🌐 EN
Developer Guide

API Methods for Adding Contacts

Main methods of adding/updating contacts:

  • Subscribe contact (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 workflows. New contacts are created with "not confirmed", status and require double opt-in.

  • Add/update 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 workflows.

Useful methods for specific tasks:

  • Get contact (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.

  • Add/update contacts (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.

  • Add/update contacts from external file (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.

Subscribe contact

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 workflows
  • 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.

Workflows launch

Method Subscribe contact is used to create events. You can configure and launch workflow 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 workflow. So you can configure different workflows 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 workflows. 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 workflows 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:

937

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": "[email protected]"
        }, {
            "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"
}

URL for sending request: /api/v1/contact/subscribe

Add/update 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 our platform. It has such features:

  • it allows to add/update from 1 to 1000 contacts with one request
  • created 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 workflow 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": "[email protected]"
        },{
          "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

Workflow 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 the 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.

Add 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 workflow cannot be launched.

URL for sending request: /api/v1/contacts

Update contact

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 workflow 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 Search contacts.

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

Add/update contacts from external files

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 Search contacts 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 workflow to new contacts

The 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.

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 workflow to the contact who has made an order. For example, you can add it to a segment.

Add orders

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

Generate event

How to find a contact creation source

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

1270

To do this go to Contacts → All contacts and press View button against required contact.

A new window with contact information will open.

1301

You will see required information in the field Source.

Source names for different methods

Main methods:

  • Subscribe contact (subscription form)
  • Search contacts (contact import)
  • Search contacts (API)
  • Add/update contacts from external files (contact import)

Methods of sending email/SMS messages:

  • Send email message (single message)
  • Send SMS message (single message)
  • /v1/message/{id}/send (single message)
  • Send prepared message (single message)

Method of sending orders:

  • Add orders (Integration of orders for RFM)