API methods for adding contacts

Main methods of adding/updating contacts:

  • /v1/contact/subscribe (Method type: POST)
    This method is used to embed subscription form into the website. It creates new contacts and updates existing ones. It also creates events in the system to launch scenarios. New contacts are created with "not confirmed", status and require double opt-in. More.
  • /v1/contacts (Method type: POST)
    This method is used to import or update contacts. It has all the features of contact management through API. It allows to add/update one contact or a bulk of contacts, as well as move contacts from one segment to another. Created contacts are already confirmed, that is why this method is not used with subscription forms. It is not designed to launch scenarios. More.

Useful methods for specific tasks:

  • /v1/contact (Method type: POST)
    This method is used to add one contact. It always creates a new contact, even if contact list already contains contacts with such email or phone number. So, using this methods contact duplicates may be created. This method doesn’t allow updating existing contacts. More.
  • /v1/contact/{id} (Method type: PUT)
    This method is used to update one contact. It doesn’t allow creating new contacts. To update a contact using this method you need to know contact id in our system. More.
  • /v1/contacts/upload (Method type: POST)
    This method is used to add/update contacts from an external file. You can upload a file with contacts to your server and launch import from this file using this method. Link to file is submitted in the request. Our system downloads the file and imports contacts from it. More.

Additional details:

  • Other methods used for contact creation.
    Some API methods don’t allow creating contacts. They are designed for other tasks. However, in some cases use of such methods results in contact creation. More.
  • How can I find out how contact was created? More.

/v1/contact/subscribe

Method type: POST. Method description.

This method is used to add and update contacts. It is aimed at embedding subscription forms and has the following features:

  • new contacts are created with unconfirmed email addresses
  • one contact can be added in one request
  • contacts are created with maximum speed and are not delayed
  • it allows to create events to launch scenarios
  • if the email address or phone number are already in the contact list, a new contact is not created, instead existing contact is updated

Please note! The configuration of confirmation procedure of contact’s email is a must. You can find instructions here: Subscription form configuration.

This method allows adding contacts to any segment. However, you cannot delete contacts from segment using this method.

Scenario launch

Method /v1/contact/subscribe is used to create events. You can configure and launch scenario automatically for contacts sent with this method. Two types of events are created:

  • subscribeFromApi - event title for new contacts
  • subscribeUpdateFromApi - event title for existing contacts in the system

Every event type can launch its own scenario. So you can configure different scenarios for new contacts and contacts created earlier. In addition to that, if you have several subscription forms, you can configure creation of other events to launch other scenarios. To do this use optional parameter formType in the request body. Its value is added after the name of event type (hyphenated). For example, if you send "formType": "abc", the event will look like:

  • subscribeFromApi-abc - for new contacts
  • subscribeUpdateFromApi-abc - for existing contacts

See below example of a request with this parameter.

Each event contains 2 parameters:

  • ContactId - numerical contact id in our system
  • EmailAddress - email address. If only telephone numbers are sent, this parameter is not available

These parameters can be used in scenarios like this: ${name_parameter}. For example, ${EmailAddress}.

Event key is contact id in our system.

If the request is submitted successfully, such events will appear in Event log:

Example of request body

Not all the elements are obligatory. Use those, which you need. Format and description of all fields are available here.

{
    "contact": {
        "channels": [{
            "type": "email",
            "value": "mail@example.com"
        }, {
            "type": "sms",
            "value": "380942583691"
        }],
        "firstName": "John",
        "lastName": "Smith",
        "address": {
            "town": "London",
            "region": "West",
            "address": "First str. 1",
            "postcode": "12345"
        },
        "fields": [{
            "id": "12345",
            "value": "..."
        }]
    },
    "groups": ["Subscribers"],
    "formType": "abc"
}
 
See another example here.
URL for sending request: /api/v1/contact/subscribe
 

/v1/contacts

Method type: POST. Method description.

This method allows to add/update one contact or a bulk of contacts. In fact, it substitutes manual import of contacts from a file. It works for synchronization of your CRM contact list with eSputnik. It has such features:

  • it allows to  add/update от 1 до 1000 contacts with one request
  • сreated contacts are already confirmed, like when imported
  • it allows to add a contact to segments or delete it from segments
  • contacts are added/updated not instantly, it may take a few minutes
  • it allows to create an event to launch a scenario for new contacts

ВажноPlease note! New contacts submitted with this method are created with confirmed email addresses. It is assumed that these contacts have been already verified with double opt-in in other system. Sending campaigns to contacts whose emails were not verified with double opt-in is spamming.

Example of request body

Not all the elements are obligatory. Use those, which you need. Format and description of all fields are available here.

{
    "contacts": [{
        "channels": [{
            "type": "email",
            "value": "mail@example.com"
        }, {
            "type": "sms",
            "value": "380942583691"
        }],
        "firstName": "John",
        "lastName": "Smith",
        "address": {
            "town": "London",
            "region": "West",
            "address": "First str. 1",
            "postcode": "12345"
        },
        "fields": [{
            "id": 12345,
            "value": "..."
        }]
    }],
    "dedupeOn": "email",
    "customFieldsIDs": [12345],
    "groupNames": ["Customers"],
    "groupNamesExclude": ["Subscribers"],
    "restoreDeleted": false,
    "eventKeyForNewContacts": "newContact"
}

 

Arrays groupNames and groupNamesExclude are used to add contacts to segments and to delete contacts from segments respectively.
Parameter dedupeOn shows how contact uniqueness is checked. Receiving request the system searches contacts in contact list by specified feature (in this case be an email address). If the contact is found, it will be updated. If it is not found, the new contact will be created.

URL for sending request: /api/v1/contacts

Scenario launch

This method allows to create events only for new contacts. To create events add parameter eventKeyForNewContacts to request body. Value must be a line with Latin symbols and figures with no spaces. Value is used as event type key and its title.

For each new contact the system creates an event with the following parameters:

  • contactId - numerical contact id in our system
  • EmailAddress - email address (if not sent, the line will be empty)
  • SMS - phone number (if not sent, the line will be empty)

Email address is used as event key. If it is not sent, a phone number is used.


/v1/contact

Method type: POST. Method description.

This API method is used to create a new contact. Features:

  • if a contact with the same email address or phone number already exists, it won’t be updated, instead a new contact (duplicate) will be created
  • one contact is created at a time
  • created contacts are already confirmed. It doesn’t allow configuring double opt-in
  • events are not created. The scenario cannot be launched.

Request body format and description of fields are available here.

URL for sending request: /api/v1/contacts

/v1/contact/{id}

Method type: PUT. Method description.

This method is used to update one contact. Features:

  • it doesn’t allow creating contacts. It is designed to update existing contacts
  • it allows to update one contact at a time
  • contact identification is possible only by id
  • events are not created. The scenario cannot be launched.

Request body format and description of fields are available here.

URL for sending request: /api/v1/contact/{id}
{id} needs to be substituted with numeric contact identifier in our system. It can be obtained with method for contact search by email or by other parameters /v1/contacts GET. /v1/contacts GET.

Use of identifiers may be inconvenient. So you can update contacts by email or phone number with method /v1/contacts POST.

 

/v1/contacts/upload

Method type: POST. Method description.

It allows to add or update contacts from external file. You can upload a file with contacts to your server and launch contact import from it with this method. Our system downloads the file and imports contacts from it. This method has the same features as method /v1/contacts POST except the fact that contact data are not sent in the request. They are saved in a separate file.

Method features:

  • сontacts are submitted not in request body, but in a separate file
  • сreated contacts are already confirmed, like when imported
  • it allows to add a contact to segments and delete it from segments
  • contacts are added/updated not instantly, it may take a few minutes
  • it allows to create an event to launch a scenario to new contacts

Thr file must be saved in CSV format with encoding UTF-8. File requirements and request body format are available here.

The file should be saved at Http-resource. URL of the file is indicated in request body in parameter link. Specify login and password in URL to get access to the file.

URL for sending request: /api/v1/contacts/upload
 

Other API methods which may result in contact creation

There are several API methods with other purposes, but in some cases, the use of these methods results in contact creation. In such cases created contacts are already confirmed, but aren’t included in any segments.

Methods for sending messages (email/SMS).
If a message is sent to a user not from contact list, such contact is created at the moment of sending. Only communication channel (email address or phone number) is sent to this new contact. No other fields are completed. It is not included in any segments. Events are not created.

  • /v1/message/email
  • /v1/message/sms
  • /v1/message/{id}/send
  • /v1/message/{id}/smartsend

Method of submitting orders.
When an order is added to our system, the system verifies whether there is a contact with a specified email address or phone number in the contact list. If not, it is created. Some order data, such as email address, phone number, name/surname are sent to this new contact. Please note that if the contact already exists in contact list, it won’t be updated. Name/surname from the order won’t be added.
This method allows to create events in the system. So you can do some additional operations launching scenario to the contact who has made an order. For example, you can add it to a segment.

  • /v1/orders

Contact creation/update with event and scenario.
You can send event through API to launch the scenario for contact creation or update. To do this there are specific blocks in scenario. You need to submit contact’s email address and a line with the required format in event parameters to complete contact’s fields.

  • /v1/event

How to find a contact creation source

You can always check which method was used to create a contact

Источник контакта

To do this go to ContactsAll contacts and press View button against required contact.

A new window with contact information will open.

Просмотр контакта

You will see required information in the field Source.

Source names for different methods

Main methods:

  • /v1/contact/subscribe (subscription form)
  • /v1/contacts (contact import)
  • /v1/contact (API)
  • /v1/contacts/upload (contact import)

Methods of sending email/SMS messages:

  • /v1/message/email (single message)
  • /v1/message/sms (single message)
  • /v1/message/{id}/send (single message)
  • /v1/message/{id}/smartsend (single message)

Method of sending orders:

  • /v1/orders (Integration of orders for RFM)