Contacts

Intro

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

Contact identifiers

Each contact can be identified by multiple identifiers (example: phone, email). Currently, we support identifiers of types ‘email’ and ‘phone’.

Identifier	Description
email	Email
phone	Phone number

Identifier channel

To reach contact we use identifier channels. Each identifier can have multiple channels, i.e. identifier phone with chanels SMS or identifier email with channels email and Facebook Messenger. Each channel can have different statuses (for example contact can be subscribed for ‘email’ channel, but nonSubscribed for sms channel).

Channel	Identifier	Description
email	email	Email channel
sms	phone	Sms channel

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

System will return status with latest status update date.

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

Parameters

Parameter	Type	Description
identifiers	array	Contact's identifiers (supported types: email, phone)
id	string	Identifier's id
type	string	Identifier type
source	string	Identifier source
sendWelcomeEmail	boolean (default: false)	Send welcome email (will be sent only if welcome workflow is turned on) or not.
channels	object	Identifier's channels (supported channels: email, sms)
status	string	Channel status (available statuses: subscribed, unsubscribed, nonSubscribed)
statusDate	string	Status update date, ISO 8601 format. Example: 2017-05-30T15:14:22Z
contactID	string	Contacts identifier in our system.
createdAt	string (format: date-time)	Contacts creation date, ISO 8601 format. (example: 2017-05-30T14:11:12Z)
firstName	string	First name
lastName	string	Last name
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"
country	string	Country name
countryCode	string(2)	ISO Country code (2 characters). You can find all country codes in Guides part.
state	string	State
city	string	City
address	string	Street, house number, apartment
postalCode	string	Contact's postal or zip code.
gender	string(1; m/f)	Contact's gender. Can be: m - male, f - female
birthdate	string (format": date)	Birthdate. Example: 1981-11-05
customProperties	object	You can add your own custom properties. Supported types: number, string, boolean. Please read more above.

Custom properties

Custom properties - 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:

{
    "email": "[email protected]",
    "firstName": "Vanessa",
    "lastName": "Kensington",
    "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.