Generic selectors
Exact matches only
Search in title
Search in content
Search in posts
Search in pages

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])
https://api.unisender.com/en/api/importContacts?format=json&api_key=KEY&field_names[0]=email … field_names[N]=MyFieldN&data[0][0]=test@example.org…. &data[N][0]=test2@example.org&overwrite_tags=X&overwrite_lists=X
Arguments
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
deleteIf the field with this name contains 1, the specified contacts in the list are deleted.
tagsYou can specify the tags assigned to the contact and separate them by commas.
emailContact’s email address.
email_statusEmail 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_availabilityAvailability of the address. See the description of the email_availability field in the exportContacts method.
email_add_timeDate and time of when the subscription address/request was added, in the «YYYY-MM-DD» or «YYYY-MM-DD hh:mm:ss» format, in GMT (UTC).
email_request_ipYou can specify the IP address, format from which the subscription request was received, in the «NNN.NNN.NNN.NNN». It is optional, but there are more strict restrictions on the number of contacts per day when it is not specified. IP addresses from the «internal» subnetworks are not counted.
email_confirm_timeDate and time of when the subscription was confirmed, in the «YYYY-MM-DD» or «YYYY-MM-DD hh:mm:ss» format, in GMT (UTC).
email_list_idsList codes separated by comma to which the email address will be subscribed.
email_subscribe_timesDates 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_idsList 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_idsList codes separated by commas into which the -email is included, but from which the contact has been excluded.
phone, phone_status, phone_availability, phone_add_time, phone_request_ip, phone_list_ids, phone_subscribe_times, phone_unsubscribed_list_ids, phone_excluded_list_idsThe meaning of the fields matches similar fields for email. Please note that there are no phone_confirm_ip and phone_confirm_time fields for phone numbers. 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):

field_names[0]=email&field_names[1]=email_list_ids&
data[0][0]=a@example.com&data[0][1]=123&data[1][0]=b@example.org
overwrite_tagsOptional 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_listsOptional 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:
totalInteger 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.
insertedInteger decimal non-negative number — the number of successfully added contacts, none of which is duplicated.
updatedInteger decimal non-negative number — the amount of the updated contact data (email or phone numbers that have already been present in the database).
deletedInteger decimal non-negative number — the number of successfully deleted contacts, both new and existing ones, as well as successfully deleted contacts.
new_emailsInteger 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».
invalidInteger decimal non-negative number greater than or equal to zero. The number email addresses that have been imported.
logArray of errors and import warnings, each element is an object with the following properties:

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

{
  "result":{
    "total":4, "inserted":2, "updated":1, "deleted":2, "new_emails":1, "invalid":2,
    "log":[
      {"index":0,"code":"e_email_invalid", 
       "message":"Invalid email format"},
      {"index":2,"code":"e_phone_not_unique", 
       "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:

{
  "result":{
    "total":1, "inserted":1, "updated":0, "deleted":0, "new_emails":1, "invalid":0,
    "log":[
      {"index":0,"code":"w_common_overlimit", 
       "message":"The number of contacts for the current tariff plan has been exceeded (but the string has been added)"
}
 ] 
 },
 "warnings":[
 {
 "warning":"Addresses overlimit for current period" 
 }
 ]
}

Examples of forming the URL request

https://api.unisender.com/en/api/importContacts?format=json&api_key=KEY&
field_names[0]=email&field_names[1]=Name&field_names[2]=email_list_ids&
data[0][0]=1@example.com&data[0][1]=Anna&data[0][2]=778899&
data[1][0]=2@example.com&data[1][1]=Kate&data[1][2]=778899&
data[2][0]=3@example.com&data[2][1]=John&data[2][2]=778899&
data[3][0]=4@example.com&data[3][1]=Mike&data[3][2]=778899&
data[4][0]=5@example.com&data[4][1]=Bill&data[4][2]=778899

— add  5 new contacts with addresses 1 .. 5@example.org 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.