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.

• intent:sale Provide this string as part of the option value if your primary reason for searching for a customer is to create a new sale. Leave it out otherwise. This provides a hint to the POS that very old records can be removed at the preference of newer records. For example if your database has 5000 Customers called Smith, this may cause the list to favour those with recent sales or contact.
• geo:latitude,longitude,altitude Supplies your current position so that searching can favour records near you. Using the Smith example again, if you are using a mobile device while at Smith's house/business, then that record is likely to be listed first when searching.

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