Online Ordering API Certification Tutorial - Module 1a: Create User

Goal

Create a new loyalty guest user in the online ordering system of a business via the website or mobile app.

Prerequisites

Review Overview of Online Ordering API Certification Tutorials, Getting Started With Online Ordering APIs, and Getting Started With SSO APIs.

Use Cases and Context

When creating an account, the user must provide all required fields (email, password, name, phone, etc.). The user can create the account before or after visiting the business. Some fields may be required by platform settings defined in the Punchh platform. Regardless of the provider used for online ordering, the integration partner should allow the business to set any of the optional fields in the Sign up With Email and Password API as required and send the data for those fields to the Punchh server.

A major difference between POS sign-up and online ordering sign-up is that online ordering is a full sign-up that can be done at the guest’s convenience from the business website or mobile app. For online ordering, the user must provide email, password, and any other required fields, whereas with POS sign-up the user can quickly sign up as a “partial” user by providing just a phone number or an email address. Some businesses have custom profile fields with optional questions, and some have a wizard that walks the user through the sign-up process.

Note: You may pass access_token instead of authentication_token in the authorization header of online ordering endpoints. It will be passed as a bearer token (e.g., Authorization: Bearer {{access_token_goes_here}})

Applicable API Endpoints

Example Code

Before running the Python and Ruby example code below, save each code sample to a file (.py or .rb) in the same directory where the generate_signature file (.py or .rb) and the http_client file (.py or .rb) are located, as described in Overview of Online Ordering API Certification Tutorials.

Create User

curl --location --request POST 'https://SERVER_NAME_GOES_HERE.punchh.com/api/auth/customers.json' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'x-pch-digest: SIGNATURE_GOES_HERE' \
--header 'User-Agent: Punchh/OnlineOrder/1.0/Web/BrowserVersion/OS_Type' \
--data-raw '{
  "client":"CLIENT_GOES_HERE",
  "user":{  
    "email":"test@example.com",
    "password":"PASSWORD_GOES_HERE",
    "password_confirmation": "PASSWORD_GOES_HERE",
    "first_name":"Test",
    "last_name":"Test",
    "terms_and_conditions": true,
    "zip_code": "98701",
    "phone": "1111111111",
    "birthday": "1985-10-26"
  }
}'

import json
from http_client import send_request

def sign_up():
  path = "/api/auth/customers.json"
  http_verb = "POST"
  body = json.dumps({
  "client": "CLIENT_GOES_HERE",
  "user": {
    "email": "test@example.com",
    "password": "PASSWORD_GOES_HERE",
    "password_confirmation": "PASSWORD_GOES_HERE",
    "first_name": "Test",
    "last_name": "Test",
    "terms_and_conditions": True,
    "zip_code": "98701",
    "phone": "1111111111",
    "birthday": "1985-10-26"
  }
})

  response = send_request(path, http_verb, body)
  print(f"Response: {response}")

sign_up()

class Signup
    require_relative 'generate_signature.rb'
    require_relative 'http_client.rb'
    require 'json'

    # Client for the environment that you are pointing the request to
    CLIENT = "CLIENT_GOES_HERE"
    PATH = "/api/auth/customers.json"
    HTTP_VERB = "POST"

    def self.signup
        body = {client: CLIENT, user: {email:"test@example.com",password:"PASSWORD_GOES_HERE",password_confirmation:"PASSWORD_GOES_HERE",first_name:"Test",last_name:"Test",terms_and_conditions:true,zip_code:"98701",phone:"1111111111",birthday:"1985-10-26"}}.to_json
        response = HttpClient::send_request(PATH, HTTP_VERB, body)
    end
end

Signup.signup

Workflow

The Sign up With Email and Password API provides an option to create a loyalty user with at least the business client key, an email address, and a password. Depending on the business criteria, the following fields can be made mandatory in the Punchh platform so that the user must complete the fields when signing up for an account on the business website or mobile app:

• Phone number
• Birthday
• Terms and conditions opt-in status
• Zip code
• Favorite location
• First name
• Last name

Note: If a mandatory field is enabled after users are already created, that can cause issues for those existing users. Depending on the mandatory field, it can cause existing users to not be able to log in until their accounts are updated to include the required field.

If requested by the business, Punchh can set some of these fields to required within the Punchh platform. Contact your Punchh representative to update this configuration.

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, 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.”

If a business wants the phone number to be mandatory when creating a new user, this must be set in the Punchh platform. Contact your Punchh representative to update this configuration.

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 Sign up With Email and Password API returns the following error: “Phone has already been taken.”

Tip: To verify if the required parameter for creating a new user is a phone number, you can send a test Sign up With Email and Password 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.

If a business wants Punchh to validate the phone number for uniqueness when creating a new user, this must be set in the Punchh platform. Contact your Punchh representative to update this configuration.

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

After a new user has been created, the user’s sign-up anniversary date (the user_joined_at parameter) will automatically be set to the day that the user data was received, and an “id” will be created for the user. This information, if needed, can be seen in the response of the Sign up With Email and Password API.

If the Punchh platform has been configured to enable generation of access tokens for single sign on, the access_token parameter can be returned in the response of the Sign up With Email and Password API. In most mobile API endpoints, the value of the access_token parameter is used as the value of the Authorization header where required. Contact your Punchh representative to update this configuration.

Best Practices

• Punchh recommends that you configure the first name, last name, zip code, and birthday as mandatory with any new guest data. Gather as many pieces of information as the business wants and then send them to the Punchh server (e.g., if the business is asking for a birthday or zip code, that information should be sent to the Punchh server). Some fields can be made required via the Punchh platform (e.g., birthday, phone number, enforce unique phone number). There is no way to get that configuration information from the API, so it is better to provide more information up front so that you have all of the required information. If building an integration for multiple businesses, some businesses may want to use a different subset of fields, so the integration partner should have the option of allowing the business to configure which fields to use. The online ordering integration partner should allow the business to set any of the optional fields in the Sign up With Email and Password API as required and send the data for those fields to the Punchh server. If the online ordering integration partner supported only some of the available fields, the business could not gather those fields during sign-up, so the business would have to gather the information some other way. If the business does not gather some fields at sign-up, adding that information later would require updating each user where that information is missing. The external_source parameter must be sent with the external_source_id parameter.
• Punchh does not validate phone numbers on 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 more information, see Sign up With Email and Password.
• Parameters returned in the response of the Sign up With Email and Password API can be used to display relevant user profile information. For example, first_name and last_name are commonly used on a website to greet the user by name. Other parameters can be used to display the current value on an edit profile page (e.g., address_line1, birthday, city, email, state, zip_code, favourite_locations, marketing_email_subscription, and phone).

Related Topics

Overview of Online Ordering API Certification Tutorials

Sign up With Email and Password API

Getting Started With Online Ordering APIs

Getting Started With SSO APIs