Overview
You can use this request to create many contacts at once. This request is similar to the Create Contacts in Bulk method, but it runs the contact creation asynchronously.
Once you make the request, we will store the data you have sent and immediately give you a response saying that the data is stored. Then the data will be processed on our side without you having to wait for it to be done within the scope of the API request. Because of this, it should allow for a lot more contacts to be sent at once, whereas bulk create is limited to 2,000 at a time.
The Method
Type | Request | Method |
---|---|---|
REST | POST | https://[Your URL]/api/2.0/contacts/import |
XML-RPC | Call | contacts.ListContacts |
Your method must be structured as follows:
Parameters
Required Parameters
The $contacts function must be passed as an array of contacts.
As with creating single contacts, you must create a new contact with either an email address or a mobile phone number. You must also specify the lists the contact will belong to, and their subscription status.
Property | Type | Description | Default | Required | Read Only |
---|---|---|---|---|---|
list_id | array | An array of list IDs with the subscription status for the contact. For example: array(1 => ‘unconfirmed’, 2 => ‘subscribed’) will subscribe the contact to list with ID 2, and add the contact as an unconfirmed contact to list 1. | empty | yes | no |
string | empty | no | no | ||
mobile | string | Mobile | empty | no | no |
Optional Parameters
You may include any of these optional parameters when adding a contact:
Property | Type | Description | Default | Required | Read Only |
---|---|---|---|---|---|
country_id | integer | Country identifier | 1 | no | no |
city_id | integer | City identifier | 1 | no | no |
name | string | First Name | empty | no | no |
last name | string | Last Name | empty | no | no |
status | string | Status Possible values: on / off / suppressed | on | no | no |
preferred_email_format | string | Email format Possible values: html / text | HTML | no | no |
title | string | Title | empty | no | no |
company_position | string | Position | empty | no | no |
company_name | string | Company Name | empty | no | no |
department | string | Department | empty | no | no |
industry | string | Industry | empty | no | no |
address | string | Address | empty | no | no |
city | string | City | empty | no | no |
country | string | Country | empty | no | no |
state | string | Province / State | empty | no | no |
zip | string | Postal / ZIP code | empty | no | no |
telephone_office | string | Work Number | empty | no | no |
telephone_home | string | Home Number | empty | no | no |
telephone_fax | string | Fax Number | empty | no | no |
date_of_birth | integer | Date of birth (deprecated) | empty | no | no |
tags | string | JSON array containing tag names | empty | no | no |
birth_date | string | Date of birth | empty | no | no |
gender | string | Gender Possible variables: unknown / male / female | empty | no | no |
marital_status | string | Marital status Possible values: unknown / single / married | empty | no | no |
education_level | string | Education level | empty | no | no |
hash | string | hash_key | empty | no | no |
unique_id | string | Unique import identifier | empty | no | no |
id | integer | ID | empty | no | yes |
date_create | integer | Date created | empty | no | yes |
score | float | Contact score | 2 | no | yes |
rating | integer | Contact rating score | 2 | no | yes |
email_status | string | Email status Possible values: none / bouncing / bounced / always send | none | no | yes |
create_notifications | string | Create notification Possible values: yes / no | no | no | no |
email_bounce_hard_count | integer | Hard email bounces | 0 | no | yes |
email_bounce_soft_count | integer | Soft email bounces | 0 | no | yes |
block_bounce_count | integer | Consecutive block bounces | 0 | no | yes |
sms_bounce_hard_count | integer | Hard SMS bounces | 0 | no | yes |
sms_bounce_soft_count | integer | Soft SMS bounces | 0 | no | yes |
sms_bounce_consecutive_count | integer | Consecutive SMS bounces | 0 | no | yes |
complaints_count | integer | Complaints | 0 | no | yes |
forward_count | integer | Forwards | empty | no | yes |
invite_count | integer | Invites | empty | no | yes |
bounce_unidentified_count | integer | Unidentified bounces | 0 | no | yes |
autoresponder_count | integer | Autoresponders | 0 | no | yes |
email_message_ids | string | Email message identifiers | empty | no | yes |
sms_message_ids | string | SMS message identifiers | empty | no | yes |
email_message_count | integer | Email Messages | 0 | no | yes |
sms_message_count | integer | SMS Messages | 0 | no | yes |
message_reads_inferred | integer | Inferred reads | 0 | no | yes |
message_reads_unique | integer | Unique reads | 0 | no | yes |
message_link_clicks | integer | Link clicks | 0 | no | yes |
message_link_clicks_unique | integer | Unique link clicks | 0 | no | yes |
Responses
Type | Description |
---|---|
array | An array that corresponds to the passed array, with the results. The array also contains the $batch_id string, the identifier for this import, which can be used in other API calls to check the progress of the import. |
Code Samples
$json = ' { "contacts":{ "1":{ "contact_email":"michael1@email.com", "on_duplicate":"update", "list_id":{"1":"subscribed"} }, "2":{ "contact_email":"michael2@email.com", "on_duplicate":"update", "list_id":{"1234":"subscribed"}, "tags":["first tag name", "second tag name"] } } } '; $url = '(Your URL)/api/2.0/contacts/import'; $method = 'POST'; $cSession = curl_init(); $headers = array(); $auth = base64_encode($username . ':' . $apikey); $headers[] = 'Authorization: Basic ' . $auth; curl_setopt($cSession, CURLOPT_URL, $url); curl_setopt($cSession, CURLOPT_RETURNTRANSFER, true); curl_setopt($cSession, CURLOPT_HEADER, false); curl_setopt($cSession, CURLOPT_CUSTOMREQUEST, strtoupper($method)); curl_setopt($cSession, CURLOPT_POSTFIELDS, $json); $headers[] = 'Content-Type: application/json'; curl_setopt($cSession, CURLOPT_HTTPHEADER, $headers); $result = curl_exec($cSession); curl_close($cSession);