With eduConverse, you can use the Bulk Contact Importer API to upload large numbers of contacts into your account with just one API call.
In this article:
Take note
- The Bulk Contact Importer API is available on all eduConverse plans
- This feature is for advanced users who are familiar with the API and are comfortable using it to import contacts
About the Bulk Contact Importer API
The bulk contact importer is designed to perform operations on large quantities of contacts at one time. These operations include:
- Creating new contacts
- Updating existing contacts
- Setting fields on contacts
- Tagging contacts
- Adding contacts to lists
|
Note The Bulk Contact Importer is not designed to support frequent operations involving a small number of contacts or to sync updates in real-time from an external database. Instead, contact updates should be collected into larger batches and imported as a group. Contacts can be imported in batches of up to 250 items. |
Rate limiting
The bulk importer process is optimized for the upload of larger lists of contacts. Running frequent requests that involve a small number of contacts requires significant overhead, and can affect the importer’s performance.
As a result, we enforce the following rate limits on the Bulk Contact Importer API:
- For requests containing a single contact, there is a limit of 20 requests per minute
- For requests containing multiple contacts, there is a limit of 100 requests per minute
We recommend that all users attempt to batch updates into groups as large as possible before starting an import.
Payload size limiting
The maximum payload size of a single bulk_import request is 400000 bytes.
Skipped contacts
Contacts must meet all the following criteria in order to be created or updated with this API:
- The imported contacts may not exceed your account limit
- The contact must have an email address
- The contact’s email address must not be on an exclusion list
- The contact’s email must not be on a list of bounced email addresses
- The contact must not have unsubscribed to a list that the import would add them to
If contacts do not meet all of these requirements, they will be skipped by the importer.
API documentation
Request Structure
JSON
{
"contacts": [
{
"email": "someone@somewhere.com",
"first_name": "Jane",
"last_name": "Doe",
"phone": “123-456-7890”,
"customer_acct_name": "ActiveCampaign",
"tags": [
"dictumst aliquam augue quam sollicitudin rutrum",
],
"fields": [
{"id": 1, "value": "foo"},
{"id": 2,"value": "foo||bar||baz"}
],
"subscribe": [{"listid": 1}, {"listid": 2}],
"unsubscribe": [{"listid": 3}],
}
],
"callback": <optional, see below>
}
Response
200 OK
{
"Success":1,
"queued_contacts":1,
"batchId":"0641fbdd-f62f-4c2c-ba02-3a83d5d11ac9",
"message":"Contact import queued"
}
400 Bad Request
{
"Success":0,
"message":"JSON payload did not pass validation. Please fix failureReasons and retry. The import was not queued for processing.",
"failureReasons":["Payload must contain a 'contacts' field"]
}
Body Params
contacts* array (object)
An array of objects containing information about a single contact. Up to 250 contacts may be included in a single request. Each contact may contain the following fields:
- email* (string)
The contact’s email.
- first_name (string)
The contact’s first name.
- last_name (string)
The contact’s last name.
- phone (string)
The contact’s phone number.
- customer_acct_name (string)
The name of the contact’s account.
- tags array (string)
Each string in the array will be added as a single tag to the contact. New tags will be created if they do not already exist.
- fields array (object)
A list of custom fields to apply to the contact. Each field must contain two fields: Each contact may have up to N custom fields.
- id* (number)
The ID of the custom field. Custom fields must be referenced by the ID that eduConverse assigns to them. You can retrieve the ID number for a custom field by using the "List all custom fields" API call.
- value* (string)
The value of the custom field. Multiple values may be populated for multi-value fields by separating the different values by the double-pipe delimiter (“||”).
- subscribe array (object)
An array of lists to subscribe the contact to. Contacts may not be subscribed to lists which they have previously unsubscribed from. Each list object contains a single field.
- listid* (number)
The ID of the list to subscribe the contact to. Lists must be referenced by the ID that eduConverse assigns to them.
You can find the list ID by clicking the list in your eduConverse account then viewing the URL bar. It will look something like this: /app/contacts/?listid=19&status=1
You can also retrieve the ID number for a list by using the "Retrieve all lists" API call.
- unsubscribe array (object)
An array of lists to unsubscribe the contact to. Each list object contains a single field.
- listid* (number)
The ID of the list to unsubscribe the contact from. Lists must be referenced by the ID that eduConverse assigns to them.
You can find the list ID by clicking the list in your eduConverse then viewing the URL bar. It will look something like this: /app/contacts/?listid=19&status=1
You can also retrieve the ID number for a list by using the "Retrieve all lists" API call.
Callbacks
The bulk contact endpoint has a callback function to notify users when an import is complete. Include the following information in a contact import request to use this feature:
JSON
{
"contacts": [ ... include contacts here ... ],
“callback”: {
“url“: “www.your_web_server.com“,
“requestType”: “POST”,
“detailed_results”: “true”,
“params”: [
{“key”:””,”value”:””}
]
“headers”: [
{“key”:””,”value”:””}
]
}
}
- url (string)
The URL endpoint which the importer will make a request to once the import has completed.
- requestType (string)
Can be set to either “GET” or “POST”. Determines the type of HTTP request which will be sent to the specified endpoint.
- detailed_results (string)
When set to “true” and the requestType parameter is set to “POST”, the callback will include the number of successes and failures in the originating request, as well as an array of error messages for each failed contact.
- params (array)
A list of parameters to include in the callback request. Add each parameter in the form of a key-value pair. For a GET request, each parameter will be appended to the end of the URL in a query string. For a POST request, parameters will be included in the body of the request.
- headers (array)
A list of headers to include in the callback request. Add each header in the form of a key-value pair.
Examples
Receiving a notification
{
"contacts": [ ... include contacts here ... ],
“callback”: {
“url”: “www.yourwebsite.com/the/api/to/hit”,
“requestType”: “GET”,
“params”: [
{“key”:”msg”,”value”:”hello”}
]
“headers”: [
{“key”:””,”value”:””}
]
}
}
Params will be appended to the URL as query parameters in the case of a “GET” request. Headers will be applied to the request before it is sent. This endpoint accepts any string value for both keys and values for both params and headers.
Posting a message
{
"contacts": [ ... include contacts here ... ],
“callback”: {
“requestType”: “POST”,
“params”: [
{“key”:”msg”,”value”:”Import completed”}
]
“headers”: [
{“key”:”Authorization”,”value”:”Bearer 4u1h_t0k3N”}
]
}
}
Result:
GET www.yourwebsite.com/the/api/to/hit
JSON
[
{“key”:”msg”,”value”:”Import completed”}
]
Import results with error messages
{
"contacts": [ ... include contacts here ... ],
“callback”: {
“requestType”: “POST”,
“detailed_results”: “true”,
“headers”: [
{“key”:””,”value”:””}
]
}
}
When the “detailed_results” parameter is set to "True", the callback will include:
- A JSON object containing the params specified
- Three other fields in the response which can help with monitoring and debugging
Result:
GET www.yourwebsite.com/the/api/to/hit
JSON
{
"Success":1,
"Failures":0,
"failure_reasons":[]
}