Punchh Users API

openapi: 3.2.0
info:
  title: Punchh Users API
  version: '1.0'
  description: 'Operations tagged Users across 2 of this provider''s published API definitions: punchh-mobile-api-openapi.yml, punchh-platform-functions-api-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://SERVER_NAME_GOES_HERE.punchh.com
tags:
- name: Users
paths:
  /api2/mobile/users/login:
    post:
      parameters:
      - $ref: '#/components/parameters/signature'
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/Accept-Language'
      - $ref: '#/components/parameters/User-Agent'
      - $ref: '#/components/parameters/punchh-app-device-id'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  access_token:
                    $ref: '#/components/schemas/access_token-Object'
                  user:
                    $ref: '#/components/schemas/User-object'
              examples:
                default:
                  value:
                    access_token:
                      token: ACCESS_TOKEN_GOES_HERE
                      seconds_to_expire: null
                      revoked_at: null
                      refresh_token: REFRESH_TOKEN_GOES_HERE
                      scopes: []
                    user:
                      address: ''
                      anniversary: '2013-02-16'
                      avatar_remote_url: null
                      birthday: '1999-01-01'
                      city: ''
                      communicable_email: test@example.com
                      created_at: '2019-01-11T09:08:25Z'
                      email: test@example.com
                      email_verified: false
                      facebook_signup: null
                      apple_signup: null
                      apple_uid: null
                      favourite_location_ids: 306082,333070,304374
                      favourite_store_numbers: 12345,0604,1234
                      fb_uid: null
                      first_name: FIRST_NAME_GOES_HERE
                      gender: ''
                      has_generated_fb_email: false
                      last_name: LAST_NAME_GOES_HERE
                      marketing_email_subscription: true
                      marketing_pn_subscription: true
                      migrate_status: false
                      passcode_configured_for_giftcards: false
                      phone: '1111111111'
                      profile_field_answers:
                        test1: Option 1
                      referral_code: REFERRAL_CODE_GOES_HERE
                      referral_path: URL_GOES_HERE
                      secondary_email: ''
                      state: ''
                      superuser: false
                      terms_and_conditions: true
                      title: ''
                      updated_at: '2020-04-29T04:18:24Z'
                      user_as_qrcode: QR_CODE_GOES_HERE
                      user_code: P11111111
                      user_id: 111111111
                      preferred_locale: en
                      user_relations: []
                      zip_code: null
                      verification_mode: null
                      sms_subscription: false
                      apple_pass_url: APPLE_PASS_URL_GOES_HERE
                      google_pass_url: GOOGLE_PASS_URL_GOES_HERE
                      user_joined_at: '2019-01-11T09:08:25Z'
        '400':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: object
                    properties:
                      missing_required_param:
                        type: array
                        items:
                          type: string
              examples:
                Bad Request (blank email field):
                  value: "{\n  \"errors\": {\n    \"missing_required_param\": [\n      \"Required parameter missing or the value is empty: email\"\n    ]\n  }\n}"
                Bad Request (invalid language):
                  value: "{  \n   \"errors\":{  \n      \"invalid_language\":[  \n         \"Unknown/Invalid locale in Accept-Language Header. Supported locales are en-GB, es-CR, en, es.\"\n      ]\n   }\n}"
                Bad Request (missing parameter):
                  value: "{  \n   \"errors\":{  \n      \"missing_required_param\":[  \n         \"Required parameter missing or the value is empty: client\"\n      ]\n   }\n}"
        '401':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: object
                    properties:
                      unknown_client:
                        type: array
                        items:
                          type: string
              examples:
                default:
                  value:
                    errors:
                      unknown_client:
                      - Client ID is incorrect. Please check client param or contact us.
        '412':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: object
                    properties:
                      invalid_signature:
                        type: array
                        items:
                          type: string
              examples:
                application/json; charset=utf-8:
                  value:
                    errors:
                      invalid_signature:
                      - Signature doesn't match. See https://developers.punchh.com/docs/dev-portal-mobile/17c2f8eb39142-generating-x-pch-digest-header-for-mobile-ap-is
        '422':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: object
                    properties:
                      invalid_email_password:
                        type: array
                        items:
                          type: string
              examples:
                default:
                  value:
                    errors:
                      invalid_email_password:
                      - Sorry, Invalid Email/Password.
      summary: Sign in
      description: 'Logs a user into the app of a business and returns the user''s information in the response

        '
      operationId: mobile_signin
      tags:
      - Users
      x-stoplight:
        id: c1be403d96bc5
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                client:
                  type: string
                  description: OAuth client ID provided by the business
                user:
                  type: object
                  properties:
                    email:
                      type: string
                      description: Email address of the user
                    password:
                      type: string
                      description: Password of the user
                    apn_token:
                      type: string
                      description: Apple push-notification token that allows push notifications to be received on the registered device of the user
                    gcm_token:
                      type: string
                      description: Google Cloud Messaging (GCM) or Firebase Cloud Messaging (FCM) token that allows push notifications to be received on the registered device of the user
              required:
              - client
            examples:
              default:
                value:
                  client: CLIENT_GOES_HERE
                  user:
                    email: test@example.com
                    password: PASSWORD_GOES_HERE
    servers:
    - url: https://SERVER_NAME_GOES_HERE.punchh.com
  /api2/mobile/users/connect_with_facebook:
    post:
      responses:
        '200':
          description: The response returns basic details about the user account, including the access token that you must use to authenticate other API calls on the user's behalf.
          content:
            application/json:
              schema:
                type: object
                properties:
                  access_token:
                    $ref: '#/components/schemas/access_token-Object'
                  user:
                    $ref: '#/components/schemas/User-object'
              examples:
                default:
                  value:
                    access_token:
                      token: ACCESS_TOKEN_GOES_HERE
                      seconds_to_expire: null
                      revoked_at: null
                      refresh_token: REFRESH_TOKEN_GOES_HERE
                      scopes:
                      - wifi
                    user:
                      address: ADDRESS_GOES_HERE
                      avatar_remote_url: null
                      birthday: '1999-01-01'
                      communicable_email: test@example.com
                      city: Mountain View
                      created_at: '2016-03-16T11:40:07+00:00'
                      email: test@example.com
                      email_verified: false
                      facebook_signup: true
                      favourite_location_ids: '304155'
                      favourite_store_numbers: '1023'
                      fb_uid: FB_UID_GOES_HERE
                      first_name: FIRST_NAME_GOES_HERE
                      gender: male
                      last_name: LAST_NAME_GOES_HERE
                      marketing_email_subscription: true
                      marketing_pn_subscription: true
                      migrate_status: false
                      passcode_configured_for_giftcards: false
                      phone: '1111111111'
                      profile_field_answers: {}
                      referral_code: REFERRAL_CODE_GOES_HERE
                      referral_path: URL_GOES_HERE
                      secondary_email: test@example.com
                      state: California
                      superuser: false
                      terms_and_conditions: false
                      title: null
                      updated_at: '2016-03-16T11:40:08+00:00'
                      user_as_barcode: '1111111'
                      user_as_qrcode: QR_CODE_GOES_HERE
                      user_code: P11111111
                      user_id: 111111111
                      user_relations: []
                      zip_code: '30201'
                      anniversary: '2013-07-13'
                      verification_mode: null
                      apple_signup: null
                      apple_uid: null
                      has_generated_fb_email: false
                      sms_subscription: true
                      apple_pass_url: APPLE_PASS_URL_GOES_HERE
                      google_pass_url: GOOGLE_PASS_URL_GOES_HERE
                      age_verified_status: true
                      user_joined_at: '2016-03-16T11:40:07+00:00'
        '412':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  code:
                    type: integer
              examples:
                default:
                  value:
                    message: Sending invalid Signature
                    code: 412
        '422':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  code:
                    type: integer
              examples:
                default:
                  value:
                    message: Sending invalid Entity
                    code: 422
      summary: Log in With Facebook
      description: 'This API is invoked when a user registers on a business app using Facebook ID, email address, first name, last name, etc. '
      tags:
      - Users
      operationId: mobile_connect_with_facebook
      parameters:
      - $ref: '#/components/parameters/signature'
      - $ref: '#/components/parameters/Accept'
      - $ref: '#/components/parameters/Accept-Language'
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/User-Agent'
      x-stoplight:
        id: a6f1c0055e695
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                client:
                  type: string
                  description: OAuth client ID provided by the business
                user:
                  type: object
                  properties:
                    facebook_access_token:
                      type: string
                      description: Access token received from Facebook
                    apn_token:
                      type: string
                      description: Apple push-notification token that allows push notifications to be received on the registered device of the user
                    gcm_token:
                      type: string
                      description: Google Cloud Manager (GCM) token that allows push notifications to be received on the registered device of the user
                    signup_channel:
                      type: string
                      description: Sign-up channel for user registration. Possible values are `WebFacebook` or `MobileFacebook`.
                    age_verified_status:
                      type: boolean
                      x-stoplight:
                        id: zuuvbxdbfmpyx
                      description: 'Whether or not the user has undergone age verification by Koupon Media. Possible Values: true, false. The parameter is accepted in the request if Koupon Media is selected as the age verification adapter for the business in the Punchh platform. Contact your Punchh representative to update this configuration.'
                  required:
                  - facebook_access_token
              required:
              - client
            examples:
              default:
                value:
                  client: CLIENT_GOES_HERE
                  user:
                    facebook_access_token: ACCESS_TOKEN_GOES_HERE
                    apn_token: APN_TOKEN_GOES_HERE
                    gcm_token: GCM_TOKEN_GOES_HERE
                    signup_channel: MobileFacebook
                    age_verified_status: true
        description: ''
    servers:
    - url: https://SERVER_NAME_GOES_HERE.punchh.com
  /api2/mobile/apple_registrations:
    post:
      responses:
        '200':
          description: The response returns basic details about the user account, including the access token that you must use to authenticate other API calls on the user's behalf.
          content:
            application/json:
              schema:
                type: object
                properties:
                  access_token:
                    $ref: '#/components/schemas/access_token-Object'
                  user:
                    $ref: '#/components/schemas/User-object'
              examples:
                default:
                  value:
                    access_token:
                      token: ACCESS_TOKEN_GOES_HERE
                      seconds_to_expire: null
                      revoked_at: null
                      refresh_token: REFRESH_TOKEN_GOES_HERE
                      scopes: []
                    user:
                      address: null
                      anniversary: null
                      avatar_remote_url: null
                      birthday: null
                      city: null
                      communicable_email: test@example.com
                      created_at: '2019-09-05T03:39:10-07:00'
                      email: test@example.com
                      email_verified: false
                      facebook_signup: null
                      apple_signup: null
                      apple_uid: APPLE_UID_GOES_HERE
                      favourite_location_ids: '315783'
                      favourite_store_numbers: ''
                      fb_uid: FB_UID_GOES_HERE
                      first_name: FIRST_NAME_GOES_HERE
                      gender: Male
                      has_generated_fb_email: false
                      last_name: LAST_NAME_GOES_HERE
                      marketing_email_subscription: true
                      marketing_pn_subscription: true
                      migrate_status: false
                      passcode_configured_for_giftcards: false
                      phone: null
                      profile_field_answers: {}
                      referral_code: REFERRAL_CODE_GOES_HERE
                      referral_path: URL_GOES_HERE
                      secondary_email: null
                      state: null
                      superuser: false
                      terms_and_conditions: false
                      title: null
                      updated_at: '2019-09-17T04:35:56-07:00'
                      user_as_qrcode: QR_CODE_GOES_HERE
                      user_code: P11111111
                      user_id: 111111111
                      preferred_locale: en
                      user_relations: []
                      zip_code: null
                      verification_mode: null
                      sms_subscription: false
                      apple_pass_url: APPLE_PASS_URL_GOES_HERE
                      google_pass_url: GOOGLE_PASS_URL_GOES_HERE
                      age_verified_status: true
                      user_joined_at: '2019-09-05T03:39:10-07:00'
      summary: Log in With Apple
      description: 'A user can sign in with Apple using a random email ID generated by Apple.


        ## Session Behavior After Users Revoke App Access From their Apple ID

        When a user authenticates using Apple Sign-In, Punchh generates its own access token that is independent of Apple''s authorization. If the user later revokes the app''s access through their Apple ID settings (Settings > Apple ID > Password & Security > Apps Using Apple ID), the active Punchh session is not affected, and the user is not automatically logged out.


        This behavior occurs because Apple Sign-In is used only during the initial authentication process. Apple does not provide a callback or notification to Punchh when a user revokes access to the app.


        As a result, the user remains signed in until their Punchh session expires or they explicitly log out of the app. If the user logs out and subsequently attempts to sign in again using Apple Sign-In, Apple will prompt the user to reauthorize the app to use the their Apple ID for authentication before the sign-in process can be completed.

        '
      operationId: mobile_login_with_apple
      tags:
      - Users
      parameters:
      - $ref: '#/components/parameters/signature'
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/Accept'
      - $ref: '#/components/parameters/User-Agent'
      x-stoplight:
        id: a39b0ccb639cb
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                client:
                  type: string
                  x-stoplight:
                    id: 8etz5eob70kcd
                  description: OAuth client ID provided by the business
                user:
                  type: object
                  properties:
                    first_name:
                      type: string
                      description: First name of the user
                    last_name:
                      type: string
                      description: Last name of the user
                    gender:
                      type: string
                      description: Gender of the user
                    external_source:
                      type: string
                      description: External source name (e.g., "Apple", "Salesforce", or whatever the name of the user account source is)
                    external_source_id:
                      type: string
                      description: ID of the customer in the mentioned external source name (provided in the `external_source` request parameter)
                    authorization_code:
                      type: string
                      description: Unique authorization code generated by Apple for every request (expires after 5 minutes)
                    age_verified_status:
                      type: boolean
                      x-stoplight:
                        id: ms49bv8zek773
                      description: 'Whether or not the user has undergone age verification by Koupon Media. Possible Values: true, false. The parameter is accepted in the request if Koupon Media is selected as the age verification adapter for the business in the Punchh platform. Contact your Punchh representative to update this configuration.'
                  required:
                  - first_name
                  - last_name
              required:
              - client
            examples:
              default:
                value:
                  client: CLIENT_KEY_GOES_HERE
                  user:
                    first_name: FIRST_NAME_GOES_HERE
                    last_name: LAST_NAME_GOES_HERE
                    gender: Male
                    external_source: SOURCE_GOES_HERE
                    external_source_id: SOURCE_ID_GOES_HERE
                    authorization_code: AUTHORIZATION_CODE_GOES_HERE
                    age_verified_status: true
        description: ''
    servers:
    - url: https://SERVER_NAME_GOES_HERE.punchh.com
  /api2/mobile/users/logout:
    delete:
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties: {}
        '400':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: object
                    properties:
                      invalid_language:
                        type: array
                        items:
                          type: string
              examples:
                default:
                  value:
                    errors:
                      invalid_language:
                      - Unknown/Invalid locale in Accept-Language Header. Supported locales are en-GB, es-CR, en, es.
        '401':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: object
                    properties:
                      unknown_client:
                        type: array
                        items:
                          type: string
              examples:
                default:
                  value:
                    errors:
                      unknown_client:
                      - Client ID is incorrect. Please check client param or contact us.
        '403':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: object
                    properties:
                      invalid_access_token:
                        type: array
                        items:
                          type: string
              examples:
                default:
                  value:
                    errors:
                      invalid_access_token:
                      - 'Error: access_token not found or is incorrect! Valid access_token of the user required.'
        '422':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: object
                    properties:
                      access_token:
                        type: string
              examples:
                default:
                  value:
                    errors:
                      access_token: Invalid access_token or cannot be blank
      summary: Log out
      description: Logs a user out of the app of a business, ending the current user session
      operationId: mobile_logout
      tags:
      - Users
      parameters:
      - $ref: '#/components/parameters/signature'
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/Accept'
      - $ref: '#/components/parameters/Accept-Language'
      - $ref: '#/components/parameters/punchh-app-device-id'
      - $ref: '#/components/parameters/User-Agent'
      - $ref: '#/components/parameters/Authorization'
      x-stoplight:
        id: 2bcfa21492491
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                client:
                  type: string
                  description: OAuth client ID provided by the business
                access_token:
                  type: string
                  description: Token issued to the user after logging into the app of the business
                gcm_token:
                  type: string
                  description: Google Cloud Messaging (GCM) or Firebase Cloud Messaging (FCM) token that allows push notifications to be received on the registered device of the user
              required:
              - client
            examples:
              default:
                value:
                  client: CLIENT_GOES_HERE
                  access_token: ACCESS_TOKEN_GOES_HERE
    servers:
    - url: https://SERVER_NAME_GOES_HERE.punchh.com
  /api2/mobile/users/profile:
    get:
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  access_token:
                    $ref: '#/components/schemas/access_token-Object'
                  user:
                    $ref: '#/components/schemas/User-object'
              examples:
                default:
                  value:
                    access_token:
                      token: ACCESS_TOKEN_GOES_HERE
                      seconds_to_expire: null
                      revoked_at: null
                    user:
                      address: ADDRESS_GOES_HERE
                      avatar_remote_url: null
                      birthday: '1999-01-01'
                      communicable_email: test@example.com
                      city: Mountain View
                      created_at: '2016-03-16T11:40:07+00:00'
                      email: test@example.com
                      email_verified: false
                      facebook_signup: null
                      favourite_location_ids: '304155'
                      favourite_store_numbers: '1023'
                      fb_uid: null
                      first_name: FIRST_NAME_GOES_HERE
                      gender: male
                      last_name: LAST_NAME_GOES_HERE
                      marketing_email_subscription: true
                      marketing_pn_subscription: true
                      migrate_status: false
                      passcode_configured_for_giftcards: false
                      phone: '1111111111'
                      profile_field_answers:
                        favorite_sports: Football
                        favourite: Arizona Cardinals
                        favs: Air Force
                        fava: Academy
                        favb: Atlanta Hawks
                        favd: Arizona Diamondbacks
                        fave: England - Arsenal
                        favf: Anaheim Ducks
                      referral_code: REFERRAL_CODE_GOES_HERE
                      referral_path: URL_GOES_HERE
                      secondary_email: test@example.com
                      state: California
                      superuser: false
                      terms_and_conditions: false
                      title: null
                      updated_at: '2016-03-21T08:02:44+00:00'
                      user_as_barcode: '1111111'
                      user_as_qrcode: QR_CODE_GOES_HERE
                      user_code: P11111111
                      user_id: 111111111
                      user_relations:
                      - id: 111111111
                        relation: spouse
                        name: FIRST_NAME_GOES_HERE LAST_NAME_GOES_HERE
                        birthday: '1999-01-01'
                        created_at: '2016-03-18T12:32:13+00:00'
                        updated_at: '2016-03-18T12:32:13+00:00'
                      zip_code: '30201'
                      anniversary: '2013-07-13'
                      verification_mode: null
                      apple_signup: null
                      apple_uid: null
                      has_generated_fb_email: false
                      sms_subscription: true
                      apple_pass_url: APPLE_PASS_URL_GOES_HERE
                      google_pass_url: GOOGLE_PASS_URL_GOES_HERE
                      age_verified_status: true
                      account_created_at: '2020-03-27T04:34:35-05:00'
                      user_joined_at: '2016-03-16T11:40:07+00:00'
      summary: Fetch User Information
      description: Returns a user's details
      operationId: mobile_fetch_user_information
      tags:
      - Users
      parameters:
      - $ref: '#/components/parameters/Authorization'
      - $ref: '#/components/parameters/signature'
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/Accept'
      - $ref: '#/components/parameters/User-Agent'
      - $ref: '#/components/parameters/punchh-app-device-id'
      x-stoplight:
        id: fe0fd0660fed4
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                client:
                  type: string
                  description: OAuth client ID provided by the business
              required:
              - client
            examples:
              default:
                value:
                  client: CLIENT_KEY_GOES_HERE
    servers:
    - url: https://SERVER_NAME_GOES_HERE.punchh.com
  /api2/mobile/users:
    put:
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  access_token:
                    $ref: '#/components/schemas/access_token-Object'
                  user:
                    $ref: '#/components/schemas/User-object'
              examples:
                default:
                  value:
                    access_token:
                      token: ACCESS_TOKEN_GOES_HERE
                      seconds_to_expire: null
                      revoked_at: null
                    user:
                      address: ''
                      avatar_remote_url: IMAGE_URL_GOES_HERE
                      birthday: '1999-01-01'
                      communicable_email: test@example.com
                      city: ''
                      created_at: '2015-11-02T18:14:32+00:00'
                      email: test@example.com
                      email_verified: false
                      facebook_signup: null
                      favourite_locations: ''
                      favourite_store_numbers: ''
                      fb_uid: FB_UID_GOES_HERE
                      first_name: FIRST_NAME_GOES_HERE
                      gender: male
                      last_name: L

# --- truncated at 32 KB (363 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/punchh/refs/heads/main/openapi/punchh-users-api-openapi.yml