pos_user_search

User Look-up and Fetch Balance

​

This API looks up a loyalty guest using an identifier to retrieve guest data and to assign the user to the check or transaction.

Fields Used for User Look-up

The following table summarizes the different look-up fields that are used in the request of this API endpoint. The POS makes a call using one of these identifiers (e.g., email address, phone number, QR code, or loyalty card number) to look up the loyalty user on the Punchh platform. Sending one of the query parameters (see below) is required. Note: User QR codes appear in three different ways, hence the three descriptions below.

Type Character Length Character Type How To Identify
Phone Number 10 Numeric 10 digits
Email 6-255 Alphanumeric String including @
User QR Code 2-12 Alphanumeric Starts with "P"
13-512 Alphanumeric Starts and ends with "Punchh"
8 Alphanumeric Starts with "S"
Single Scan Code 6-34 Alphanumeric Hexadecimal digits
Redemption Code 7 Numeric 7 digits
Card Number 16 Numeric 16 digits
Drive-Thru Short Code 4 Numeric/
Alphanumeric		 4 digits or string

POS Single Scan Flow (SSF) User Look-up API

Punchh supports SSF token. The SSF token is used to make payments for the purchases made at POS stores.

This token is a UUID string, which is made up of alphanumeric characters and passed in the User Look-up API request in the single_scan_code parameter. The SSF token that is generated from the guest’s mobile app is used to look up the information required for processing the payment, such as the payment mode that the user selected for the purchase, the selected discount that the user wants to redeem, and the selected tip amount.

For more information, see Single Scan Flow.

Query Parameters
  • email
    Type: string

    Email address of the user.

  • phone
    Type: string

    Phone number of the user.

  • card_number
    Type: string

    Physical loyalty card generated by Punchh.

  • user_as_qrcode
    Type: string

    QR code of the user.

  • single_scan_code
    Type: string

    Single scan code of the user to be used in single scan flow.

  • redemption_code
    Type: string

    Redemption code of the user as generated on the app or web.

  • apple_nfc_data
    Type: string

    User identifier that enables look-up of user information generated from the Apple Pass. See Implement Apple Pass Integration With POS

  • drive_thru_code
    Type: string

    4-digit numeric/alphanumeric drive-thru short code generated by the user from the brand's mobile app that enables look-up of user details and balance. The short code is mapped to the guest_id. The API returns a 404 or 410 status code with the error message "CODE_EXPIRED" for an expired short code, and a 404 status code with the error message "CODE_NOT_FOUND" for an invalid or unmapped short code. See Generate a Drive-Thru Short Code

Headers
  • Authorization
    Type: string
    required

    This is a combination of unique API key as well as business key (UUID) as the Authorization header.

  • Accept-Language
    Type: string

    Short code for locale variant (e.g., fr-ca, es-ES, en-EN, etc.)

Body
application/json
Responses
  • 200
    Type: object
    • address_line1
      Type: string

      Full address of the user

    • age_verified
      Type: boolean

      Is the age of user verified or not

    • age_verified_status
      Type: boolean

      Whether or not the user has undergone age verification by Koupon Media. Possible values: true, false. The value is set to true if the user's age is verified by Koupon Media; otherwise, it is set to false. The response returns this parameter in sign-in, sign-up, and user update APIs if Koupon Media is selected as the age verification adapter for the business in the Punchh platform. Contact your Punchh representative to update this Punchh platform configuration setting.

    • anniversary
      Type: stringFormat: date

      Anniversary date of the user in YYYY-MM-DD format

    • avatar_remote_url
      Type: string

      Avatar remote URL the of user profile image

    • balance
      Type: Balance (Object)

      Account balance of the user

    • birthday
      Type: stringFormat: date

      Birthday date string of the user in YYYY-MM-DD format

    • city
      Type: string

      City in which the user lives

    • converted_category_balances
      Type: array Converted Category Balances (Array Object)[]
    • created_at
      Type: stringFormat: date-time

      Date/time string when the user was created in the system in ISO 8601 format

    • discount_type
      Type: string

      Discount types include: reward, redeemable

    • email
      Type: string

      Email address of the user

    • email_verified
      Type: boolean

      Is the email address of the user verified or not

    • fb_uid
      Type: string

      Facebook ID of the user

    • first_name
      Type: string

      First name of the user

    • gender
      Type: string

      Gender of the user

    • id
      Type: integer

      Unique ID of the user

    • last_name
      Type: string

      Last name of the user

    • payment_mode
      Type: string

      This value is set only in a single scan flow. Returns payment mode selected as a part of single scan flow. Currently supported values are GiftCard, CreditCard, and recurring.

    • phone
      Type: string

      Phone number of the user

    • privacy_policy
      Type: boolean

      Has the user agreed to the privacy policy or not

    • rewards
      Type: array Rewards (Array Object)[]

      Shows the details of rewards in the user account.

    • selected_card_number
      Type: string

      This value is set only in single scan flow. This is the gift card that the user wants to use for payment. If this value is set, use it to make the payment for the order.

    • selected_coupons
      Type: array Selected Coupons (Array Object)[]

      This object is set only in the single scan flow (SSF). The selected_coupons object shows one or more Punchh coupon codes if the user would like to redeem them as part of the single scan flow. The user selects the coupon(s) when generating the single scan code on the mobile application. If this value is set, trigger the redemption flow. See Single Scan Flow

    • selected_discount_amount
      Type: Selected Discount Amount (Object)

      This object is set for the single scan flow (SSF) for users who are on the Banked Rewards loyalty program. The selected_discount_amount object shows the banked currency amount if the user would like to redeem it as part of the single scan flow. The user selects the banked currency when generating the single scan code on the mobile application. If this value is set, trigger the redemption flow. See Single Scan Flow

    • selected_redeemable_cards
      Type: array Selected Redeemable Cards (Array Object)[]

      This object is set for the single scan flow (SSF) for users that are on the Visit-based loyalty program. The selected_redeemable_cards object shows one or more reedemable cards if the user would like to redeem them as part of the single scan flow. The user selects the redeemable cards when generating the single scan code on the mobile application. If this value is set, trigger the redemption flow. See Single Scan Flow

    • selected_redeemables
      Type: array Selected Redeemables (Array Object)[]

      This object is set for the single scan flow (SSF) for users that are on the Points Unlock Redeemables loyalty program. The selected_redeemables object shows one or more redeemables if the user would like to redeem them as part of the single scan flow. The user selects the redeemable(s) when generating the single scan code on the mobile application. If this value is set, trigger the redemption flow. See Single Scan Flow

    • selected_rewards
      Type: array Selected Rewards (Array Object)[]

      This object is set only in the single scan flow (SSF). The selected_rewards object shows one or more user-selected rewards if the user would like to redeem them as part of the single scan flow. The user selects the reward when generating the single scan code on the mobile application. If this value is set, trigger the redemption flow. See Single Scan Flow

    • selected_subscriptions
      Type: array Selected Subscriptions (Array Object)[] 1…

      This object is set only in the single scan flow (SSF). The selected_subscriptions array object shows one or more user-selected subscriptions if the user would like to redeem them as part of the single scan flow. The user selects the subscription(s) when generating the single scan code on the mobile application. See Single Scan Flow

    • selected_tip_amount
      Type: string

      This value is set only in single scan flow. This is the amount that the user selected as a tip amount on the mobile app during SSF code generation.

    • state
      Type: string

      State in which the user lives.

    • subscriptions
      Type: array Subscriptions (Array Object)[]

      This object is returned when the subscriptions feature is available for the business. In case a guest does not have active subscriptions, an empty object is returned.

    • updated_at
      Type: stringFormat: date-time

      Date/time string when the user was last updated in the system in ISO 8601 format.

    • user_digest
      Type: string

      User digest token of the user

    • zip_code
      Type: string

      Zip code of the user.

  • 400
    Type: object
    • error
      Type: string
  • 404
    Type: object
    • error
      Type: string
get/api/pos/users/search
{
  "address_line1": "string",
  "age_verified": true,
  "anniversary": "2025-12-19",
  "avatar_remote_url": "string",
  "balance": {
    "banked_rewards": "string",
    "expired_membership_level": "string",
    "initial_visits": 1,
    "membership_level": "string",
    "membership_level_id": "string",
    "net_balance": 1,
    "net_debits": 1,
    "pending_points": 1,
    "points_balance": 1,
    "signup_anniversary_day": "string",
    "total_credits": 1,
    "total_debits": "string",
    "total_point_credits": 1,
    "total_redeemable_visits": 1,
    "total_visits": 1,
    "unredeemed_cards": "string"
  },
  "birthday": "2025-12-19",
  "city": "string",
  "created_at": "2025-12-19T16:32:19.137Z",
  "discount_type": "string",
  "email": "string",
  "email_verified": true,
  "fb_uid": "string",
  "first_name": "string",
  "gender": "string",
  "id": 1,
  "last_name": "string",
  "phone": "string",
  "privacy_policy": true,
  "rewards": [
    {
      "created_at": "YYYY-MM-DDThh:mm:ssZ",
      "description": "string",
      "discount_amount": 1,
      "start_date_tz": "2025-12-19T16:32:19.137Z",
      "end_date_tz": "YYYY-MM-DDThh:mm:ssZ",
      "id": -9007199254740991,
      "image": "string",
      "name": "string",
      "points": 1,
      "redeemable_properties": "string",
      "status": "string",
      "updated_at": "string",
      "type": "string",
      "meta_data": "string"
    }
  ],
  "selected_card_number": "string",
  "state": "string",
  "updated_at": "2025-12-19T16:32:19.137Z",
  "user_digest": "string",
  "zip_code": "string",
  "converted_category_balances": [
    {
      "name": "string",
      "balance": "string",
      "discount_type": "string"
    }
  ],
  "payment_mode": "string",
  "selected_discount_amount": {
    "banked_currency": "string",
    "discount_type": "string"
  },
  "selected_rewards": [
    {
      "id": -9007199254740991,
      "name": "string",
      "description": "string",
      "created_at": "YYYY-MM-DDThh:mm:ssZ",
      "start_date_tz": "YYYY-MM-DDThh:mm:ssZ",
      "end_date_tz": "YYYY-MM-DDThh:mm:ssZ",
      "updated_at": "YYYY-MM-DDThh:mm:ssZ",
      "image": "string",
      "status": "string",
      "points": 1,
      "discount_amount": 1,
      "discount_type": "string",
      "redeemable_properties": "string"
    }
  ],
  "selected_redeemables": [
    {
      "id": -9007199254740991,
      "name": "string",
      "description": "string",
      "created_at": "YYYY-MM-DDThh:mm:ssZ",
      "count": 1,
      "start_date_tz": "YYYY-MM-DDThh:mm:ssZ",
      "end_date_tz": "YYYY-MM-DDThh:mm:ssZ",
      "updated_at": "2025-12-19T16:32:19.137Z",
      "image": "string",
      "status": "string",
      "points": 1,
      "discount_amount": 1,
      "discount_type": "string",
      "redeemable_properties": "string"
    }
  ],
  "selected_redeemable_cards": [
    {
      "id": -9007199254740991,
      "name": "string",
      "description": "string",
      "count": "string",
      "created_at": "YYYY-MM-DDThh:mm:ssZ",
      "start_date_tz": "YYYY-MM-DDThh:mm:ssZ",
      "end_date_tz": "YYYY-MM-DDThh:mm:ssZ",
      "updated_at": "YYYY-MM-DDThh:mm:ssZ",
      "image": "string",
      "status": "string",
      "points": 1,
      "discount_amount": 1,
      "discount_type": "string",
      "redeemable_properties": "string"
    }
  ],
  "selected_coupons": [
    {
      "code": "string",
      "name": "string",
      "description": "string",
      "start_date_tz": "YYYY-MM-DDThh:mm:ssZ",
      "end_date_tz": "YYYY-MM-DDThh:mm:ssZ",
      "image": "string",
      "discount_type": "string"
    }
  ],
  "selected_tip_amount": "string",
  "subscriptions": [
    {
      "plan_name": "string",
      "pos_meta": "string",
      "subscription_id": "string"
    }
  ],
  "age_verified_status": true,
  "selected_subscriptions": [
    {
      "subscription_id": 1,
      "start_time": "2025-12-19T16:32:19.137Z",
      "end_time": "2025-12-19T16:32:19.137Z",
      "external_plan_identifier": "string",
      "plan_id": 1,
      "cancelled_at": "2025-12-19T16:32:19.137Z",
      "name": "string",
      "description": "string",
      "miscellaneous": "string",
      "status": "string"
    }
  ]
}