importContacts method

It is a method of bulk import of contacts. It can also be used for periodic synchronization with the contact database stored on your own server (see also the description of the exportContacts method). You can import data of no more than 500 contacts per call. Larger lists should be imported in several calls (this restriction is due to the limitations of the POST request).

If there are new email addresses among the subscribed ones, they receive the «new» status by default.

Technical limitations: the maximum number of user fields is 50. The timeout for one call is 30 seconds from the moment the request is sent to the server. If no response has been received after the timeout expires, you are recommended to make up to two more attempts, and contact the technical support service if there is no answer.

Principle of use

Syntax and URL to call the method
importContacts (string array field_names, string array data [bool overwrite_tags, bool overwrite_lists])[0]=email ... field_names[N]=MyFieldN&data[0][0][email protected].... &data[N][0][email protected]&overwrite_tags=X&overwrite_lists=X
api_key * API access key
field_names * Array of data column names. There must be at least the «email» or «phone» field, otherwise the method will return an error. The names of the existing user fields and the names of the following system fields can be specified:

Special values for field_names
delete If the field with this name contains 1, the specified contacts in the list are deleted.
tags You can specify the tags assigned to the contact and separate them by commas. Allowed number of tags is 10.
email Contact's email address.
email_status Email status, one of the following: «New» (new), «active» (active), «inactive» (temporarily disabled), «unsubscribed» (unsubscribed from all current and future campaigns). If the status is not specified, «new» is assigned for new addresses. The status value cannot be changed for already existing addresses with the current status other than «active» or «inactive».
email_availability Availability of the address.
email_list_ids List codes separated by comma to which the email address will be subscribed.
email_subscribe_times Dates and time of the subscription separated by comma, the number and order of dates correspond to the number and order of the list codes in email_list_ids. The dates are in UTC, in the «YYYY-MM-DD hh:mm:ss» or «YYYY-MM-DD» format.
email_unsubscribed_list_ids List codes separated by commas into which the -email is included, but from which the contact has unsubscribed. It may seem that this field is redundant, because you can just specify unsubscribed in the email_status field. But if you have several lists, the contact may be unsubscribed, for example, from only one, and then only this list is indicated in email_unsubscribed_list_ids, and the rest are indicated in email_list_ids. The email_status field refers to the address as a whole and can be «active».
email_excluded_list_ids List codes separated by commas into which the -email is included, but from which the contact has been excluded.
phone, phone_status, phone_availability, phone_list_ids, phone_subscribe_times, phone_unsubscribed_list_ids, phone_excluded_list_ids The meaning of the fields matches similar fields for email. Another difference is that phone_status is set to ‘active’ by for new phone numbers by default. Also pay attention that «phone» field value should be passed in the international phone number format (e.g. +79261232323)
data * Array of contact data, each element of which is an array of fields in the order in which field_names follow.Example for two contacts (the email address is included in the 123 list in the first one, and it is outside the lists in the second one):

data[0][0][email protected]&data[0][1]=123&data[1][0][email protected]
overwrite_tags Optional logical field (0 or 1, the default value is 0). It shows whether tags are overwritten (if 1), or only the new ones are added without deleting the old ones (if 0).
overwrite_lists Optional logical field (0 or 1, the default value is 0).

1 means to replace all the data about when and in which lists contacts are included and from which contacts are excluded with new data. I.e., if the contact is now included in three lists and only one is indicated in the email_list_ids, the contact will be included in only one specified after the call, and the time of the subscription will be the one specified in email_subscribe_times (or the current one if the email_subscribe_times field has been skipped).

Return value
JSON object with the following fields:
total Integer decimal non-negative number — the total number of contacts in the input data array. Amount inserted + updated + deleted may be less than the total if there were errors or duplicates.
inserted Integer decimal non-negative number — the number of successfully added contacts, none of which is duplicated.
updated Integer decimal non-negative number — the amount of the updated contact data (email or phone numbers that have already been present in the database).
deleted Integer decimal non-negative number — the number of successfully deleted contacts, both new and existing ones, as well as successfully deleted contacts.
new_emails Integer decimal non-negative number less than or equal to the total. Number of the imported email addresses that have received the «new» status. This number includes the previously existing addresses, the status of which was «new».
invalid Integer decimal non-negative number greater than or equal to zero. The number email addresses that have been imported.
log Array of errors and import warnings, each element is an object with the following properties:

Log parameter fields
index Integer decimal non-negative number — the number of the contact in the data array.
code Error or warning code.
message Error/warning message.
Example of the return value:

    "total":4, "inserted":2, "updated":1, "deleted":2, "new_emails":1, "invalid":2,
       "message":"Invalid email format"},
       "message":"Duplicate telephone number"}

If while importing the limit on the number of contacts within the current tariff plan is exceeded, the response will be returned with a warning:

    "total":1, "inserted":1, "updated":0, "deleted":0, "new_emails":1, "invalid":0,
       "message":"The number of contacts for the current tariff plan has been exceeded (but the string has been added)"
 "warning":"Addresses overlimit for current period" 

Examples of forming the URL request
data[0][0][email protected]&data[0][1]=Anna&data[0][2]=778899&
data[1][0][email protected]&data[1][1]=Kate&data[1][2]=778899&
data[2][0][email protected]&data[2][1]=John&data[2][2]=778899&
data[3][0][email protected]&data[3][1]=Mike&data[3][2]=778899&
data[4][0][email protected]&data[4][1]=Bill&data[4][2]=778899

— add  5 new contacts with addresses 1 .. [email protected] with the names Anna, Kate, John, Mike and Bill to list with the code 778899. We should note that it is more correct to make requests via POST as the admissible length of a request is substantially less in a GET request.

Did we answer to your question?