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

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:

  1. /rewards endpoint

    An external_id query parameter is used

    Example

    A GET request http://region.api.antavo.com/rewards?customer=customer_id&external_id=external_id_field

  1. /rewards/{reward_id}/claim endpoint

    An external_id fields is included in the request body

    Example

    A POST request http://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.