Skip to main content

Bulk write contacts API

To create multiple contacts at once, the /contacts/bulk API endpoint can be used.

POST /api/v2/contacts/bulk

You can also use this same endpoint to update multiple existing contacts at once:

PATCH /api/v2/contacts/bulk


The maximum number of contacts allowed in one bulk request is 4000. The rate limit for this endpoint is the same as for other endpoints.


If you are planning to do a large migration of contacts, and you have an XML export activated, first get in touch with your Voyado team.

Query string parameters

There are two optional parameters that can be added to the query string:

avoidTriggeringExport: This prevents your bulk contact request from triggering the BI and XML contact exports. The default value is "false" so you only need to include this if you want it to be true. You can read more about this parameter here.


The avoidTriggeringExport parameter only has an effect when doing a bulk update (that is, when using the PATCH operation).

contactType: This allows you to specify the contact type of the contacts you are creating (or updating). If not specified, your default contact type configured in Engage will be used.

A request using these parameters (a bulk update in this case) would look like this:

PATCH /api/v2/contacts/bulk?avoidTriggeringExport=true&contactType=Contact

In this example, all the contacts updated will be of contactType "Contact".

Creation payload

The data needed to bulk create contacts has the same requirements as if you were creating an individual contact using the /contacts endpoint. This means, at a bare minimum, that the key attribute must be included (in this case, it's email).

See the create contact page on the recommended way to create contacts.

    "firstName": "Example1",
    "lastName": "Examplesson",
    "city": "Examplecity",
    "email": ""
    "firstName": "Example2",
    "lastName": "Examplesson",
    "city": "Examplecity",
    "email": ""

If you have specified a contactType in the query string then all these new contacts will be created with that type. If it's not specified, the new contacts will all be created using whatever default contactType you have configured in Engage.

Update payload

When doing a bulk update through the API, you will need to specify the unique contact ID for each contact, along with the value or values you want to change.

    "contactId": "a9cc2989-6a39-4168-b48d-afda77a0139c",
    "lastName": "Exampleberg",
    "city": "Exampelopolis"
    "contactId": "4823f5ab-9d03-41d2-ae1f-afda99a013cb",
    "lastName": "Exampelius"

As when you update a single contact using /contacts, be sure to only send the fields you want to update. Empty fields will overwrite the current values.


All contacts sent in a bulk update must have the same contactType. You either send this in the query string, or else not specify it and the default value will be used. This means you cannot mix contacts of different contactType in the same bulk update request.


If your request has been successful, you'll get a 202: Accepted response. Your data is now ready for processing. A unique batch ID for your request will also be returned as a GUID.


Save this batch ID as you'll need it to check the status of your batch job.

If the request has not been successful, you'll get one of the following HTTP error codes:

  • 422: UnprocessableEntity

  • 503: ServiceUnavailable


Your batch job can take time to be processed. You can check the current status of the job by calling this endpoint with the batch ID:

GET /api/v2/contacts/bulk/status?batchId={batchId}

This will return an object containing one of the following:

"status": "Received": Your payload has been received.

"status": "InProgress": Processing of your data is in progress.

"status": "Done": Your contacts should now be created / updated.

"status": "The request is invalid.": The batch ID you sent could not be found.

"status": "Error": There was an error.

The progress of your batch will be recorded in the integration log.


The log is especially useful when finding out what happened if things go wrong. Read about the integration log here.

Starting the job

Once you get back a status of "Received" your data is ready to be processed. This happens on a schedule, so it might not be completed right away. Keep checking the /status endpoint to see when it's done.

Wrong contact type


If a bulk update contains a contact of the wrong contactType, that contact will be skipped and the job will continue.

Contacts that already exists


If a bulk update contains a contact that already exists in Engage, that contact will be skipped and the job will continue.