TL;DR: Contacts support external IDs, in addition to the Adversus (internal) ID.


While integrating Adversus with external systems, keeping track of the contact entity systems in between is essential. For that purpose, we use an identifier that could come from Adversus or the external service.

While POSTing new contacts to Adversus, an external ID can be appended 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 are visible from the Warehouse and available in PATCH requests (using either the internal or external ID).


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 - it is possible to search contacts by key/value pairs, for example, by a company registration number or similar. It is even possible to search for contacts based on multiple fields 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.


Did this answer your question?