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

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