Using the Bulk Contact Importer API

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

📘
Use exclude_automations to skip running automations on imports
Using this parameter will improve the import time.
If exclude_automations: true is included in the payload, automations will NOT run when bulk importing contacts.
By default, automations will run when doing a bulk import.

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 for less than 10 contacts:
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 maximum payload size of a single bulk_import request must be less than less than 400K bytes (399,999 bytes or less).

"Excluded" Emails will be Skipped

Any emails emails contained in a bulk import will be compared against your "Email Exclusions" list.
If an email is important that is in your exclusion list, the Bulk Import API response will be 200 "Success" but will contain:

{"success":5,"queued_contacts":2,"batchId":"59f14dbe-a54f-4d84-a3f6-a13849Aa3eb","message":"Contact import queued"}\`

A call to import status will show the skipped emails:

{"status":"completed","success":["5232"],"failure":["excluded_email1@example.com", "excluded_email2@example.com"]}

🚧
Why Bulk Imports Fail
Examples of invalid formatting that will fail an import:

Username before @ must have a length of at least 1 character.

Address does not contain special characters such as " ( ) , : ; < > @ [ \ ]

An @ symbol is required between the email username and domain url.

A . is required in the address's domain url, and there must be at least two letters after the . containing no special characters.

Other reasons for failure:

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

{
  "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": {
    "url": "www.your_web_server.com",
    "requestType": "POST",
    "detailed_results": "true",
    "params": [
      { "key": "", "value": "" }
    ],
    "headers": [
      { "key": "", "value": "" }
    ]
  }
}

{
   "Success":1,
   "queued_contacts":1,
   "batchId":"0641fbdd-f62f-4c2c-ba02-3a83d5d11ac9",
   "message":"Contact import queued"
}

❗️
400 Errors can take two forms
If the error occurs during contact creation, the error will return failureReasons as a list of objects, and a nested contact indicating which Contact the failure occurred with.
If the failure is more general (for example, rate limit exceeded), the error will return failureReasons as a list of strings.