Contact Insert and Update (Batch)

POST /Contacts/Batch/

This endpoint is used to create or update a group of contacts. In an update, any fields omitted from the request will remain as they were. To maximize performance, we recommend that you limit the batch size to 100 contacts or fewer.

Usage scenario for this endpoint:

This endpoint is especially useful to periodically sync contacts from another database to the Mainbrainer CRM.

Method Details
HTTP Method POST
Content type Application/json
Requires authentication? YES
Rate limited? YES
Headers User-Agent
Module CRM
End Point

https://apicrm.mainbrainer.com/contacts/batch

Note

It can take a few minutes for the changes/updates to be applied to the records because the changes made through this endpoint are processed asynchronously.

Note:

The batch size should not exceed 1000 contacts per request.

Required Parameters Usage Description
Access Token or API Key Authorization: Bearer {token} header Pass the API key in the request header for request authentication. Read more about our authentication process.
Contact JSON Body Request This JSON represents the contacts that you intend to create/update. It should follow the format as demonstrated in the code sample.
ListID listId (uuid) eg: "3fa85f64-5717-4562-b3fc-2c963f66afa6 Each list is assigned a unique List ID that acts as a Unique identifier for the particular list. In case you wish to add the contact to a particular list, specify the list ID of the desired list using the parameter listId. If no list ID is specified, the contact will get added under All contacts.
Update/Insert using Contactid and Mobile/email Used in the request body Each property data set must include either an email address, a mobile number, or a contactID. Since contactID is a unique identifier for a contact, we recommend that you include contactID data whenever possible.

-- Whenever the data set includes the contactID, the existing record with the specified contactID will be updated. In case no record exists with the specified contactID, a new record will be created.
-- In case the data set only includes the mobile number and email address, we update the records based on the combination of the email address and mobile number data: In case a record already exists with the mobile number and email address specified in the request data, the record will get updated. Otherwise, a new contact will be created.
-- In case the data set includes only a mobile number and no email data, we search if a record exists with the specified mobile number and a null email. In case such a record exists, it will be updated. In case no such record exists, a new record will be created.
-- In case the data set includes only an email address and no mobile number, we search if a record exists with the specified email and a null mobile number. In case such a record exists, it will be updated. In case no such record exists, a new record will be created.
propertyid/propertyname propertyid (uuid),propertyname (string) It is mandatory to include either a property name or the property ID in the request body. In case the property ID is mentioned, the property value will be inserted/updated on the basis of the propertyID. In case only the property name is mentioned, the property value will be inserted/updated on the basis of the property name.
mobileOptIn mobileOptIn = boolean and default = true , In case no Opt-in Status send Blank Use this parameter to specify the MobileOpt-In status of the contact.

-- Pass the parameter value as mobileOptIn= true if the contact has opted-in to receive SMS communication from you. If the contact has not opted-in to receive SMS communication from you, pass the parameter value as mobileOptIn= false.
--In case the property is not defined in your request, we'll add/update the contact property as no consent. No communication will be sent to the contact till its mobileOptIn status is updated to true.
emailOptIn emailOptIn = boolean and default = true , In case no Opt-in Status send Blank Use this parameter to specify the Email opt-in status of the contact.

-- Pass the parameter value as emailOptIn= true if the contact has subscribed to receive emails from you. If the contact has not subscribed to your emails, pass the parameter value as emailOptIn= false.
-- In case the property is not defined in your request, we'll add/update the contact property as no consent. No communication will be sent to the contact till its emailOptIn status is updated to true.
Webhook URL Delivery Status Use this parameter to specify the webhook URL where you want to receive updates for the contacts being created. For each batch, the update will specify the following:
• Number of Contacts inserted along with the Contact IDs.
• Number of Contacts updated along with the Contact IDs
• Number of Contacts skipped along with the Contact IDs
Note

If you're working with a known contact, using the ContactID is preferred.

Note

SMSs will only be sent to contacts if their mobileOptIn status is true. Similarly emails will only be sent to contacts if their emailOptIn status is true.

List and List IDs

In the MainBrainer CRM, contacts can be grouped under various Lists. Each list is assigned a unique List ID that acts as a Unique identifier for the particular list. In case you wish to add the contact to a particular list, specify the list ID of the desired list using the parameter listId. If no list ID is specified, the contact will get added under All contacts.

Response

An error in even a single contact will prevent the processing of the entire batch of contacts, and no updates will be made. In this case, we'll return a 400 and 422 response along with additional details listing the cause.

Copy
Copied

This example demonstrates how to update and insert contact properties with two contacts:

one for an existing contact as identified by the contactId or email or mobile no and second for another contact 
that may or may not exist, as identified by the email address and mobile or only email or only mobile.

post url: https://apicrm.mainbrainer.com/contacts/batch


{
"listId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",  
"createUpdateContacts": [
{
  "contactId": 234567,
  "mobileCountryCode": 47, 
  "mobileNumber": 90812501,
  "mobileOptIn": true,
  "email": "apitest@mainbrainer.com",
  "emailOptIn": true,
  "propertyfields": [
    {
      "propertyid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "propertyname": "firstname",
      "propertyvalue": "jennifer"
    },
    {
      "propertyname": "lastname",
      "propertyvalue": "merg"
    },
    {
      "propertyname": "interest",
      "propertyvalue": "ice hockey"
    },
    {
      "propertyname": "company",
      "propertyvalue": "MainBrainer"
    },
    {
      "propertyname": "Street",
      "propertyvalue": "16 Av Street"
    },
    {
      "propertyname": "city",
      "propertyvalue": "Oslo"
    },
    {
      "propertyname": "state",
      "propertyvalue": "Oslo"
    },
    {
      "propertyid": "3fa85f64-5717-4562-b3fc-123123d23dds",
      "propertyvalue": "0236"
      }
  ]
},
{
  "mobileCountryCode": 47, 
  "mobileNumber": 93454496,
  "mobileOptIn": true,
  "email": "",
  "propertyfields": [
    {
      "propertyid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "propertyname": "firstname",
      "propertyvalue": "Mark"
    },
    {
      "propertyname": "lastname",
      "propertyvalue": "hugeine"
    },
    {
      "propertyname": "interest",
      "propertyvalue": "sking"
    },
    {
      "propertyname": "company",
      "propertyvalue": "MainBrainer"
    },
    {
      "propertyname": "Street",
      "propertyvalue": "Willy Thoresens"
    },
    {
      "propertyname": "city",
      "propertyvalue": "Oslo"
    },
    {
      "propertyname": "state",
      "propertyvalue": "Oslo"
    },
    {
      "propertyid": "3fa85f64-5717-4562-b3fc-123123d23dds",
      "propertyvalue": "0234"
      }
  ]
}
],
"webhookUrl": "https://webhook-url.yourdomain.com"
}
Returns a 202 Accepted response with content on success.
    

Response Body

Copy
Copied
{
    "status": "Success",
    "message": "Batch request accepted",
    "data": {
        "BatchId": "ce2c2e48-47e4-4aa0-b4e7-c9deebe29852",
        "Processed": null,
        "ContactId": null,
        "InvalidProperties": [],
        "InvalidContactIds": [],
        
    }
}