Punchh Users API

openapi: 3.0.3
info:
  title: PAR Punchh Mobile Check-In Users API
  version: '1.0'
  description: The PAR Punchh Mobile API powers business-branded mobile apps and websites, exposing guest-facing loyalty functions such as user registration and sign-in, profile management, check-ins/transactions, and offer management. Access requires partner certification and business-issued OAuth client credentials. All calls are signed with an HMAC-SHA256 `x-pch-digest` header. Base URLs (sandbox and production) are provided by a Punchh representative.
  x-generated-from: documentation
  x-last-validated: '2026-06-03'
  contact:
    name: PAR Developer Portal
    url: https://developers.partech.com/
servers:
- url: https://{server_name}.punchh.com
  description: Punchh environment host (provided by your Punchh representative)
  variables:
    server_name:
      default: SERVER_NAME_GOES_HERE
      description: Environment-specific host name
tags:
- name: Users
  description: Guest registration, authentication, and profile management.
paths:
  /api2/mobile/users:
    post:
      operationId: createMobileUser
      summary: Create User
      description: Registers a new guest account. Requires the business OAuth client ID and basic profile fields.
      tags:
      - Users
      security:
      - PunchhDigest: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
            examples:
              CreatemobileuserRequestExample:
                summary: Default createMobileUser request
                x-microcks-default: true
                value:
                  client: business_client_key
                  email: jsmith@example.com
                  password: example
                  first_name: Jane Smith
      responses:
        '200':
          description: User created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserSession'
              examples:
                Createmobileuser200Example:
                  summary: Default createMobileUser 200 response
                  x-microcks-default: true
                  value:
                    access_token:
                      token: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4
                      refresh_token: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4
                      seconds_to_expire: example
                      scopes:
                      - example
                    user: {}
        '400':
          description: Bad Request.
        '422':
          description: Unprocessable Entity.
      x-source-url: https://developers.partech.com/docs/dev-portal-mobile/5f1a47e9bd79f-make-your-first-mobile-api-call
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      operationId: updateMobileUserProfile
      summary: Update User Profile
      description: Updates the authenticated guest's profile. Birthday may be updated only once due to fraud protections.
      tags:
      - Users
      security:
      - PunchhBearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUserProfileRequest'
            examples:
              UpdatemobileuserprofileRequestExample:
                summary: Default updateMobileUserProfile request
                x-microcks-default: true
                value:
                  client: business_client_key
                  user:
                    first_name: Jane Smith
                    last_name: Jane Smith
                    email: jsmith@example.com
                    phone: '+15551234567'
                    password: example
                    password_confirmation: example
                    current_password: example
                    birthday: example
                    anniversary: example
                    gender: female
                    address: 123 Market St
                    city: San Francisco
                    state: CA
                    zip_code: CODE-AB12CD
                    avatar_remote_url: https://portal.example.com/path/abc123
                    favourite_location_ids:
                    - 123
                    apn_token: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4
                    gcm_token: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4
                    age_verified_status: active
      responses:
        '200':
          description: Updated user object with new access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserSession'
              examples:
                Updatemobileuserprofile200Example:
                  summary: Default updateMobileUserProfile 200 response
                  x-microcks-default: true
                  value:
                    access_token:
                      token: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4
                      refresh_token: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4
                      seconds_to_expire: example
                      scopes:
                      - example
                    user: {}
        '401':
          description: Unauthorized.
        '422':
          description: Unprocessable Entity.
      x-source-url: https://developers.partech.com/docs/dev-portal-mobile/c9b928e35a6f3-update-user-profile
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api2/mobile/users/login:
    post:
      operationId: loginMobileUser
      summary: Sign In
      description: Authenticates a guest with email and password and returns an access token, refresh token, and the user profile.
      tags:
      - Users
      security:
      - PunchhDigest: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
            examples:
              LoginmobileuserRequestExample:
                summary: Default loginMobileUser request
                x-microcks-default: true
                value:
                  client: business_client_key
                  user:
                    email: jsmith@example.com
                    password: example
      responses:
        '200':
          description: Authenticated session.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserSession'
              examples:
                Loginmobileuser200Example:
                  summary: Default loginMobileUser 200 response
                  x-microcks-default: true
                  value:
                    access_token:
                      token: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4
                      refresh_token: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4
                      seconds_to_expire: example
                      scopes:
                      - example
                    user: {}
        '400':
          description: Bad Request.
        '401':
          description: Unauthorized.
        '412':
          description: Precondition Failed.
        '422':
          description: Unprocessable Entity.
      x-source-url: https://developers.partech.com/docs/dev-portal-mobile/apis/mobile-api/tag/users/post/api2/mobile/users/login
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/pos/users/search:
    get:
      operationId: searchPosUser
      summary: User Look-Up and Fetch Balance
      description: Looks up a guest and returns account details and loyalty balances. Provide exactly one identifier (phone number, email, QR code, single scan code, redemption code, card number, or Apple NFC token).
      tags:
      - Users
      security:
      - PunchhPosToken: []
      parameters:
      - name: phone_number
        in: query
        required: false
        description: Guest phone number.
        schema:
          type: string
      - name: email
        in: query
        required: false
        description: Guest email address.
        schema:
          type: string
          format: email
      - name: user_as_qrcode
        in: query
        required: false
        description: Guest QR code value.
        schema:
          type: string
      - name: single_scan_code
        in: query
        required: false
        description: Single scan code value.
        schema:
          type: string
      - name: redemption_code
        in: query
        required: false
        description: Redemption code value.
        schema:
          type: string
      - name: card_number
        in: query
        required: false
        description: Loyalty/gift card number.
        schema:
          type: string
      responses:
        '200':
          description: Guest account details and loyalty balances.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PosUser'
              examples:
                Searchposuser200Example:
                  summary: Default searchPosUser 200 response
                  x-microcks-default: true
                  value:
                    phone_number: '+15551234567'
                    email: jsmith@example.com
                    first_name: Jane Smith
                    last_name: Jane Smith
                    card_number: example
                    balances: {}
        '401':
          description: Unauthorized.
        '404':
          description: User not found.
      x-source-url: https://developers.partech.com/docs/dev-portal-pos/1fbfdfdd05a86-make-your-first-pos-api-call
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/pos/users:
    post:
      operationId: createPosUser
      summary: Create New User
      description: Creates a new guest account from the point of sale.
      tags:
      - Users
      security:
      - PunchhPosToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PosUser'
            examples:
              CreateposuserRequestExample:
                summary: Default createPosUser request
                x-microcks-default: true
                value:
                  phone_number: '+15551234567'
                  email: jsmith@example.com
                  first_name: Jane Smith
                  last_name: Jane Smith
                  card_number: example
                  balances: {}
      responses:
        '200':
          description: User created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PosUser'
              examples:
                Createposuser200Example:
                  summary: Default createPosUser 200 response
                  x-microcks-default: true
                  value:
                    phone_number: '+15551234567'
                    email: jsmith@example.com
                    first_name: Jane Smith
                    last_name: Jane Smith
                    card_number: example
                    balances: {}
        '401':
          description: Unauthorized.
        '422':
          description: Unprocessable Entity.
      x-source-url: https://developers.partech.com/docs/dev-portal-pos/1fbfdfdd05a86-make-your-first-pos-api-call
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    LoginRequest:
      title: LoginRequest
      type: object
      x-schema-source: documentation
      required:
      - client
      - user
      properties:
        client:
          type: string
          description: OAuth client ID provided by the business.
          example: business_client_key
        user:
          type: object
          required:
          - email
          - password
          properties:
            email:
              type: string
              format: email
              example: jsmith@example.com
            password:
              type: string
              example: example
    PosUser:
      title: PosUser
      type: object
      x-schema-source: documentation
      properties:
        phone_number:
          type: string
          example: '+15551234567'
        email:
          type: string
          format: email
          example: jsmith@example.com
        first_name:
          type: string
          example: Jane Smith
        last_name:
          type: string
          example: Jane Smith
        card_number:
          type: string
          example: example
        balances:
          type: object
          description: Loyalty point and reward balances.
    AccessToken:
      title: AccessToken
      type: object
      x-schema-source: documentation
      properties:
        token:
          type: string
          example: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4
        refresh_token:
          type: string
          example: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4
        seconds_to_expire:
          type: integer
          example: example
        scopes:
          type: array
          items:
            type: string
    UpdateUserProfileRequest:
      title: UpdateUserProfileRequest
      type: object
      x-schema-source: documentation
      required:
      - client
      properties:
        client:
          type: string
          description: OAuth client ID provided by the business.
          example: business_client_key
        user:
          type: object
          properties:
            first_name:
              type: string
              example: Jane Smith
            last_name:
              type: string
              example: Jane Smith
            email:
              type: string
              format: email
              example: jsmith@example.com
            phone:
              type: string
              example: '+15551234567'
            password:
              type: string
              example: example
            password_confirmation:
              type: string
              example: example
            current_password:
              type: string
              example: example
            birthday:
              type: string
              example: example
            anniversary:
              type: string
              example: example
            gender:
              type: string
              example: female
            address:
              type: string
              example: 123 Market St
            city:
              type: string
              example: San Francisco
            state:
              type: string
              example: CA
            zip_code:
              type: string
              example: CODE-AB12CD
            avatar_remote_url:
              type: string
              example: https://portal.example.com/path/abc123
            favourite_location_ids:
              type: array
              items:
                type: integer
            apn_token:
              type: string
              example: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4
            gcm_token:
              type: string
              example: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4
            age_verified_status:
              type: string
              example: active
    CreateUserRequest:
      title: CreateUserRequest
      type: object
      x-schema-source: documentation
      required:
      - client
      - email
      - password
      properties:
        client:
          type: string
          description: OAuth client ID provided by the business.
          example: business_client_key
        email:
          type: string
          format: email
          example: jsmith@example.com
        password:
          type: string
          example: example
        first_name:
          type: string
          example: Jane Smith
    UserSession:
      title: UserSession
      type: object
      x-schema-source: documentation
      properties:
        access_token:
          $ref: '#/components/schemas/AccessToken'
        user:
          type: object
          description: Guest profile with loyalty information and generated codes.
  securitySchemes:
    PunchhBearer:
      type: http
      scheme: bearer
      description: Bearer access token obtained via Sign In. Calls must also include an `x-pch-digest` HMAC-SHA256 signature header and a `punchh-app-device-id` header.
    PunchhDigest:
      type: apiKey
      in: header
      name: x-pch-digest
      description: HMAC-SHA256 request signature. Unauthenticated mobile calls also pass the business OAuth `client` id in the request body.