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