Contact Insert and Update (Bulk)
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.
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": "[email protected]",
"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
{
"status": "Success",
"message": "Batch request accepted",
"data": {
"BatchId": "ce2c2e48-47e4-4aa0-b4e7-c9deebe29852",
"Processed": null,
"ContactId": null,
"InvalidProperties": [],
"InvalidContactIds": [],
}
}