Requires an API user access with Admin or Custom routes. |
This article will explain how you bulk insert/update contacts using the /imports endpoint. The endpoint supports the extended import functionality known from the user interface, such as duplicate checks and enrichment of existing contacts.
To better understand the possibilities with the data importer, you may have a look at the article explaining how to upload leads through the UI.
An import is initiated by sending a POST request to the create /imports endpoint - for example:
{ "poolId": 25528, "match": { "fields": [ 2 ], "blacklist": [] }, "updateFields": [ 1, 2, 3 ], "callbackUrl": "https://your-custom-callback-url.dev"}In this case, we are instructing the importer to insert contacts in the pool with ID 25528. This is the only required parameter if you're doing an upload. If you want to utilize more features such as duplicate control, a few more parameters must be added:
Check against import duplicates
Define the $.match.fields with the IDs of which you want to run the duplicate check. You can include any existing contacts in the duplicate check by adding one or multiple pool IDs to $.match.blacklist.
Enrich existing contacts
Instead of entirely skipping existing contacts during the duplicate check, allowed fields for data enrichment are to be defined in $.updateFields.
Since this is an asynchronous process, a callback can be necessary while integrating into external systems. The URL can be added to $.callbackUrl.
For more information, please refer to the official documentation page.
The request will return a response containing the importer ID - for example:
{ "id": 523231, "state": "init", "match": { "fields": [ 2 ], "blacklist": [ 25528 ] }, "updateFields": [ 1, 2, 3 ], "poolId": 25528}The returned ID is now used for populating records to the import request by calling the /imports/{id}/insert endpoint; in this case /imports/523231/insert.
The request should include your contact records in the body, according to the documentation.
[ { "data": { "1": "Peter", "2": "12345678", "3": "8000" } }, { "data": { "1": "Martin", "2": "87654321", "3": "9000" } }]Lastly, initiate the import request by calling /imports/{id}/start.