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.

User Look-up with Loyalty Short Code

The Loyalty Short Code is generated in the mobile app. When only the guest identification using the short code at driv-thru is enabled for a business, the short code is used for loyalty identification only. When Single Scan Flow (SSF) and Payment with Short Code using SSF are also enabled, the short code is used for both loyalty identification and payment.

A Short code used only for loyalty identification is generated using the Generate a Drive-Thru Short Code API. When the short code is used for look-up, the User Look-up API returns the user profile data, balance, and rewards in the response.

A Short code used for both loyalty identification and payment is generated using Generate Single Scan Code API. When the POS calls the User Look-up API with the short code (passed in the drive_thru_code parameter), Punchh uses the short code and the user ID mapped to it to retrieve the associated single_scan_code.

Punchh then uses the single_scan_code to look up the user and returns it in the response, along with any rewards and payment information selected by the user when generating the short code from the mobile app. The POS can use the single_scan_code for check-in, redemptions, and payments.

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.

  • reward_id
    Type: integerFormat: int64

    ID of the user’s reward 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

  • nfc_token
    Type: string

    User identifier that enables the look-up of user information generated from the Google Pass. See Implement Google 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 lookup of user details and balance. The short code is mapped to the user ID. See Generate a Drive-Thru Short Code.

    When the short code passed in the API is enabled for payments, Punchh uses the short code and the user ID mapped to it to retrieve the associated single scan code. Punchh then uses the single scan code to look up the user and returns it in the response, along with any rewards and payment information selected when the short code was generated.

    The POS can use the single_scan_code for check-in, redemptions, and payments. See Generate Single Scan Code API.

    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.

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.)

Responses
  • application/json
  • application/json
  • application/json
Request Example for get/api/pos/users/search
curl 'https://SERVER_NAME_GOES_HERE.punchh.com/api/pos/users/search?email=&phone=&card_number=&user_as_qrcode=&single_scan_code=&redemption_code=&reward_id=1&apple_nfc_data=&nfc_token=&drive_thru_code=' \
  --header 'Authorization: Token token=LOCATION_KEY_GOES_HERE, btoken=BUSINESS_KEY_GOES_HERE' \
  --header 'Accept-Language: en'

{
  "address_line1": "",
  "age_verified": false,
  "anniversary": null,
  "avatar_remote_url": null,
  "balance": {
    "banked_rewards": "3339.69",
    "expired_membership_level": null,
    "initial_visits": 0,
    "membership_level": null,
    "membership_level_id": null,
    "net_balance": 3339.69,
    "net_debits": 425.31,
    "pending_points": 434,
    "points_balance": 41,
    "signup_anniversary_day": "10/17",
    "total_credits": 21091,
    "total_debits": "425.31",
    "total_point_credits": 21091,
    "total_redeemable_visits": 210,
    "total_visits": 201,
    "unredeemed_cards": 0
  },
  "birthday": null,
  "city": "",
  "created_at": "2017-10-17T18:40:05Z",
  "discount_type": null,
  "email": "test@example.com",
  "email_verified": false,
  "fb_uid": null,
  "first_name": "FIRST_NAME_GOES_HERE",
  "gender": "",
  "id": 1107620,
  "last_name": "LAST_NAME_GOES_HERE",
  "phone": 1111111111,
  "privacy_policy": false,
  "rewards": [
    {
      "created_at": "2019-07-30T10:36:23Z",
      "description": "Test Test",
      "discount_amount": 0,
      "end_date_tz": null,
      "id": 1380722,
      "image": "IMAGE_URL_GOES_HERE",
      "name": "Test1",
      "points": 0,
      "redeemable_properties": null,
      "start_date_tz": "2019-07-30T10:36:23Z",
      "status": "unredeemed",
      "updated_at": "2019-07-30T10:36:23Z"
    },
    {
      "created_at": "2019-09-28T07:05:50Z",
      "description": "",
      "discount_amount": 5,
      "end_date_tz": null,
      "id": 1399333,
      "image": "IMAGE_URL_GOES_HERE",
      "name": "Test (basic)",
      "points": 0,
      "redeemable_properties": null,
      "start_date_tz": "2019-09-28T07:05:50Z",
      "status": "unredeemed",
      "updated_at": "2020-04-20T19:36:03Z"
    },
    {
      "created_at": "2019-09-28T07:05:50Z",
      "description": "",
      "discount_amount": 5,
      "end_date_tz": null,
      "id": 1399334,
      "image": "IMAGE_URL_GOES_HERE",
      "name": "Test (basic)",
      "points": 0,
      "redeemable_properties": null,
      "start_date_tz": "2019-09-28T07:05:50Z",
      "status": "unredeemed",
      "updated_at": "2019-09-28T07:05:50Z"
    },
    {
      "created_at": "2019-09-28T07:05:50Z",
      "description": "",
      "discount_amount": 5,
      "end_date_tz": null,
      "id": 1399335,
      "image": "IMAGE_URL_GOES_HERE",
      "name": "Test (basic)",
      "points": 0,
      "redeemable_properties": null,
      "start_date_tz": "2019-09-28T07:05:50Z",
      "status": "unredeemed",
      "updated_at": "2019-09-28T07:05:50Z"
    },
    {
      "created_at": "2019-09-28T07:05:50Z",
      "description": "",
      "discount_amount": 5,
      "end_date_tz": null,
      "id": 1399336,
      "image": "IMAGE_URL_GOES_HERE",
      "name": "Test (basic)",
      "points": 0,
      "redeemable_properties": null,
      "start_date_tz": "2019-09-28T07:05:50Z",
      "status": "unredeemed",
      "updated_at": "2019-09-28T07:05:50Z"
    },
    {
      "created_at": "2020-01-30T13:26:40Z",
      "description": "",
      "discount_amount": 0,
      "end_date_tz": null,
      "id": 1425570,
      "image": "IMAGE_URL_GOES_HERE",
      "name": "Test QC static discounrt",
      "points": 0,
      "redeemable_properties": null,
      "start_date_tz": "2020-01-30T13:26:40Z",
      "status": "unredeemed",
      "updated_at": "2020-01-30T13:26:40Z"
    },
    {
      "created_at": "2020-01-30T13:41:40Z",
      "description": "",
      "discount_amount": 0,
      "end_date_tz": null,
      "id": 1425572,
      "image": "IMAGE_URL_GOES_HERE",
      "name": "Test QC static discounrt",
      "points": 0,
      "redeemable_properties": null,
      "start_date_tz": "2020-01-30T13:41:40Z",
      "status": "unredeemed",
      "updated_at": "2020-01-30T13:41:40Z"
    },
    {
      "created_at": "2020-01-30T13:57:07Z",
      "description": "",
      "discount_amount": 0,
      "end_date_tz": null,
      "id": 1425574,
      "image": "IMAGE_URL_GOES_HERE",
      "name": "Test QC static discounrt",
      "points": 0,
      "redeemable_properties": null,
      "start_date_tz": "2020-01-30T13:57:07Z",
      "status": "unredeemed",
      "updated_at": "2020-01-30T13:57:07Z"
    },
    {
      "created_at": "2020-04-20T18:17:40Z",
      "description": "",
      "discount_amount": 2,
      "end_date_tz": null,
      "id": 1478745,
      "image": "IMAGE_URL_GOES_HERE",
      "name": "Test $2",
      "points": 0,
      "redeemable_properties": null,
      "start_date_tz": "2020-04-20T18:17:40Z",
      "status": "unredeemed",
      "updated_at": "2020-04-20T18:17:40Z"
    },
    {
      "created_at": "2020-04-20T18:18:04Z",
      "description": "",
      "discount_amount": 2,
      "end_date_tz": null,
      "id": 1478746,
      "image": "IMAGE_URL_GOES_HERE",
      "name": "Test $2",
      "points": 0,
      "redeemable_properties": null,
      "start_date_tz": "2020-04-20T18:18:04Z",
      "status": "unredeemed",
      "updated_at": "2020-04-20T18:18:04Z"
    }
  ],
  "selected_card_number": null,
  "selected_discount_amount": null,
  "selected_reward_id": null,
  "selected_subscriptions": [
    {
      "subscription_id": 331,
      "start_time": "2024-06-05T17:21:48+05:30",
      "end_time": "2024-07-25T23:59:59+05:30",
      "external_plan_identifier": null,
      "plan_id": 14,
      "cancelled_at": null,
      "name": "Sub plan",
      "description": "",
      "miscellaneous": "",
      "status": "active"
    }
  ],
  "state": "",
  "updated_at": "2020-04-28T14:43:15Z",
  "user_digest": "USER_DIGEST_GOES_HERE",
  "zip_code": null,
  "age_verified_status": true
}
Copyright © 2026 PAR Technology Corporation. All rights reserved.
PAR Technology Corporation 8383 Seneca Turnpike, Suite 3 New Hartford, New York 13413 (315) 738-0600 legal@partech.com. PAR Tech is a leading global provider of software, systems, and service solutions to the restaurant and retail industries. You may learn about its product offerings here.
Before using this application, please read the Limited License Agreement and the PAR Tech Terms of Use. In addition, the sample applications of PAR Technology are licensed under the terms of the O'Saasy License.