Skip to main content

Working with contact identifiers

Jonas Klærke Hejlskov
  • Updated

TLDR: Contacts supports external IDs, in addition to the Adversus (internal) id.

While integrating Adversus with external systems, is it essential to keep track of the contact entity systems in between. For that purpose, we are using an identifier that could either come from Adversus or the external service.

While POSTing new contacts to Adversus, an external id is possible to append to the request.

curl --location --request POST 'https://api.adversus.io/contacts' \
--header 'Authorization: Basic XX' \
--header 'Content-Type: application/json' \
--data-raw ' {
 "poolId": 25518,
 "externalId": "ABCD1234",
 "data": {
   "1": "John Doe",
   "2": "+1 (337) 385 5102"
 }
}'

Both the internal (Adversus) and external ID is visible from the warehouse and are available in PATCH requests (using either the internal id or the external id).

Sk_rmbillede_2020-11-09_kl._14.12.01.png

 

What if contacts are uploaded without the external id?

In cases where we want to keep manually uploaded contacts updated from the API - but no external ID is appended during import - is it possible to search contacts by key/value pairs, for example, searching contacts by a company registration number or similar. It is even possible to search for contacts based on multiple fields — hence using concatenated field values. 

These requests are made using the contacts findByData-endpoint.

curl --location --request POST 'https://api.adversus.io/contacts/findByData' \
--header 'Authorization: Basic XX' \
--header 'Content-Type: application/json' \
--data-raw '{
 "1": "John Doe",
 "2": "+1 (337) 385 5102"
}'

The endpoint will return the internal id, which then can be used for further processing. 

Please be aware that it is generally considered best practice to use either the internal or external ID, which likewise will cause faster response times. 

Related articles