How to: sync contacts

Intro

In this section, we will cover how to create/update contacts in Omnisend using the Contacts REST API. It enables the following features:

Automated Campaigns: Set up automated email and SMS campaigns based on customer behaviour, such as welcome emails, abandoned cart reminders, and re-engagement campaigns.
Segmentation: Create targeted customer segments based on demographics, behavior, or custom attributes to deliver personalised marketing messages.
Analytics and Reporting: Analyse customer data and campaign performance to optimize marketing efforts and improve customer engagement.

See the detailed API reference for contacts

Create contact

In order to create contacts one by one use the POST /contacts endpoint.

Note: Two contacts cannot share same identifier. If you try to create a contact with an identifier that already exists for another contact, the system will ignore the identifier. If it is the only identifier, the contact will not be created.

Here's an example using the curl command to create a new contact with email identifier:

curl --request POST \
     --url https://api.omnisend.com/v3/contacts \
     --header 'X-API-KEY: MERCHANT_API_KEY' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "identifiers": [
    {
      "channels": {
        "email": {
          "status": "subscribed",
          "statusDate": "2020-02-29T10:07:28Z"
        }
      },
      "id": "[email protected]",
      "type": "email",
      "sendWelcomeMessage": true
    }
  ],
  "firstName": "Jane",
  "lastName": "Doe",
  "country": "United Kingdom",
  "countryCode": "GB",
  "city": "London",
  "address": "Westminster",
  "postalCode": "SW1A 1AA",
  "gender": "f",
  "birthdate": "1997-05-02"
}
'

Create contacts in a batch

Using the batch endpoint to create contacts saves time, minimises API calls, reduces rate limit risks, and improves scalability.

We recommend keeping the payload size limited to a maximum of 1MB to ensure optimal performance and efficient data transmission.

Use POST /batches endpoint to create multiple contacts. Here is an example:

curl --request POST \
     --url https://api.omnisend.com/v3/batches \
     --header 'X-API-KEY: MERCHANT_API_KEY' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
    "method": "POST",
    "endpoint": "contacts",
    "items": [
        {
          "identifiers": [
            {
              "type":"email",
              "id": "[email protected]",
              "channels": {
              "email": {
                "status": "subscribed",
                "statusDate": "2019-05-30T14:11:12Z"
                }
              }
            }
          ]
        },
        {
          "identifiers": [
          {
            "type":"email",
            "id": "[email protected]",
            "channels": {
              "email": {
                "status": "subscribed",
                "statusDate": "2019-05-30T14:11:12Z"
                }
              }
            }
          ],

         "firstName":"Vanessa"
        }
    ]
}
'

Update contacts

Use the PATCH /contacts/{contactId} endpoint to update an existing contact.

Note: Two contacts cannot share the same identifier. If you try to update a contact with an identifier that already exists for another contact, the system will ignore the identifier.

Here's an example using the curl command:

curl --request PATCH \
     --url https://api.omnisend.com/v3/contacts/6321837c0b053d1f29598dad \
     --header 'X-API-KEY: MERCHANT_API_KEY'
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "identifiers": [
    {
      "channels": {
        "email": {
          "status": "subscribed"
        }
      },
      "id": "[email protected]"
    }
  ],
  "customProperties": {
    "shoeSize": 42,
    "eyesColor": "blue",
    "maritalStatus": "single"
  },
  "city": "Los Angeles"
}
'

Use the PATCH /contacts/{contactId} endpoint to update an existing contact.
Here's an example using the curl command:

curl --request PATCH \
     --url https://api.omnisend.com/v3/contacts/6321837c0b053d1f29598dad \
     --header 'X-API-KEY: MERCHANT_API_KEY'
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "identifiers": [
    {
      "channels": {
        "email": {
          "status": "subscribed"
        }
      },
      "id": "[email protected]"
    }
  ],
  "customProperties": {
    "shoeSize": 42,
    "eyesColor": "blue",
    "maritalStatus": "single"
  },
  "city": "Los Angeles"
}
'