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

🚧

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": "[email protected]",
      "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.