POS API Certification Tutorial - Module 2: Create User - Concepts

Goal

Create a new loyalty guest user on the POS device.

Prerequisites

Review Getting Started With POS API Integrations.

Use Cases and Context

Primary Use Case

The employee/cashier at a business (restaurant, convenience store, etc.) is creating the Punchh loyalty account for the user on the POS device at the physical store location.

Another use case may be when the POS operator does a look-up using the user's phone number or email and the results of a user look-up return “User Not Found”, the POS will prompt to create a new user.

At a minimum, a phone number or email is required for creating a user.

Primary Use Case Environment

• Quick-service restaurant or convenience store

• Quick sign-up at the counter

• Table-side

• Kiosk

Applicable API Endpoints

Example Code

Create new user account by phone

curl --location --request POST 'https://SERVER_NAME_GOES_HERE.punchh.com/api/pos/users' \
--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' \
--data-raw '{
	"phone": "1111111111",
	"first_name": "FIRST_NAME_GOES_HERE",
	"last_name": "LAST_NAME_GOES_HERE",
	"terms_and_conditions": true,
	"send_compliance_sms": false
}'

const url = 'https://SERVER_NAME_GOES_HERE.punchh.com/api/pos/users';
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 requestBody = {
  phone: '1111111111',
  first_name: 'FIRST_NAME_GOES_HERE',
  last_name: 'LAST_NAME_GOES_HERE',
  terms_and_conditions: true,
  send_compliance_sms: false
};

let options = {
  method: 'POST',
  headers: headers,
  body: JSON.stringify(requestBody)
};

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"

payload = json.dumps({
  "phone": "1111111111",
  "first_name": "FIRST_NAME_GOES_HERE",
  "last_name": "LAST_NAME_GOES_HERE",
  "terms_and_conditions": True,
  "send_compliance_sms": False
})
headers = {
  '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("POST", url, headers=headers, data=payload)

print(response.text)

Create new user account by email

curl --location --request POST 'https://SERVER_NAME_GOES_HERE.punchh.com/api/pos/users' \
--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' \
--data-raw '{
	"email": "test@example.com",
	"first_name": "FIRST_NAME_GOES_HERE",
	"last_name": "LAST_NAME_GOES_HERE",
	"terms_and_conditions": true,
	"send_compliance_sms": false
}'

const url = 'https://SERVER_NAME_GOES_HERE.punchh.com/api/pos/users';
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 requestBody = {
  email: 'test@example.com',
  first_name: 'FIRST_NAME_GOES_HERE',
  last_name: 'LAST_NAME_GOES_HERE',
  terms_and_conditions: true,
  send_compliance_sms: false
};

let options = {
  method: 'POST',
  headers: headers,
  body: JSON.stringify(requestBody)
};

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"

payload = json.dumps({
  "email": "test@example.com",
  "first_name": "FIRST_NAME_GOES_HERE",
  "last_name": "LAST_NAME_GOES_HERE",
  "terms_and_conditions": True,
  "send_compliance_sms": False
})
headers = {
  '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("POST", url, headers=headers, data=payload)

print(response.text)

Create new user account by card number

curl --location --request POST 'https://SERVER_NAME_GOES_HERE.punchh.com/api/pos/users' \
--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' \
--data-raw '{
	"card_number": "1111111111111111",
	"first_name": "FIRST_NAME_GOES_HERE",
	"last_name": "LAST_NAME_GOES_HERE",
	"terms_and_conditions": true,
	"send_compliance_sms": false
}'

const url = 'https://SERVER_NAME_GOES_HERE.punchh.com/api/pos/users';
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 requestBody = {
  card_number: '1111111111111111',
  first_name: 'FIRST_NAME_GOES_HERE',
  last_name: 'LAST_NAME_GOES_HERE',
  terms_and_conditions: true,
  send_compliance_sms: false
};

let options = {
  method: 'POST',
  headers: headers,
  body: JSON.stringify(requestBody)
};

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"

payload = json.dumps({
  "card_number": "1111111111111111",
  "first_name": "FIRST_NAME_GOES_HERE",
  "last_name": "LAST_NAME_GOES_HERE",
  "terms_and_conditions": True,
  "send_compliance_sms": False
})
headers = {
  '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("POST", url, headers=headers, data=payload)

print(response.text)

Workflow

The Create New User API endpoint provides an option to create a loyalty user with an Email address, Phone number, or Punchh loyalty Card Number. Depending on the business configuration, at least a Phone, Email, or Card Number is required in every request to create a new user.

By default, the email address is the primary identifier; however, Punchh allows a business to configure the phone number as the unique identifier. When creating a user at POS, if the only input is a guest email address for a business that requires a phone number, the API returns the following error: “Please enter a valid Phone Number.”

The option to enable phone number as a mandatory field must be enabled in the Punchh platform if the phone number is to be made mandatory for creating a new user. Contact your Punchh representative to update this Punchh platform configuration setting.

The Create New User API allows you to create a user with only a loyalty card or phone number. In such a case, Punchh creates a dummy email account with card@cards.punchh.com (e.g. 23XXXXXXXX78XXXX@cards.punchh.com) or phone@phone.punchh.com (e.g. XXX234XXX8@phone.punchh.com) as the email address is the primary guest identifier and new user account can not be created without the email address.

Punchh can configure phone numbers to be unique throughout a business. This option is usually configured when the production environment for the business is set up on the Punchh side. If this is the current configuration, and a non-unique phone number is used with a new guest, the Create New User API returns the following error: “Phone has already been taken.”

Tip: To verify if the required parameter for creating a new user at POS is a phone number, you can send a test Create New User API request with a blank value in the phone parameter. If the API returns a validation error, it means the phone number is a required parameter.

The option to validate the uniqueness of a phone number across guests must be enabled in the Punchh platform for Punchh to validate the phone number for uniqueness when creating a new user at POS. Contact your Punchh representative to update this configuration setting.

We recommend you configure the POS to accept only the user's phone number or email address when creating a new user. Creating an account with a phone number is the best practice. Based on the configurations, Punchh provides guest users with these different options to complete their profile and registration process.

• If the phone number is used for sign-up and if the text-to-join feature is configured in the Punchh platform, Punchh will send a text-to-join link to the user’s mobile number. The user can use the link to complete the profile and registration process. For text-to-join to work, both SMS and text-to-join must be enabled on the Punchh platform. Contact your Punchh representative to update these Punchh platform configuration settings. Additionally, the text-to-join feature will work only if the send_compliance_sms request parameter in the Create New User API is set to true, triggering compliance/opt-in SMS for the user.
• If the phone number is used for sign-up and if the “Text to Join” feature is not configured for business, users can download the brand app on their mobile or go to the brand Website and create an account to complete the profile and registration process. Punchh provides guest users with an option to merge/sync their user accounts created at POS with the account created on the brand app or on the Website. On the app sign-up page, the guest must provide the same phone number that was provided at the POS. If the phone numbers provided at the POS and on the brand website/app match, the accounts are merged/synched. After successful sign-up, users can log in to the brand app from mobile and complete their profile and registration process to be able to receive any email or marketing communication. Guest users can also view the points earned for transactions made at the POS.
• If an email address is used to create a guest user account at the POS, the guest will need to manually visit the brand's website/iFrame or mobile app and select "Forgot Password" on the login page. The guest will receive an email with a password-reset link, which they can use to set a password for the new account. After setting the password, the guest can log in to the brand’s app or website using their email address and password to complete their profile and registration. Guests can view the points earned for the transactions made at the POS. The reset message and link are configured in the Punchh platform. Contact your Punchh representative to update this Punchh platform configuration.

Here is another use case where you may need to call the Create New User API. POS should automatically make a call to the Create New User API endpoint and create a user with the user's phone number if the user is not found on the Punchh server during a user look-up. Before making a call to the Create New User API, check if the autocreate_user_phone value in the Program Meta configurations is set to "true" for business. If the autocreate_user_phone value is not set to "true", the POS should not call the Create New User API; however, the POS operator should still be allowed to manually create a new user. The autocreate_user_phone values can be true or false, depending on the platform configuration.

The autocreate_user_phone value is configured for the POS integration in the Punchh platform. If the "Create a new guest based on phone number if the guest doesn't exist (via POS/SMS)?" option is enabled, the autocreate_user_phone value can be set to true. Contact your Punchh representative to update this configuration setting.

Note

Depending on the business criteria, Punchh can add requirements to make the following additional fields mandatory. We recommend you not to collect the following information at POS, but these should be collected either in the Kiosk environment or through the brand app to protect user privacy.

• Birthday: This can be added later in the user profile

• Terms and conditions opt-in status: This can be added later in the user profile. If you make the Terms and Conditions required at POS, POS needs to send whether the guest has accepted or declined the terms and conditions of the brand for Punchh to complete the sign-up process.

• Zip code: This can be added later in the user profile

• Favorite location: This can be added later in the user profile 

• First Name: This can be added later in the user profile

• Last Name: This can be added later in the user profile

If requested by the business, Punchh can set some of these fields to required within the Punchh platform. Contact your Punchh representative for more information about this Punchh platform configuration setting.

The first name and last name can be set as mandatory in the Punchh platform. Contact your Punchh representative to update these configuration settings.

After a new user has been created, the user’s signup_anniversary_day will automatically be set to the day that the user data was received, and an “id” will be created for the guest.  If needed, this information can be seen in the Create New User API response. 

Within the response, you will also see the user_digest parameter. This is a parameter received for use with other APIs (online ordering, check-in, and others) and can be ignored for the process of adding a user.

Best Practices

• Punchh strongly recommends that you configure the POS to collect only the phone number or email address when creating a new user to protect user privacy. The phone number is preferred over email at the POS terminal, as typing in the email address at the counter is slow and prone to typing errors. As mentioned above, the requirement for email can change to a phone number depending on the business configuration. Punchh recommends that you configure the first name, last name, zip code, and birthday as mandatory with any new guest data in a kiosk or table-side environment.  

• Punchh does not validate phone numbers for length or character. Such validations should be done on the integration side. 

• Beyond the required parameters, ensure that your configuration supports the full list of Punchh sign-up fields. Doing so gives businesses the ability to customize their user creation and configure guest sign-up to their individual business needs. For a list of supported parameters, see Create New User API.

Related Topics

Create New User API

Getting Started With POS API Integrations

Program Meta API