Schema

The Punchh API is a RESTful API over HTTPS. A valid authentication signature through HTTP header x-pch-digest must be included with all requests. Our API uses industry standard SSL/TLS encryption and must be accessed only over HTTPS. Plain-text HTTP access is not available.

Base Endpoint

All requests must be sent to a resource name by prepending the API base URL. Currently, we provide two environments: production and sandbox.

Production API Base URL

Examples in our API documentation assume that the production API base URL provided by your Punchh representative will be used. For each and every request, send the request along with the required parameters and authentication signature through headers.

https://SERVER_NAME_GOES_HERE.punchh.com

Sandbox API Base URL

Sandbox is for testing only. For Sandbox, replace the production API base URL with the Sandbox API base URL provided by your Punchh representative.

Parameters

Many API methods take optional parameters. We accept parameters in two different ways:

a). Query string: For GET requests, parameters can be passed as an HTTP query string. For example:

Using auth

$ curl -i "https://SERVER_NAME_GOES_HERE.punchh.com/api/auth/users?name=EMAIL_GOES_HERE -H 
    "x-pch-digest:SIGNATURE_GOES_HERE

In this example, we want to fetch users via the API where the name parameter with value EMAIL_GOES_HERE is passed in the query string.

b). JSON in the request body: For HTTP POST, PATCH, PUT, and DELETE requests, parameters should be sent in the HTTP body as JSON; application/json included in the request's Content-Type header and SHA1 SIGNATURE value should be included in the x-pch-digest header.

JSON Formatting

JSON must be serialized, as specified in RFC4627, and encoded as UTF-8, as specified in RFC3629, using one to four bytes per Unicode code point.

For example:

Using auth

$ curl -i "https://SERVER_NAME_GOES_HERE.punchh.com/api/auth/users" \
       -H "Content-Type:application/json" \
       -H "Accept: application/json" \
       -H "x-pch-digest:SIGNATURE_GOES_HERE"  \
       -X PUT \
       -d '{"name":NAME_GOES_HERE,"client_key":CLIENT_KEY_FOR_PUNCHH_DASHBOARD_HERE}' \
       -u 'USER_TOKEN_HERE:x' \

In this example, we send an HTTP PUT request to list users through the auth API while name and client_key are passed as parameters. We provide authentication using HTTP basic auth USER_TOKEN_HERE for authentication and signature using x-pch-digest header, which is generated using the URL and body through the SHA1 digest algorithm. For more information, see Generating x-pch-digest Header for Online Ordering APIs.

Response Data Format

All responses are in JSON.

Blank Fields

Blank fields are included as null (empty) instead of being omitted.

HTTP Verbs

Where possible, API auth strives to use appropriate HTTP verbs for each action.

Error Codes and Responses

The Punchh API attempts to return appropriate HTTP status codes for every request.

Date Format

We use ISO 8601 as our data format. All timestamps are returned in the following format:

YYYY-MM-DDTHH:MM:SSZ