TLDR: 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.
The external Id field serves as a unique identifier. Creating more than one contact with the same external Id is not permitted.
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 via the API but no external ID is appended during import, it is possible to search for 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 will likewise result in faster response times.