Contacts

Intro

Endpoint: https://api.omnisend.com/v5/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 contact we use identifier channels. Each identifier can have only one channel, i.e. identifier phone with channels SMS or identifier email with channels email. Each channel can have different statuses (for example contact can be subscribed for email channel, but nonSubscribed for sms channel).

The Email identifier is case-sensitive, meaning it treats uppercase and lowercase letters as distinct.

Note: Two contacts cannot share 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 without consent 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.

For example, if you'll post the status date earlier than in the system, status and status date won't be changed.

Custom properties

Custom properties - an array of any properties needed.

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

Name restrictions:

• Can contain only latin characters, numbers, "_" (underscore) sign
• Max name length - 128 symbols
• Name is case sensitive

Value restrictions:

• String max length - 2048 characters
• Floats are rounded to 6 digits precision.

Removing custom property

To remove custom property, pass customProperties array with needed to remove property name and it's value as "" or null.

Example:

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