Contacts flow
Contacts are the backbone of the data stored in Engage. Here's how to work with them.
Creating a contact
Creating a contact in Engage consists of these steps:
First, check if the contact already exists in Engage, using this endpoint:
GET api/v2/contacts/idIn the payload of this request, you will send some identifier for the contact, such as their email.
If the contact exists, Engage returns their unique contactId value.
If they don't exist, you'll get error code “404 contact not found” and can continue to the next step, which is where you will create a contact in Engage for this customer.
Now you know the contact does not already exist in Engage, so create them using:
POST api/v2/contactsEngage returns the code 200, 201 or 202 if the creation is successful.
In the response payload you'll get a JSON with the contact's full information.
In both of the steps above, the GUID of the created contact will be returned as the id value in the response payload. Store this value for that contact in your system and use it in the future for looking them up. This simplifies your flows and reduces unnecessary delays and API calls to Engage.
Contact creation error handling
When no response is received from the Engage API, or when the response has error code 500, you'll need a plan in place to ensure that no data is lost until the connection is restored.
Retry: If your first call is unsuccessful, perform a retry. Follows the recommendations here.
Local file: If errors remain, or no response is received, you should implement a fallback. This works by saving contact changes to local XML files in your system. Then, when the connection has been restored, these files can be transferred to Engage to sync contact data, in one of two ways:
You can transfer contact changes by file through the Engage FTP server.
Tip
When uploading XML files via the FTP, contact GUIDs will not be returned from Engage for any new contacts created. Therefore, the next time that contact is identified, you'll need to check if their GUID already exists in your systems, and save it there if it doesn't, to reduce unnecessary API calls and improve your flow.
Or you can save contact changes using the Engage bulk API:
POST /api/v3/contacts/bulkSee more about the bulk API here.
Posting data like this puts it in a queue that Engage handles asynchronously. In the meantime, you can continue with your normal workflow.
Updating contacts
When an existing contact's data changes (such as a new address, new name or change in some consent) you'll need to do an update to sync those changes to Engage.
If the Engage contactId has been saved in your system, as recommended above, you will not need to query Engage for it first and can just continue directly to the updating.
However, if the contactId, for whatever reason, has not been saved, then a lookup to the Engage API must be done to fetch it, using the general lookup endpoint along with some identifying information:
GET api/v2/contacts/id
When you know the contactId, the update is then done like this:
POST api/v2/contacts/{contactId}
The contact attributes to be updated are sent in the request payload.
Important
When updating contacts in Engage, be sure to send only the changes. Empty or null values in an update payload will overwrite the existing values, and you probably don't want that.
Engage will return a 200 or 202 response code to show the request was successful.
Contact updating error handling
Like in the contact creation case, it's important to have a fallback in place for when problems occur, such as when Engage is down, or does not respond, or return error code 500 is received.
Again, if your first call is unsuccessful, perform a retry. Follows the recommendations here.
If that fails, implement your local file fallback, saving changes that will be sent in later when the connection has been restored, using either the Engage FTP, or the bulk update endpoint:
PATCH /api/v3/contacts/bulk
Engage processes these updates asynchronously, allowing you to continue with your workflow.
Fetching a contact's information
The need will arise to fetch a contact's data, for example when presenting their personal information, their purchases or their active promotions on My Pages in your e-com.
There are three endpoints used here, and they are:
GET /api/v2/contacts/{contactId}
GET /api/v2/contacts/{contactId}/transactions
GET /api/v2/contacts/{contactId}/promotions
Important
Cache the response you get here and use that should the page be reloaded. This is to avoid repeated API calls, which can lead to loading delays and a worse user experience.
Important
You should only fetch what you need. If you just want to view purchase history, then just use /transactions. For personal data, use only the first endpoint of the three above.
All three endpoints use contactId to identify the contact. Let's consider each one separately.
Fetch a contact's data
To fetch the full contact data use the first endpoint:
GET /api/v2/contacts/{contactId}
This returns a JSON with the contact's personal information (not transactions or promotions).
This is useful, for example, to get a contact's postal address, see the store where they signed up, or to display their personal information on their My Pages in your e-com.
Which information you will display and how is up to you. Engage will return all contact information and you must then filter out what you wish to show for your customer.
Fetch a contact's purchase history
To fetch the contact's purchase and returns history, use the second endpoint:
GET /api/v2/contacts/{contactId}/transactions
This endpoint allows you some control in paginating the response.
Note that purchases and returns are both present in the data received.
Fetch a contact's active promotions
To fetch all of the contact's active promotions use the third endpoint:
GET /api/v2/contacts/{contactId}/promotions
You have the option to restrict the response by promotion type (ECOM, POS, OTHER).
Caution
A promotion will be returned if both the assigned promotion AND the main promotion (the "template" it was created from) are active. Redeemed promotions may be included in this response if they otherwise fulfill the criteria for being active.
Upgrading a contact
Engage can handle multiple contact types. For example, you might want to separate your newsletter subscribers from account holders, so you will have a contact type for each.
An account holder usually has contact type "Member". Ideally,this is where you want all your contacts to be. Changing a contact to "Member" is called upgrading. There are two ways to upgrade contacts to members.
The regular update
Here you just do as described in the update section, specifying the new contact type in the payload:
POST /api/v2/contacts/{contactId}
The dedicated endpoint
You could also use the dedicated Engage endpoint for promoting contacts to members:
POST /api/v2/contacts/{contactId}/promoteToMember
We'll assume you followed best practice and stored the contactId during the contact creation step.
Once you have successfully upgraded a contact to a member, it's common to enrich their information, which then needs to be synced to Engage. You can again do this in one of two ways:
Using the standard update endpoint as described above.
Sending the data in the payload when you call the /promoteToMember endpoint. This allows you to promote the contact to a member as well as update their information in a single request.