Contacts

🚧
The v4 API is deprecated
The v4 (Contact Tracking) API is deprecated and will be sunset on June 15, 2027. Please follow the migration guide to move to the Contacts API in the latest stable Omnisend API version.

Intro

Contact identifiers

Each contact can be identified by its id, email or phoneNumber properties.

Properties

Contact can contain two types of properties:

System properties
Custom properties

System properties

System properties are:

Property	Type	Description
id	string	Contacts identifier in our system
email	string	Email
phoneNumber	string	Phone number
firstName	string	First name
lastName	string	Last name
gender	string	Contact's gender. Can be: m - male, f - female
birthdate	string	Birthdate. Example: 1981-11-05
address	string	Street, house number, apartment
country	string	Country name
countryCode	string	ISO Country code (2 characters)
city	string	City
state	string	State
postalCode	string	Contact's postal or zip code
tags	Array of string	Contact tags. Tags are labels you create to organize and manage your audience. When creating a new contact we strongly advice to add source tag, i.e. "source: shopify"
consents	Array of Consent	Contact consents. Consent is contact's permission to manage their data. Consent is usually (but not always, depends on country) given during opt in action.
optIns	Array of OptIn	Contact opt ins. Opt in is contact's subscription to email or SMS communication.
optOuts	Array of OptOut	Contact opt outs. Opt out is contact's unsubscription to email or SMS communication.

Removing and modifying system properties:

System properties cannot be removed at the moment, only modified.

To modify a system property set its new value.

Properties which cannot be modified:

identifier properties: id, email and phoneNumber
tags, consents, optIns and optOuts

Custom properties

Custom properties can be specified in customProperties object.

Maximum 200 properties could be specified for one contact.

Name restrictions:

Property names can contain only latin characters, numbers, "_" (underscore) sign
Max name length - 128 symbols
Names are case-sensitive

Value restrictions:

String max length - 2048 characters
Objects are not supported
Floats are rounded to 6 digits precision

Supported types

Type	Description	Examples
bool	Boolean	`true`, `false`
number	Integer or float	`1`, `1.23`
string	String	`lorem ipsum`
date	String, `YYYY-MM-DD` format	`2021-09-01`
dateTime	String, ISO 8601 format	`2021-09-01T12:41:52Z`, `2021-09-01T12:41:52+03:00`
string array	Multiple strings	`["elem1", "elem2"]`

Removing and modifying custom properties:

To remove a custom property set its value to "". Omitting a custom property or setting its value to null won't remove the property.

To modify a custom property set its new value.

Example

The following is an example contact JSON structure:

{
    "email": "[email protected]",
    "firstName": "Vanessa",
    "lastName": "Kensington",
    "customProperties" {
        "age": 33,
        "hair_color": "brown",
        "married": true,
        "marriageDate":"2018-07-07",
        "loyaltyPoints": 125.8,
        "hobbies": ["traveling", "reading"]
    }
}