Contacts

Intro

Endpoint: https://api.omnisend.com/v3/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).

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.

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

Status	Description
subscribed	Channel is subscribed
unsubscribed	Channel has unsubscribed
nonSubscribed	Channel's status is unknown (contact hasn't subscribed or unsubscribed yet)

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.

Type	Description
number	Supported floats, ints. Example: 1; 1.23
boolean	Values: true/false
string	Max length: 2048 characters
date	Date should be passed as string. Preferable formats: Y-m-d, Y-m-d H:i, Y-m-d H:i:s or ISO 8601. Examples: 2018-08-08, 2018-08-08 14:23, 2018-08-08T14:23Z, 2018-08-08T14:23:11+02:00
list	List should contain array of strings. Examples: ["blue", "green"]

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": "Vanessa",
  "lastName": "Kensington",
  "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.