Library OpenApi Overview About these APIs Architecture Authentication Error Responses Locating a Server Sessions Design Guides Guides and Hints Examples Pricing for Websites Accepting Vouchers PreAuth Payment Replication Common Apis The most used APIs Create New Sale Payment Completion Multiple Locations Delivery Addresses Create New Sale v2 Customers Locations Products Staff WebHooks eCommerce Apis These APIs are often used with eCommerce website integrations Get Pricing Card Inquiry Report & Analysis Grouped or analysed report data. Typically used to build reports and dashboards Today Login Access Pinboard ReportRequest Advanced Information More indepth information Caller Handling HTTP Protocol Bulk Data Downloads Document Uploading RetailConfig Under Development Details of APIs that will be available shortly. Documentation provided is for early adopters Get Receipt

Customers API

Simple Examples

Storing details of a new customer

{
    "Name": "Pat Benatar",
    "Address1": "123 Riverlands Road",
    "Address2": "Perth",
    "Mobile": "+61 12 1234 5678",
    "Email": "patb@example.com",
    "EUCitizen": true
}

Quick Notes

This API is designed so that you can send the same information multiple times and the POS will only process it once. This can simplify sending applications as they can simply resend sales several times over a couple of days as a primitive retry mechanism. The restriction to this is that you must not change the information, such as adding new details or changing contents. IF you make changes the POS may record it as a new customer. If we have only returned error codes for each call, then you are permitted to change the details; as it has not been stored.

Full Name, First Name, Last Name, Company Name?

There are several name fields to cater for different retailer requirements, preferences and country of operation.

Name
This is the full name field, such as "Pat Benatar"
FirstName & LastName
These fields hold the two parts of the name individually. If you supply firstname and lastname but not Name, the POS will build Name from these two parts.
If you know for certain that this customer is a company, or you wish to store an individuals company association, use the CompanyName field.

Providing a Customer Id (Cid)

When you create a new customer, the POS will automatically allocate new internal Key identifiers. In some cases though you wish to immediately use this customer record in another API call without waiting for a key to be provided. You are allowed to create new customers and specify a valid UUID value, which can then be used in other API calls.

POST /Customers
{
    "CustomerId": "16D33318-1AB4-4728-806D-928DD3C07F01",
    "Name": "Pat Benatar",
    ...
}

POST /Sales
{
    "ExternalId": "Sale.000001",
    "CustomerId": "16D33318-1AB4-4728-806D-928DD3C07F01",
    ...
}

If allocating a CustomerId if must be a valid UUID of any type, you should not simply generate a random string. If you are unable to generate a valid UUID, then you can request a set of Physkey values with the Allocate Keys API to save and use as needed.

Searching for Customers

Searching for customers is done using the GET/Customers API. Provide the search string inside the "englishquery" search field.

The "option" search field can be used to augment your request and provide bit more context to the search. The option values are hints to the API rather than being specific controls.

var iStr = "intent:sale;geo:" + myLatitude;
iStr += "," + myLongitude;
iStr += "," + myAltitude;   // Optional
var Url = "/Customers?englishquery=smith&option=" + encodeURIComponent(iStr);

Supplying Additional Filters

The filter query parameter can be used to

Only Listing Customers with an Account

To list only customers that have a charge account. Retired accounts are not included in returned results

GET /OpenApi2/Customers?filter=account&...

To list only customers that are related to charge account 1234

GET /OpenApi2/Customers?filter=account=1234&...

Bulk Customer Extraction

Fieldpine OpenApi will happily return hundreds of thousands of results in one API call. This is not always optimal for other software which often prefers small paged result sets.

To select all customers in one call

GET /OpenApi2/Customers?limit=0

If you want paged results, include the query parameter ?page=N where the first page is #1, then 2 and so on.

GET /OpenApi2/Customers?limit=100&page=1
GET /OpenApi2/Customers?limit=100&page=2
GET /OpenApi2/Customers?limit=100&page=3
                
When using paged results a sort order must be provided. If you do not supply one the default order is 'Edit Date descending', which means the first row returned is the most recently edited.

Requesting page results does not stop you from filtering the rows. If you are only wanting rows changed since last time you scanned then the following pattern can be used

GET /OpenApi2/Customers?limit=100&page=1&englishquery=editdtu after 17-jan-2020
GET /OpenApi2/Customers?limit=100&page=2&englishquery=editdtu after 17-jan-2020
GET /OpenApi2/Customers?limit=100&page=3&englishquery=editdtu after 17-jan-2020