External ID#
Note
This approach requires the Uniform Customer Profile module. Please contact Service Desk if you don’t have this module enabled.
![../_images/uniform_profile.bmp](../_images/uniform_profile.bmp)
Any customer string field can be made an external ID field by adding the external_id
tag to the suitable attribute.
This process is described in the User manual and the additional requirements for an external ID customer field are:
it is only possible for string type attributes
the field name should not match any extension names
the field name should minimize any confusion with any third party systems e.g., newsletterproviders
Usage#
External IDs can be be currently used on the following endpoints:
External IDs are supported for every endpoint listed in the Customer API in the following format:
https://api.region.antavo.com/customers/external_field:external_customer_id
Example
A customer merge request using a POST
requests to https://api.region.api.antavo.com/customers/external_id_field:external_id_value/merge
//request body:
{
"source": "{external_field:external_id_value}"
}
//or
{
"target": "{external_field:external_id_value}"
External IDs are supported for every endpoint listed in the Display API in the following format:
https://api.region.antavo.com/customers/external_field:external_customer_id
Example
https://api.rc.antavo.com/customers/loyalty_barcode:1234-5678-9123
External IDs are supported for the Entities API endpoints in the following format:
https://api.region.antavo.com/custom entity collection/custom entity ID/external_field:external_customer_id
Example
http://api.rc.antavo.com/entities/core/customer/loyalty_barcode:1234-5678-9123
External IDs support for Events submitted to Antavo to the Events API require an external_id
field.
Example
{ "action": "point_add", "customer": "1234-5678-9123", "external_id": "loyalty_barcode", "data": { ... } }
Warning
This API will be deprecated in the near future. Please use the reward section in the Display API for future projects.
This module has two distinct forms:
/rewards
endpointAn
external_id
query parameter is usedExample
A
GET
requesthttp://region.api.antavo.com/rewards?customer=customer_id&external_id=external_id_field
/rewards/{reward_id}/claim
endpointAn
external_id
fields is included in the request bodyExample
A
POST
requesthttp://api.{region}.antavo.com/rewards/{reward_id}/claim
request body: { "customer": "{customer_id}", "external_id": "{external_id_field}" }
Bulk Submission#
Bulk endpoints process submission on one-by-one basis and thus it is possible to submit data containing both customer ID and external ID.
A typical submission to the /entities/bulk
endpoint showcasing mixed customer ID and external ID entries.
{
"entities": [
{
"method": "PUT",
"type": "core/customer",
"id": "CUST000001",
"data": {
"barcode": "1234-5678-9123"
}
},
{
"method": "POST",
"type": "core/customer",
"id": "loyalty_barcode:1234-5678-9123",
"data": {
"first_name", "Test"
}
},
{
"method": "GET",
"type": "core/customer",
"id": "CUST000001"
}
],
"error_handling": "pre-check"
}
A typical submission to the /events/bulk
endpoint showcasing mixed customer ID and external ID entries.
{
"events": [
{
"customer": "CUST000001",
"action": "opt_in",
"data": {
"loyalty_barcode": "1234-5678-9123"
}
},
{
"customer": "1234-5678-9123",
"external_id": "loyalty_barcode",
"action": "profile",
"data": {
...
}
},
{
"customer": "CUST000001",
"action": "point_add",
"data": {
"points": 1
}
}
]
}
It is also possible to access customers in the back office
/customers/{external_field:external_customer_id}
Note
It is currently not possible to create a customer using an external ID. Internal integrations, such as the salesforce salescloud module, can create customer using an external ID. However, this uses a different internal-only mechanism.