1. ActiveCampaign Help Center
  2. Contact Management
  3. Add & Export Contacts

Use the Bulk Contact Importer API

Avatar
Sarah N
Last updated
ActiveCampaign plans
Starter
Plus
Pro
Enterprise

With ActiveCampaign, you can use the Bulk Contact Importer API to upload large numbers of contacts into your account with just one API call.

Take note

  • The Bulk Contact Importer API is available on all ActiveCampaign plans
  • This feature is for advanced users who are familiar with the API and are comfortable using it to import contacts
  • Lists feature is only available on Marketing Lite, Plus, Professional, and Enterprise plans

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 (Available on Marketing Lite, Plus, Professional, and Enterprise)

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.

If you need to upload 10 or fewer contacts at a time, please use the Contacts functionality of our ActiveCampaign API V3.

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 payload size of a single bulk_import request must be less than 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

In addition, the following criteria apply only applies to Marketing Lite, Plus, Professional, and Enterprise plans:

  • 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

POST https://youraccountname.api-us1.com/api/3/import/bulk_import

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 ActiveCampaign 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)

    Available on Marketing Lite, Plus, Professional, and Enterprise plans.

    The ID of the list to subscribe the contact to. Lists must be referenced by the ID that ActiveCampaign assigns to them.

    You can find the list ID by clicking the list in your ActiveCampaign 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 ActiveCampaign assigns to them.

    You can find the list ID by clicking the list in your ActiveCampaign 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.

Result:

GET www.yourwebsite.com/the/api/to/hit?msg=hello

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

Related to:

Was this article helpful?
1 out of 7 found this helpful

Have more questions? Submit a request

Start free trial