Batch API - Add Multiple Contacts through API
This API allows the user to add contacts in bulk to the CE dashboard.
Important Note
This API is meant for transferring smaller contact groups. For larger data transfers, it is recommended to use our Bulk Upload through file API
General Rules for API Use
- The maximum number of attributes per contact is limited to 20.
- All keys in JSON should be in lowercase (to split longer names, use “_”)
- Both notify email and callback URLs are mandatory to be specified in request api call. Ensure that your callback endpoint is in POST method.
- All attribute fields should be in upper case.
- You can send a maximum size of 1000 contacts in one API call
- Attribute values should be either in string or integer format. If you wish to pass blank or null, then it should be enclosed within double quotes.
We recommend you use Add Contact (Async or Sync Mode) APIs to add single contacts.
API Specs
URL Schema
US IDC:
http://api.netcoresmartech.com/v3/contact/batchadd
Indian IDC:
https://apiin.netcoresmartech.com/v3/contact/batchadd
EU IDC:
https://goapiv3.eu-north-1.eu.netcoresmartech.com/v3/contact/batchadd
Method:
POST
Header:
| Key | Value | Required |
|---|---|---|
| api-key | Your API Key. Please refer this document on how to get API key. | Yes |
Content-Type:
application/json
Body:
| Key | Description | Data-Type | Required | Sample Value |
|---|---|---|---|---|
| listid | List ID | Numeric | Yes | 5 |
| notifyemail | Email to which the job status is to be notified. - Email is only sent when more than one contact is added to the data field. | String | [email protected] | |
| callback | This refers to the pingback URL to receive the status of the upload job. Ensure that your callback endpoint is in POST method. | string | http://client.com/callbackurl.php | |
| primarykey | Primary Key of the Panel | String | ||
| data | Contains the array of Contact details. The format is key value pair. Refer to the sample to understand this better | Array | "data": [{ "NAME": "ABC", "EMAIL": "[email protected]", "MOBILE": 25, "AGE": 24, "CITY": "Mumbai" }, { "NAME": "Jon doe", "EMAIL": "[email protected]", "MOBILE": 25, "AGE": 24, "CITY": "Mumbai" }] |
Sample API Call
Endpoint : http://api.netcoresmartech.com/v3/contact/batchadd
Headers: api-key : <Your API Key>
Content-Type: application/json
Body:
{
"listid": 5,
"notifyemail": "[email protected]",
"callback": "http://client.com/callbackurl.php",
"primarykey": "[email protected]", //e.g email id is primary key
"data": [{
"NAME": "ABC",
"EMAIL": "[email protected]",
"MOBILE": 25,
"AGE": 24,
"CITY": "Mumbai"
}, {
"NAME": "Jon doe",
"EMAIL": "[email protected]",
"MOBILE": 25,
"AGE": 24,
"CITY": "Mumbai"
}]
}
curl --location 'http://api.netcoresmartech.com/v3/contact/batchadd' \
--header 'Content-Type: application/json' \
--header 'api-key: Your API Key' \
--data-raw '{
"listid": 2,
"notifyemail": "[email protected]",
"callbackurl": "http://client.com/callbackurl.php",
"primarykey": "email",
"data": [{
"NAME": "ABC",
"EMAIL": "[email protected]",
"MOBILE": 25,
"AGE": 24,
"CITY": "Mumbai"
}, {
"NAME": "Jon doe",
"EMAIL": "[email protected]",
"MOBILE": 25,
"AGE": 24,
"CITY": "Mumbai"
}]
}'
Response:
Success
{
"message": "39c2e217-b7ca-0196-f7ec-b26e5c7acf4e",
"status": 200
}
Success Status (200)
This API is asynchronous, so a successful status does not guarantee job completion. Track job status using the endpoint in the callback key & email in notifyemail key.
API Limits and Error Description
| Error | Description |
|---|---|
| { "message": "invalid api key", "status": 401 } | API key is invalid |
| { "message": "api key can not be blank in headers", "status": 400 } | "api-key" header should not be blank |
| { "message": "listid should be of type integer", "status":400 } | "listid" key mentioned in the API body should be of integer data type |
| { "message": "you have exceeded the batch limit of 1000", "status":400 } | In one API call, you can add details up-to a maximum of 1000 contacts |
| { "message": "primary key is mandatory and should be string", "status":400 } | "primarykey" key mentioned in the API body is mandatory and should be of String Data type |
| { "message": "callbackurl or notifyemail is mandatory and should be string", "status":400 } | Both the keys "callbackrul" and "notifyemail" mentioned in the API body are mandatory fields |
| { "message": "data should be of type array", "status":400 } | "data" key mentioned in the API body should of type array |
| { "message": "client server not found", "status":400 } | Client server not found |
| { "message": "limit Reached", "status":400 } | The daily limit of API requests made has been reached |
Updated 2 days ago