API Methods for Adding Contacts

{
    "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"
}

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 the following features:

• It allows to  add/update from 1 to 3000 contacts in one request.
• Created contacts are already confirmed, same as when imported.
• It allows to add contacts to segments or delete them 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.
• The response returns asyncSessionId. You can use this asyncSessionId parameter in the Get contact import status method to get import status and ID of contacts.

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"
}

URL for sending request: /api/v1/contacts

If your API request is correct, the response returns the HTTP 200 success status code.

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 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 will be updated
• 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.

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

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

Attach contact to static segment

Method type: POST. Method description.

This method adds contacts by contactId or externalCustomerId to a segment of the List type (use only one contact identifier in the request). The maximum number of contacts in one request is 500.

URL for sending request: /api/v1/group/{id}/contacts/attach

{id} needs to be substituted with a numeric segment identifier in our system. 

File requirements and request body format are available here.

Delete from static segment 

Method type: POST. Method description.

This method deletes contacts by contactId or externalCustomerId from a segment of the List type (use only one contact identifier in the request). The maximum number of contacts in one request is 500.

If you do not specify IDs, all contacts will be removed from the segment.

URL for sending request: /api/v1/group/{id}/contacts/detach

{id} needs to be substituted with a numeric segment identifier in our system. 

File requirements and request body format are available here.

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.

• send email message
• send SMS message
• /v1/message/{id}/send
• send prepared message

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

To do this go to Contacts → All 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:

• 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)