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 (see more here):
GET api/v3/contacts/idAs part 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/v3/contactsEngage returns the code 201 if the creation has been 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 errors, you'll need a plan in place to ensure that no data is lost.
Validation errors: Follow the error instructions to ensure good data quality prior to retry creation (POST). See here.
Retry: In the case of no answer and/or 500 error, perform a retry. Follow 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 contacts 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/v3/contacts/id
When you know the contactId, the update is then done like this:
PATCH api/v3/contacts/{contactId}
The contact attributes to be updated are sent in the request payload.
Caution
You can't use this endpoint to update a contact's contact type. This has to be done using the /contacts/{contactId}/updateContactType endpoint. See "Upgrading a contact" below.
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/v3/contacts/{contactId}
GET /api/v3/contacts/transactions
GET /api/v3/promotion-assignments
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 /contacts/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/v3/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, along with article data, use the second endpoint:
GET /api/v3/contacts/transactions
The contactId is sent as a query string parameter.
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/v3/promotion-assignments
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 from other type to "Member" is called upgrading.
Upgrading contacts is done using the following endpoint:
POST /api/v3/contacts/{contactId}/updateContactType?contactTypeId=Member
When upgrading a contact to a member, it's common to enrich their information, which then needs to be synced to Engage. Do this using the regular update method shown above.