Bulk Contact Importer API

```mediawiki Navigation: Main_Page > Developer > API > Bulk Contact Importer API

Use the Bulk Contact Importer API

The Bulk Contact Importer API is a powerful tool in ActiveCampaign that allows users to upload large quantities of contacts in a single API call. This functionality is especially valuable for users who manage extensive contact lists and seek an efficient method to create, update, and manage these contacts effectively. By understanding and leveraging this API, users can streamline their contact management processes, saving time and enhancing data organization.

Introduction

The Bulk Contact Importer API is designed to facilitate operations involving the importation of numerous contacts simultaneously. It provides advanced capabilities, allowing users to not only create new contacts but also update existing ones, manage specific fields, and apply tags or add contacts to lists with ease.

This feature is geared towards advanced users who are familiar with API integrations and are comfortable working with JSON data structures. The ability to import contacts in batches of up to 250 items allows organizations to manage large data influxes efficiently.

How to Access this Feature

To access the Bulk Contact Importer API, you need to perform a POST request to the dedicated endpoint URL:

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

Make sure your API key provides the necessary permissions for bulk import operations.

Step-by-Step Instructions

Here are the detailed steps to utilize the Bulk Contact Importer API:

1. **Prepare Your Contact Data**: Create a JSON structure that includes all necessary fields for each contact you wish to import. Make sure to gather all email addresses, first and last names, phone numbers, tags, and assign the contacts to their respective lists.

  Example structure:
  ```json
  {
      "contacts": [
          {
              "email": "someone@somewhere.com",
              "first_name": "Jane",
              "last_name": "Doe",
              "phone": "123-456-7890",
              "customer_acct_name": "ActiveCampaign",
              "tags": ["example", "contact"],
              "fields": [{"id": 1, "value": "foo"}],
              "subscribe": [{"listid": 1}],
              "unsubscribe": [{"listid": 3}]
          }
      ]
  }
  ```

2. **Set Your Callback URL (Optional)**: If you want to receive a notification when the import completes, include a callback parameter in your request. Specify the URL to which you want the API to send the HTTP request.

  Example callback structure:
  ```json
  "callback": {
      "url": "www.your_web_server.com",
      "requestType": "POST",
      "detailed_results": "true"
  }
  ```

3. **Make the API Request**: Use an API tool such as Postman or write a script in your preferred programming language to send the request. Ensure to include your API credentials and the correct headers to authenticate your request.

4. **Handle the Response**:

   - If your import is successful, you will receive a `200 OK` response indicating that the contacts were queued for import.
   - If the request fails, check for `400 Bad Request` errors which provide details about why the import could not proceed.

Configuration Options and Settings

The Bulk Contact Importer API supports several parameters in the request body:

- **contacts**: An essential array of objects where each object represents a contact. - **email**: The contact's email (required). - **first_name**: The contact's first name (optional). - **last_name**: The contact's last name (optional). - **phone**: The contact's phone number (optional). - **customer_acct_name**: Name associated with the contact's account (optional). - **tags**: Array of strings to categorize contacts (optional). - **fields**: Custom fields to apply to the contact (optional). - **subscribe**: List of lists to which the contact should be subscribed (optional). - **unsubscribe**: Lists to unsubscribe the contact from (optional). - **callback**: Detailed configuration for receiving import notifications (optional).

Make sure your payload does not exceed the limit of 400000 bytes.

Best Practices and Tips

- Always batch your contacts: Aim to bundle your contacts into groups of about 250. Larger batches improve efficiency and reduce the overhead of managing numerous individual requests. - Validate contacts before import: Ensure all contacts have valid email addresses and do not appear on any exclusion lists. - Use callback notifications: Setting up a callback can help monitor the success or failure of your imports without constantly checking the response. - Regularly review your contact limits in ActiveCampaign to ensure compliance with plan limitations.

Troubleshooting

If you encounter issues using the Bulk Contact Importer API, consider the following troubleshooting steps: - **Check for Required Fields**: Ensure that all imported contacts have an email address and that they meet the criteria specified by ActiveCampaign. - **Inspect API Response Codes**: Pay close attention to HTTP status codes. A `400 Bad Request` will provide failure reasons – use these to refine your data structure. - **Monitor Rate Limits**: Be aware of the rate limits associated with the API. For instance, if importing multiple contacts, ensure you stay within the maximum request limits (100 requests per minute for multiple contacts).

Related Features

- API: General API documentation for ActiveCampaign. - Contacts: Learn about individual contact management through the ActiveCampaign API. - Lists: A detailed overview of managing lists in ActiveCampaign.

FAQ

1. What does the Bulk Contact Importer API do?

The Bulk Contact Importer API is used to upload large numbers of contacts to your ActiveCampaign account in one API call, allowing for efficient management of contact data.

2. What is the maximum number of contacts I can import at once?

You can import up to 250 contacts in a single request using the Bulk Contact Importer API.

3. What should I do if some contacts are skipped during the import?

Contacts may be skipped if they do not meet the required criteria, such as not having an email address or being present on exclusion lists. Review the API error messages for specific reasons.

4. Can I use the Bulk Contact Importer API for small batches?

The API is optimized for larger batches. For importing 10 or fewer contacts, it is recommended to use the standard Contacts functionality of ActiveCampaign API V3.

5. How can I improve the performance of my imports?

Batching contacts into larger groups and checking for rate limits can significantly enhance import performance.

6. Is there a way to know when my import has finished?

Yes, you can use the callback feature to receive notifications regarding the completion of your import request.

7. What should I do if my JSON payload fails validation?

Check the error message returned with the `400 Bad Request` response code. Ensure that your JSON structure includes all required fields and is formatted correctly.

By following this comprehensive guide on the Bulk Contact Importer API, users can successfully integrate this functionality into their workflow, ensuring efficient contact management in ActiveCampaign. ```