Previous Topic		Next Topic
POS Module 2: Create User - Example Scenarios		POS Module 3: User Look-up - Example Scenarios

POS API Certification Tutorial - Module 3: User Look-up - Concepts

Goal

Look up a loyalty guest in the Punchh server using email, phone number, QR code, redemption code, or loyalty card number to retrieve guest data and assign the user to the check or transaction.

Prerequisites

You must have read Module 2: Create User - Concepts.
The guest or end-user must be registered with the business.

Use Cases and Context

At the point-of-sale, the POS operator performs a user look-up when informing the account balance of a guest, applying redemption for a guest, etc. When applying redemption using promos and coupons, the POS does not perform a user look-up as promos and coupons are not tied to users. The POS operator uses one of these identifiers to look up the user on the Punchh Platform:

Phone number
Email address
Card number
QR code (scan the code from the user’s mobile app)
Manually entered redemption code from the user’s mobile app

On successful user authentication, the Punchh server returns the guest data and assigns that guest to the transaction.

Primary Use Case Environment

Quick-service restaurant or convenience store
Quick sign-up at the counter
Table-side (if a business supports redemption code processing)

Applicable API Endpoints


Endpoint Name/Path	Relevant Request Parameters	Relevant Response Parameters
User Look-up and Fetch Balance GET {server-name}/api/pos/users/search	Pass one of the following query parameters: - phone - email - user_as_qrcode - card_number - redemption_code N/A - This request does not have a body.	- created_at - membership_level (shown under the balance object) - net_balance (shown under the balance object) These parameters are shown under the reward object: - name - points - discount_amount - end_date_tz - type

Example Code

User Look-up and Fetch Balance by phone

curl --location --request GET 'https://SERVER_NAME_GOES_HERE.punchh.com/api/pos/users/search?phone=1111111111' \
--header 'Cache-Control: no-cache' \
--header 'Content-Type: application/json' \
--header 'Authorization: Token token=LOCATION_KEY_GOES_HERE, btoken=BUSINESS_KEY_GOES_HERE' \
--header 'User-Agent: Brink/POS/1.0'

const url = 'https://SERVER_NAME_GOES_HERE.punchh.com/api/pos/users/search?phone=1111111111';
let headers = {
  'Cache-Control': 'no-cache',
  'Content-Type': 'application/json',
  'Authorization': 'Token token=LOCATION_KEY_GOES_HERE, btoken=BUSINESS_KEY_GOES_HERE',
  'User-Agent': 'Brink/POS/1.0'
};

let options = {
  method: 'GET',
  headers: headers
};

fetch(url, options)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

# You will need to install the Requests package before this code will work. 
# To do so, see the installation instructions here: https://requests.readthedocs.io/en/latest/user/install/#install

import requests
import json

url = "https://SERVER_NAME_GOES_HERE.punchh.com/api/pos/users/search?phone=1111111111"

headers = {
  'Cache-Control': 'no-cache',
  'Content-Type': 'application/json',
  'Authorization': 'Token token=LOCATION_KEY_GOES_HERE, btoken=BUSINESS_KEY_GOES_HERE',
  'User-Agent': 'Brink/POS/1.0'
}

response = requests.request("GET", url, headers=headers)

print(response.text)

User Look-up and Fetch Balance by email

NOTE: When passing special characters such as an @ in query parameters, if you encounter an error make sure to use URL encoding for those special characters (e.g. %40 in place of an @), or the request will fail. See below for examples.

curl --location --request GET 'https://SERVER_NAME_GOES_HERE.punchh.com/api/pos/users/search?email=test@example.com' \
--header 'Cache-Control: no-cache' \
--header 'Content-Type: application/json' \
--header 'Authorization: Token token=LOCATION_KEY_GOES_HERE, btoken=BUSINESS_KEY_GOES_HERE' \
--header 'User-Agent: Brink/POS/1.0'

const url = 'https://SERVER_NAME_GOES_HERE.punchh.com/api/pos/users/search?email=test@example.com';
let headers = {
  'Cache-Control': 'no-cache',
  'Content-Type': 'application/json',
  'Authorization': 'Token token=LOCATION_KEY_GOES_HERE, btoken=BUSINESS_KEY_GOES_HERE',
  'User-Agent': 'Brink/POS/1.0'
};

let options = {
  method: 'GET',
  headers: headers
};

fetch(url, options)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

# You will need to install the Requests package before this code will work. 
# To do so, see the installation instructions here: https://requests.readthedocs.io/en/latest/user/install/#install

import requests
import json

url = "https://SERVER_NAME_GOES_HERE.punchh.com/api/pos/users/search?email=test@example.com"

headers = {
  'Cache-Control': 'no-cache',
  'Content-Type': 'application/json',
  'Authorization': 'Token token=LOCATION_KEY_GOES_HERE, btoken=BUSINESS_KEY_GOES_HERE',
  'User-Agent': 'Brink/POS/1.0'
}

response = requests.request("GET", url, headers=headers)

print(response.text)

User Look-up and Fetch Balance by card number

curl --location --request GET 'https://SERVER_NAME_GOES_HERE.punchh.com/api/pos/users/search?card_number=1111111111111111' \
--header 'Cache-Control: no-cache' \
--header 'Content-Type: application/json' \
--header 'Authorization: Token token=LOCATION_KEY_GOES_HERE, btoken=BUSINESS_KEY_GOES_HERE' \
--header 'User-Agent: Brink/POS/1.0'

const url = 'https://SERVER_NAME_GOES_HERE.punchh.com/api/pos/users/search?card_number=1111111111111111';
let headers = {
  'Cache-Control': 'no-cache',
  'Content-Type': 'application/json',
  'Authorization': 'Token token=LOCATION_KEY_GOES_HERE, btoken=BUSINESS_KEY_GOES_HERE',
  'User-Agent': 'Brink/POS/1.0'
};

let options = {
  method: 'GET',
  headers: headers
};

fetch(url, options)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

# You will need to install the Requests package before this code will work. 
# To do so, see the installation instructions here: https://requests.readthedocs.io/en/latest/user/install/#install

import requests
import json

url = "https://SERVER_NAME_GOES_HERE.punchh.com/api/pos/users/search?card_number=1111111111111111"

headers = {
  'Cache-Control': 'no-cache',
  'Content-Type': 'application/json',
  'Authorization': 'Token token=LOCATION_KEY_GOES_HERE, btoken=BUSINESS_KEY_GOES_HERE',
  'User-Agent': 'Brink/POS/1.0'
}

response = requests.request("GET", url, headers=headers)

print(response.text)

User Look-up and Fetch Balance by QR code

curl --location --request GET 'https://SERVER_NAME_GOES_HERE.punchh.com/api/pos/users/search?user_as_qrcode=P11111111111' \
--header 'Cache-Control: no-cache' \
--header 'Content-Type: application/json' \
--header 'Authorization: Token token=LOCATION_KEY_GOES_HERE, btoken=BUSINESS_KEY_GOES_HERE' \
--header 'User-Agent: Brink/POS/1.0'

const url = 'https://SERVER_NAME_GOES_HERE.punchh.com/api/pos/users/search?user_as_qrcode=P11111111111';
let headers = {
  'Cache-Control': 'no-cache',
  'Content-Type': 'application/json',
  'Authorization': 'Token token=LOCATION_KEY_GOES_HERE, btoken=BUSINESS_KEY_GOES_HERE',
  'User-Agent': 'Brink/POS/1.0'
};

let options = {
  method: 'GET',
  headers: headers
};

fetch(url, options)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

# You will need to install the Requests package before this code will work. 
# To do so, see the installation instructions here: https://requests.readthedocs.io/en/latest/user/install/#install

import requests
import json

url = "https://SERVER_NAME_GOES_HERE.punchh.com/api/pos/users/search?user_as_qrcode=P11111111111"

headers = {
  'Cache-Control': 'no-cache',
  'Content-Type': 'application/json',
  'Authorization': 'Token token=LOCATION_KEY_GOES_HERE, btoken=BUSINESS_KEY_GOES_HERE',
  'User-Agent': 'Brink/POS/1.0'
}

response = requests.request("GET", url, headers=headers)

print(response.text)

User Look-up and Fetch Balance by redemption code

curl --location --request GET 'https://SERVER_NAME_GOES_HERE.punchh.com/api/pos/users/search?redemption_code=1111111' \
--header 'Cache-Control: no-cache' \
--header 'Content-Type: application/json' \
--header 'Authorization: Token token=LOCATION_KEY_GOES_HERE, btoken=BUSINESS_KEY_GOES_HERE' \
--header 'User-Agent: Brink/POS/1.0'

const url = 'https://SERVER_NAME_GOES_HERE.punchh.com/api/pos/users/search?redemption_code=1111111';
let headers = {
  'Cache-Control': 'no-cache',
  'Content-Type': 'application/json',
  'Authorization': 'Token token=LOCATION_KEY_GOES_HERE, btoken=BUSINESS_KEY_GOES_HERE',
  'User-Agent': 'Brink/POS/1.0'
};

let options = {
  method: 'GET',
  headers: headers
};

fetch(url, options)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

# You will need to install the Requests package before this code will work. 
# To do so, see the installation instructions here: https://requests.readthedocs.io/en/latest/user/install/#install

import requests
import json

url = "https://SERVER_NAME_GOES_HERE.punchh.com/api/pos/users/search?redemption_code=1111111"

headers = {
  'Cache-Control': 'no-cache',
  'Content-Type': 'application/json',
  'Authorization': 'Token token=LOCATION_KEY_GOES_HERE, btoken=BUSINESS_KEY_GOES_HERE',
  'User-Agent': 'Brink/POS/1.0'
}

response = requests.request("GET", url, headers=headers)

print(response.text)

Workflow

1. At the POS terminal, the POS uses one of the following identifiers to look up a user: email address, phone number, QR code, redemption code, or loyalty card number.

2. The POS uses built-in logic to determine if the type of identifier provided is an email address, a phone number, a card number, or a redemption code and passes the value in the appropriate parameter when making a call to the User Look-up API endpoint.

3. The POS makes a call to the User Look-up API endpoint with one of these identifiers (email address, phone number, QR code, or loyalty card number) to look up the loyalty user on the Punchh Platform.

4. If a user exists with the identifier provided in the API request on the Punchh server, the API returns the user’s data in the API response and assigns the user to the check. If the user is not found on the Punchh server, Punchh will call the Create New User API and create a new account for the user based on the phone number. If the autocreate_user_phone response parameter in the Program Meta API is set to true, the user will be created via POS, or else via SMS if the parameter is set to false.


Request Parameters	Descriptions
Email address	Email address is the primary look-up method. Email addresses must be unique, and one email address may not be used for multiple accounts.
Phone number	Punchh can configure its acceptance of phone numbers to either allow parsed phone numbers with special characters or not. Guest look-up supports a non-specific phone number format. For example, if a guest account is created with the phone number (972)000-0000, then you may look up a guest using this phone number format or by using a format with no special characters (9720000000). See “Best Practices” below for more information.
QR code	QR codes are provided by the guest via the mobile app. Depending on the business configuration, this may be a barcode, though each will use the same “user_as_qrcode” parameter. Punchh supports these three options for QR codes: 1. Short QR code: 2-12 character alphanumeric string starting with "P". Punchh recommends short QR codes only for POS systems that can not handle a long QR code. For example, the Micros POS system supports only short QR codes. Usually, a short QR code is used for single-scan flow. 2. Long QR code: A string enclosed by 'PUNCHH' with a minimum/maximum length of 13/512, respectively. The majority of businesses implement long QR codes. 3. Short-lived QR code: A character alphanumeric string starting with “S” with a minimum/maximum length of 8/8, respectively. Punchh provides a configuration in the platform to limit the duration of the short-lived code; that is how long the code will remain active after it is generated on the mobile app. When the code is scanned at the POS, the code remains active for the specified duration, and after that duration, it expires. For example, if the code expiry duration is set to 5 minutes, the code will remain active for 5 minutes after it is generated, and then after 5 minutes the code will expire. If the code expires before the code is scanned at the POS, then the code can not identify the user, and the user needs to regenerate the code on the mobile app. For more information about implementing the Punchh QR code algorithm, see Implement the Punchh Barcode and QR Code Algorithm.
Card number	The “card_number” parameter looks up a guest via a physical loyalty card number or a brand debit card assigned to the guest. The maximum size for this parameter is 18 digits.
Redemption code	Punchh supports looking up a guest using a redemption code assigned to the guest. For more information, see Create Redemption API.

Best Practices

Punchh strongly recommends not to include guest personal data while displaying guest profile/identity on the POS after a successful look-up. You can show information such as when the user was created in the system (created_at) and the membership level of the user (membership_level).
For businesses that do not enforce phone number uniqueness, Punchh returns the account with the most recently created date if multiple accounts share a phone number. Guest look-up by phone number or QR code is the best practice for these businesses. The option to validate the uniqueness of phone number across guests must be enabled in the Punchh platform if the phone numbers need to be unique across guests. Contact your Punchh representative to update this Punchh platform configuration setting.
Beyond the required parameters, ensure that your configuration supports the full list of Punchh-supported fields. Doing so gives businesses the ability to customize their experience to their individual business needs. For a list of supported parameters, see User Look-up and Fetch Balance API.