Contacts

Intro

Endpoint: https://api.omnisend.com/api/contacts

Guide: How to sync contacts

Contact identifiers and their Channels

Each contact can be identified by multiple identifiers (for example: phone, email).

To reach a contact, we use identifier channels. Each identifier can have only one channel, i.e., phone identifier uses the SMS channel and email identifier uses the email channel. Each channel can have different statuses (for example, a contact can be subscribed to the email channel but nonSubscribed to the sms channel).

Note: Two contacts cannot share the same identifier. If you try to create or update 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.

Email/SMS Consent Properties

Our API handles consent information for email and SMS communication. This includes details such as the source of consent, the date and time when consent was provided, the user's IP address, and the user agent.

Note: A contact can have a subscribed status even if consent has not been provided. However, consent is required in most countries for legal compliance.

Properties:

• source (string): Indicates the source or method through which the user provided consent for email/SMS communication. This could be a website form, mobile app interface, or any other platform where the consent was obtained.

• createdAt (string): Specifies the date and time when the user granted consent for email/SMS communication. The timestamp follows the ISO 8601 format for date and time.

• ip (string): Represents the IP address from which the consent was provided. This helps in tracking the origin of the consent request.

• userAgent (string): Contains information about the user agent, which typically includes details about the user's device, operating system, and browser. This aids in understanding the context of the consent request.

Example:

{
  "source": "Website Form",
  "createdAt": "2023-10-03T14:30:00Z",
  "ip": "192.168.1.100",
  "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/94.0.4606.71 Safari/537.36"
}

In this example, the user provided consent via a website form on October 3, 2023, at 14:30 UTC, originating from the IP address 192.168.1.100 using the specified user agent (Chrome browser on Windows 10). Understanding and utilizing these properties help in managing and respecting user consent effectively.

Channel statuses

Channel status date

The system will return the status with the latest status update date.

If you submit a status date earlier than the one already stored, the status and its date will not be updated.

Filter Restrictions

The GET /contacts endpoint enforces these combination rules:

• tag and status cannot be used in the same request
• updatedAtFrom cannot be combined with email, phone, status, segmentID, or tag

Note: When filtering by an email address containing +, URL-encode it as %2B to avoid it being interpreted as a space.

Custom properties

Custom properties - an object (key-value pairs) where keys are property names and values are the property values.

To create or update custom properties, just pass customProperties object with their names and values.

Name restrictions

• Can contain only Latin characters, numbers, and _ (underscores)
• Max name length - 128 symbols
• Name is case sensitive

Value restrictions

• String max length - 2048 characters
• Floats are rounded to 6 decimal places.

Removing custom property

To remove custom property, pass customProperties object with the property name as key and its value as "" or null.

Example:

curl --request POST \
     --url https://api.omnisend.com/api/contacts \
     --header 'Authorization: Omnisend-API-Key YOUR_API_KEY' \
     --header 'Omnisend-Version: 2026-03-15' \
     --header 'Content-Type: application/json' \
     --data '{
  "firstName": "John",
  "lastName": "Doe",
  "identifiers": [
    {
      "type": "email",
      "channels": {
        "email": {
          "status": "subscribed"
        }
      },
      "id": "[email protected]"
    }
  ],
  "customProperties": {
    "age": 33,
    "hair_color": "brown",
    "married": true,
    "marriageDate": "2018-07-07",
    "loyaltyPoints": 125.8,
    "height": "",
    "favoriteColors": ["blue", "green"]
  }
}'

Custom property height will be removed.

Example: Create a contact

curl --request POST \
     --url https://api.omnisend.com/api/contacts \
     --header 'Authorization: Omnisend-API-Key YOUR_API_KEY' \
     --header 'Omnisend-Version: 2026-03-15' \
     --header 'Content-Type: application/json' \
     --data '{
  "firstName": "Jane",
  "lastName": "Doe",
  "countryCode": "US",
  "tags": ["vip"],
  "identifiers": [
    {
      "type": "email",
      "id": "[email protected]",
      "channels": {
        "email": {
          "status": "subscribed",
          "statusChangedAt": "2024-01-01T00:00:00Z"
        }
      },
      "consent": {
        "source": "omnisend-form",
        "ip": "192.168.1.1",
        "createdAt": "2024-01-01T00:00:00Z"
      }
    }
  ]
}'

Example: Update a contact

curl --request PATCH \
     --url https://api.omnisend.com/api/contacts/CONTACT_ID \
     --header 'Authorization: Omnisend-API-Key YOUR_API_KEY' \
     --header 'Omnisend-Version: 2026-03-15' \
     --header 'Content-Type: application/json' \
     --data '{
  "firstName": "Jane",
  "tags": ["vip", "returning-customer"]
}'

See Also

• Errors & responses
• Pagination