Punchh User Sign-up and SSO API

openapi: 3.2.0
info:
  title: Online Ordering and SSO User Sign-up and SSO API
  version: '1.0'
  description: "The Punchh SSO API endpoints provide user-management functions such as login, registration, forgot password, and connect with Facebook for users on the Punchh loyalty platform. You can also fetch user-specific information such as rewards or point balances. \n\nThe Punchh Online Ordering API endpoints enable users to earn and redeem rewards for online orders."
  contact:
    name: Punchh Dev Support
    url: https://developers.punchh.com
servers:
- url: https://SERVER_NAME_GOES_HERE.punchh.com
tags:
- name: User Sign-up and SSO
paths:
  /api/auth/customers.json:
    post:
      responses:
        '201':
          description: Created - The response returns basic details about the user account, including the authentication token that you must use to authenticate other API calls on the user's behalf.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/user-object'
              examples:
                default:
                  value:
                    address_line1: ADDRESS_GOES_HERE
                    anniversary: null
                    avatar_remote_url: null
                    birthday: null
                    city: ''
                    created_at: '2016-10-10T07:19:19Z'
                    email: test@example.com
                    email_verified: false
                    fb_uid: ''
                    first_name: FIRST_NAME_GOES_HERE
                    gender: ''
                    id: 111111111
                    last_name: User
                    state: ''
                    updated_at: '2017-10-11T16:03:19Z'
                    zip_code: '25110'
                    allow_multiple: true
                    authentication_token: AUTHENTICATION_TOKEN_GOES_HERE
                    favourite_locations: '308052'
                    favourite_store_numbers: '2310'
                    marketing_email_subscription: true
                    marketing_pn_subscription: true
                    passcode_configured: false
                    profile_field_answers: {}
                    referral_code: REFERRAL_CODE_GOES_HERE
                    referral_path: URL_GOES_HERE
                    secondary_email: ''
                    terms_and_conditions: false
                    title: ''
                    user_as_barcode: '1111111'
                    user_as_qrcode: QR_CODE_GOES_HERE
                    user_code: P11111111
                    user_id: 111111111
                    user_relations: []
                    wants_menu_notifications: false
                    work_zip_code: null
                    mindbody_client_id: null
                    preferred_locale: en
                    phone: ''
                    migrate_status: false
                    email_unsubscribe: false
                    allow_push_notifications: true
                    facebook_signup: false
                    communicable_email: test@example.com
                    access_token: null
                    expiration_date: '2018-07-31'
                    user_joined_at: '2022-11-01T19:17:44Z'
                    sms_subscription: false
                    age_verified_status: true
        '400':
          description: Bad Request - The API returns a 400 response code if the user's age is not verified, thereby blocking the access to age-restricted content and prompting the user to complete the age verification process.
          content:
            application/json:
              schema:
                type: object
                properties: {}
        '412':
          description: Sending invalid Signature
          content:
            application/json:
              schema:
                type: object
              examples:
                default:
                  value: ''
        '422':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: object
                    properties:
                      device_already_shared:
                        type: array
                        items:
                          type: string
              examples:
                default:
                  value:
                    errors:
                      device_already_shared:
                      - with maximum number of guests allowed.
      summary: Create New User
      description: 'Sign up a new user by using information such as email, first name, last name, birthday, anniversary, password, etc. This will create/register the new user in the Punchh system.


        **NOTE**


        If the business is using a referral code, it is mandatory to pass the first_name and last_name of the guest as the referral code will be generated from first_name, last_name, and some random characters. Also, if you do not pass the first_name or the last_name, the API response may be delayed or time out.


        ### Using Referral Code As Invite Code in the Sign-up Process

        When a user signs up using the Create New User API, the API returns a referral code within the user object. The user can share this code with non-loyalty users to invite them to join the business loyalty program.


        When a referred user signs up and enters the shared referral code, this `referral_code` must be passed in the `invite_code` request parameter when calling the Create New User API.'
      operationId: sso_signup
      parameters:
      - $ref: '#/components/parameters/content_type'
      - $ref: '#/components/parameters/Accept'
      - $ref: '#/components/parameters/User-Agent'
      - $ref: '#/components/parameters/Signature'
      tags:
      - User Sign-up and SSO
      x-stoplight:
        id: 58f18dfdd2a3d
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                user:
                  type: object
                  properties:
                    email:
                      type: string
                      description: Email address of the user for sign-up
                    first_name:
                      type: string
                      description: 'First name of the user (always recommended)

                        '
                    last_name:
                      type: string
                      description: 'Last name of the user (always recommended)

                        '
                    password:
                      type: string
                      description: Password for sign-up. Must be at least 8 characters in length.
                    birthday:
                      type: string
                      enum:
                      - YYYY-MM-DD
                      format: date
                      description: 'Birthday of the user, in YYYY-MM-DD format

                        '
                    anniversary:
                      type: string
                      description: Wedding anniversary date of the user, in YYYY-MM-DD format
                      enum:
                      - YYYY-MM-DD
                      format: date
                    external_source:
                      type: string
                      enum:
                      - SOURCE_GOES_HERE
                      description: "External source name (third-party IDP). Possible values for external_source are salesforce, customer_id, mparticle, azure, aws_cognito, auth0, and ext_idp. If you are using a different one, please reach out to your implementation manager to add a new value. The values are case-sensitive. \n"
                    external_source_id:
                      type: string
                      description: ID of the customer in the mentioned external source name (external_source), a unique identifier generated by the third-party IDP (GUID format).
                    send_compliance_sms:
                      type: boolean
                      description: Send true to trigger compliance/opt-in SMS message for the user.
                    signup_channel:
                      type: string
                      enum:
                      - MobileEmail
                      - MobileFacebook
                      - POS
                      - WebEmail
                      - WebFacebook
                      - eclub
                      - OnlineOrder
                      - Chatbot
                      - Wifi
                      - MobileApple
                      description: 'Use this field to overrride the default channel of "OnlineOrder". Possible values are: `MobileEmail`, `MobileFacebook`, `POS`, `WebEmail`, `WebFacebook`, `eClub`, `OnlineOrder`, `Chatbot`, `Wifi`, `MobileApple`.'
                    password_confirmation:
                      type: string
                      description: Password confirmation for sign-up
                    fav_location_id:
                      type: string
                      description: 'Comma-separated list of the user''s favorite location IDs. NOTE: Location IDs are different from store numbers.'
                    phone:
                      type: string
                      description: Phone number of the user
                    apn_token:
                      type: string
                      description: Apple Push Notification (APN) token
                    apn_token_readability:
                      type: boolean
                      description: Whether Apple Push Notification (APN) is enabled on iOS mobile app or not
                    gcm_token:
                      type: string
                      description: Google Cloud Messaging (GCM) token
                    gcm_token_readability:
                      type: boolean
                      description: Whether Google Cloud Messaging (GCM) is enabled on the Android mobile app or not
                    card_number:
                      type: string
                      description: Card number of the user
                    epin_number:
                      type: string
                      description: Epin number of the user
                    unsubscribed:
                      type: boolean
                      description: 'Whether the user has unsubscribed from emails

                        '
                    secondary_email:
                      type: string
                      description: Secondary email address of the user
                    app_device_id:
                      type: string
                      description: Device ID of the mobile app. It can also be sent in the header via the punchh-app-device-id field.
                    city:
                      type: string
                      description: 'City where the user lives

                        '
                    zip_code:
                      type: string
                      description: Zip code where the user lives
                    address_line1:
                      type: string
                      description: 'Address information (part 1) of the user

                        '
                    address_line2:
                      type: string
                      description: 'Address information (part 2) of the user

                        '
                    state:
                      type: string
                      description: State where the user lives
                    office_phone:
                      type: string
                      description: Phone number of the user's office
                    cell_phone:
                      type: string
                      description: Cell phone number of the user
                    website:
                      type: string
                      description: Website of the user
                    twitter:
                      type: string
                      description: Twitter page of the user
                    gender:
                      type: string
                      description: Gender of the user (e.g., male or female)
                    invite_code:
                      type: string
                      description: 'The referral code of the user making the referral.  When a user signs up for the business loyalty program using the Create New User API, the API returns a referral code within the user object.


                        When a referred user signs up and enters the shared referral code, this `referral_code` must be passed in the `invite_code` request parameter when calling the Create New User API.'
                    work_zip_code:
                      type: string
                      description: 'Zip code of the user''s office

                        '
                    terms_and_conditions:
                      type:
                      - string
                      - boolean
                      description: 'Whether the user has agreed to the terms and conditions to use the app as per the configuration

                        '
                    user_relations:
                      $ref: '#/components/schemas/user-relations'
                    profile_field_answers:
                      $ref: '#/components/schemas/profile_field_answers'
                    marketing_email_subscription:
                      type: boolean
                      description: Whether the user has subscribed to receive marketing emails or not. This is mandatory if Explicit Opt-in is enabled in the Punchh platform.
                    marketing_pn_subscription:
                      type: boolean
                      description: Whether the user has subscribed to receive marketing push notifications or not
                    age_verified_status:
                      type: boolean
                      x-stoplight:
                        id: nezt0i39gju4r
                      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:
                  - email
                  - password
                client:
                  type: string
                  description: Client key of the business
              required:
              - client
            examples:
              default:
                value:
                  user:
                    email: test@example.com
                    first_name: FIRST_NAME_GOES_HERE
                    last_name: LAST_NAME_GOES_HERE
                    password: PASSWORD_GOES_HERE
                    birthday: '1992-10-03'
                    anniversary: '1996-10-03'
                    phone: '1111111111'
                    terms_and_conditions: true
                    send_compliance_sms: true
                    external_source: SOURCE_GOES_HERE
                    external_source_id: SOURCE_ID_GOES_HERE
                    signup_channel: WebEmail
                    gender: male
                    city: Mountain View
                    secondary_email: test@example.com
                    state: California
                    zip_code: '30201'
                    invite_code: INVITE_CODE_GOES_HERE
                    age_verified_status: true
                  client: CLIENT_GOES_HERE
  /api/auth/customers/sign_in:
    post:
      responses:
        '200':
          description: The response returns basic details about the user account, including the authentication token that you must use to authenticate other API calls on the user's behalf.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/user-object'
              examples:
                default:
                  value:
                    address_line1: ADDRESS_GOES_HERE
                    anniversary: null
                    avatar_remote_url: null
                    birthday: null
                    city: ''
                    created_at: '2016-10-10T07:19:19Z'
                    email: test@example.com
                    email_verified: false
                    fb_uid: ''
                    first_name: FIRST_NAME_GOES_HERE
                    gender: ''
                    id: 111111111
                    last_name: LAST_NAME_GOES_HERE
                    state: ''
                    updated_at: '2017-10-11T16:03:19Z'
                    zip_code: '25110'
                    allow_multiple: true
                    authentication_token: AUTHENTICATION_TOKEN_GOES_HERE
                    favourite_locations: '308052'
                    favourite_store_numbers: '2310'
                    marketing_email_subscription: true
                    marketing_pn_subscription: true
                    passcode_configured: false
                    profile_field_answers:
                      children: '0'
                      dish: Pizza
                    referral_code: REFERRAL_CODE_GOES_HERE
                    referral_path: URL_GOES_HERE
                    secondary_email: ''
                    terms_and_conditions: false
                    title: ''
                    user_as_barcode: '1111111'
                    user_as_qrcode: QR_CODE_GOES_HERE
                    user_code: P11111111
                    user_id: 111111111
                    user_relations: []
                    wants_menu_notifications: false
                    work_zip_code: null
                    mindbody_client_id: null
                    preferred_locale: en
                    phone: ''
                    migrate_status: false
                    email_unsubscribe: false
                    allow_push_notifications: true
                    facebook_signup: false
                    communicable_email: test@example.com
                    access_token: null
                    expiration_date: '2018-07-31'
                    user_joined_at: '2022-11-01T19:17:44Z'
                    age_verified_status: true
        '401':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
              examples:
                default:
                  value:
                    error: Incorrect information submitted. Please retry.
        '412':
          description: "{\n  \"Invalid Signature\"\n}"
        '422':
          description: '{

            Sending invalid Entity

            }'
      summary: Log in With Email and Password
      operationId: sso_login
      description: 'Log in a user with the user''s email address and password information.

        '
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/content_type'
      - $ref: '#/components/parameters/Accept'
      - $ref: '#/components/parameters/User-Agent'
      tags:
      - User Sign-up and SSO
      x-stoplight:
        id: 97dc4430bb3aa
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                user:
                  type: object
                  required:
                  - email
                  - password
                  properties:
                    email:
                      type: string
                      default: test@example.com
                      description: Email address of the user
                    password:
                      type: string
                      default: PASSWORD_GOES_HERE
                      description: Password of the user
                    age_verified_status:
                      type: boolean
                      x-stoplight:
                        id: 58201m9b6cve0
                      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. '
                client:
                  type: string
                  description: Client key of the business
              required:
              - user
              - client
            examples:
              default:
                value:
                  user:
                    email: test@example.com
                    password: PASSWORD_GOES_HERE
                    age_verified_status: true
                  client: CLIENT_GOES_HERE
  /api/auth/sso:
    post:
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  token:
                    type: object
                    properties:
                      access_token:
                        type: string
                        description: Security token that identifies the user
                  user:
                    $ref: '#/components/schemas/user-object'
              examples:
                default:
                  value:
                    token:
                      access_token: ACCESS_TOKEN_GOES_HERE
                    user:
                      anniversary: null
                      avatar_remote_url: null
                      birthday: null
                      created_at: '2015-08-18T13:53:06Z'
                      email: test@example.com
                      fb_uid: FB_UID_GOES_HERE
                      first_name: FIRST_NAME_GOES_HERE
                      gender: null
                      id: 111111111
                      last_name: LAST_NAME_GOES_HERE
                      updated_at: '2015-08-18T13:53:06Z'
                      allow_multiple: false
                      authentication_token: AUTHENTICATION_TOKEN_GOES_HERE
                      favourite_locations: ''
                      preferred_menu_items: []
                      referral_code: REFERRAL_CODE_GOES_HERE
                      referral_path: URL_GOES_HERE
                      secondary_email: null
                      user_as_barcode: '1111111'
                      user_as_qrcode: QR_CODE_GOES_HERE
                      user_relations: []
                      wants_menu_notifications: false
                      profile_field_answers: {}
                      address_line1: null
                      zip_code: null
                      phone: null
                      migrate_status: false
                      work_zip_code: null
                      email_unsubscribe: null
                      allow_push_notifications: true
                      facebook_signup: false
                      communicable_email: test@example.com
                      access_token: null
        '400':
          description: ''
        '401':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      message:
                        type: string
                      code:
                        type: string
              examples:
                default:
                  value:
                    error:
                      message: Invalid/Expired security token.
                      code: invalid_token
      summary: Create SSO Access Token
      operationId: sso_create_acces_token_for_sso
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/content_type'
      - $ref: '#/components/parameters/Accept'
      - $ref: '#/components/parameters/User-Agent'
      tags:
      - User Sign-up and SSO
      description: Generates authentication token using the security token.
      x-stoplight:
        id: aa3488b317017
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                client:
                  type: string
                  description: Client key of the business
                security_token:
                  type: string
                  description: Security token required to generate the authentication token. For more information on generating the security token, see [Mobile SSO Flow](https://developers.punchh.com/docs/dev-portal-online-ordering/9a41534336c87-sso-flow-for-web-and-mobile#mobile-sso-flow).
              required:
              - client
              - security_token
            examples:
              default:
                value:
                  client: CLIENT_GOES_HERE
                  security_token: SECURITY_TOKEN_GOES_HERE
  /api/auth/users/reset_password_token:
    post:
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  reset_password_token:
                    type: string
                    description: Token with which the user can request the password reset
                  token_expire_at:
                    type: string
                    description: Date/time when the reset password token will expire
              examples:
                default:
                  value:
                    reset_password_token: RESET_PASSWORD_TOKEN_GOES_HERE
                    token_expire_at: '2016-02-26T23:36:38Z'
        '400':
          description: ''
      operationId: sso_Get_reset_password_token_of_the_user
      summary: Get Password Reset Token
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/content_type'
      - $ref: '#/components/parameters/User-Agent'
      - $ref: '#/components/parameters/Accept'
      tags:
      - User Sign-up and SSO
      description: ''
      x-stoplight:
        id: 5e3a4b08fd4ad
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                user:
                  type: object
                  properties:
                    email:
                      type: string
                      description: Email address of the user requesting the reset password token
                  required:
                  - email
                client:
                  type: string
                  description: Client key of the business
              required:
              - client
            examples:
              default:
                value:
                  user:
                    email: guest@example.com
                  client: CLIENT_GOES_HERE
  /oauth/token:
    parameters: []
    post:
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  access_token:
                    type: string
                    description: Client instance-level access token that your application can use to retrieve the access and authentication token of the user
                  token_type:
                    type: string
                    description: Type of security token (e.g., bearer)
                  refresh_token:
                    type: string
                    description: Refresh token that the client application can use to get a new access token
                  scope:
                    type: string
                    description: Actions or data the bearer of the token is allowed to perform or access
                  created_at:
                    type: string
                    format: date-time
                    description: Date and time in epoch format
                    examples:
                    - '1695818361'
              examples:
                default:
                  value:
                    access_token: ACCESS_TOKEN_GOES_HERE
                    token_type: Bearer
                    refresh_token: REFRESH_TOKEN_GOES_HERE
                    scope: 'null'
                    created_at: '1695818361'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    examples:
                    - invalid_client
                  error_description:
                    type: string
                    examples:
                    - Client authentication failed due to unknown client, no client authentication included, or unsupported authentication method.
              examples:
                Missing authentication code parameter or code is expired:
                  value:
                    error: invalid_grant
                    error_description: The provided authorization grant is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client.
                Missing client parameter or client value is incorrect:
                  value:
                    error: invalid_client
                    error_description: Client authentication failed due to unknown client, no client authentication included, or unsupported authentication method.
                Missing redirect URI or redirect URI is incorrect:
                  value:
                    error: invalid_request
                    error_description: The request is missing a required parameter, includes an unsupported parameter value, or is otherwise malformed.
      summary: Get SSO Token
      description: 'Retrieves a client instance-level access token from your redirect URI after a successful user login through the Punchh-hosted authentication form. After you retrieve the client-level access token from this endpoint, supply it to the [Fetch User Information](/docs/dev-portal-online-ordering/b3A6NTAyODQ5NzA-fetch-user-information) API to retrieve a user-level authentication or access token. You can then use that user-level token to authenticate API calls for the remainder of the user''s session.


        **Note:** This endpoint is the second step in a multi-step authorization process. For more information, see [SSO Flow for Web and Mobile](/docs/dev-portal-online-ordering/9a41534336c87-sso-flow-for-web-and-mobile#step-2).'
      operationId: oauth_token
      parameters:
      - $ref: '#/components/parameters/Accept'
      - $ref: '#/components/parameters/content_type'
      - $ref: '#/components/parameters/User-Agent'
      - $ref: '#/components/parameters/Signature'
      tags:
      - User Sign-up and SSO
      x-stoplight:
        id: 70d60c1db9257
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                client_id:
                  type: string
                  description: OAuth client ID of the business
                client_secret:
                  type: string
                  description: OAuth client secret of the business
                redirect_uri:
                  type: string
                  description: Redirect URI configured in the OAuth app where users are sent after a successful user login through the Punchh-hosted authentication form
                grant_type:
                  type: string
                  x-stoplight:
                    id: jshu6v4hp9ek1
                  default: authorization_code
                  description: Grant type the Punchh server will use to generate the access token
                code:
                  type: string
                  description: Authorization code retrieved from the redirect URL after a successful user login. See [SSO Flow for Web and Mobile](/docs/dev-portal-online-ordering/9a41534336c87-sso-flow-for-web-and-mobile#web-sso-flow)
              required:
              - client_id
              - client_secret
              - redirect_uri
              - grant_type
              - code
            examples:
              default:
                value:
                  code: TOKEN_GOES_HERE
                  client_

# --- truncated at 32 KB (95 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/punchh/refs/heads/main/openapi/punchh-user-sign-up-and-sso-api-openapi.yml