Bulk write contacts API

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.

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".

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.

This is a basic bulk creation payload:

[
  {
    "firstName": "Anna",
    "lastName": "Arkberg",
    "city": "Examplecity",
    "email": "anna@example.com"
  },
  {
    "firstName": "Berit",
    "lastName": "Berlucci",
    "city": "Examplecity",
    "email": "berit@example.com"
  }
]

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.

If you want to send contact preferences when using bulk creation, you will do it like this:

[
  {
    "firstName": "Anna",
    "lastName": "Arkberg",
    "city": "Examplecity",
    "email": "anna@example.com",
    "acceptsEmail":true,
    "acceptsPostal":false,
    "acceptsSms":false
  },
  {
    "firstName": "Berit",
    "lastName": "Berlucci",
    "city": "Examplecity",
    "email": "berit@example.com",
    "acceptsEmail":true,
    "acceptsPostal":false,
    "acceptsSms":true
  }
]

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": "Berg",
    "city": "Exampelopolis"
  },
  {
    "contactId": "4823f5ab-9d03-41d2-ae1f-afda99a013cb",
    "lastName": "Ek",
    "city": "Exampelholm"
  },   
  {
    "contactId": "8afa642d-d4e2-4040-a573-2dc20ea6b9a0",
    "lastName": "Sten",
    "city": "Exampelholm"
  }
]

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.

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.

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

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.

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.