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/v3/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 when creating an individual contact using the /contacts endpoint. This means, at a bare minimum, that the key attribute must be included in the payload (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.

There is an important difference between creating contacts individually with the contacts endpoint and creating them in bulk using the contacts/bulk endpoint discussed here.

Consents and preferences are sent as object arrays in the basic create endpoint:

{
  "firstName": "Anna",
  "lastName": "Arkberg",
  "city": "Examplecity",
  "email": "anna@example.com",
  "preferences": {
    "acceptsEmail": true,
    "acceptsPostal": true,
    "acceptsSms": true
  },
  "consents": [{
      "id": "memberConsent",
      "value": true,
      "date": "2022-01-01T00:00:00+0100",
      "source": "ECOM",
      "comment": "Approved member terms at checkout"
   }]
}

But in the bulk API case contact data is sent "flat", as can be seen here in these two contacts:

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

Note that here memberConsent is sent as an attribute and a value, not as an object. In Engage, this consent's date attribute will be the date of the bulk import and the source will be set to "Import".

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"
  }
]

Here is a full update payload with all the contact attributes you can send.

[
  {
    "street": "Example Avenue 12",
    "lastName": "Person",
    "firstName": "Test",
    "zipCode": "string",
    "careOf": "careOf",
    "city": "Examplecity",
    "countryCode": "SE",
    "consent": "true",
    "acceptsEmail":true,
    "acceptsPostal":false,
    "acceptsSms":false,
    "email": "test.person@test.com",
    "mobilePhone": "+46700111222",
    "age": 65,
    "birthDay": "2004-04-11",
    "gender": "Female",
    "socialSecurityNumber": "190703316893",
    "discoveryKey": "87bd3b56-a1fd-4060-9962-4f08ef047251",
    "lang": "en",
    "registrationStoreId": "SE",
    "labels": "Label1,Label2"
  }
]

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/v3/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.