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

IdentifierDescription
emailEmail
phonePhone 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).

ChannelIdentifierDescription
emailemailEmail channel
smsphoneSms channel

Channel statuses

StatusDescription
subscribedChannel is subscribed
unsubscribedChannel has unsubscribed
nonSubscribedChannel'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

ParameterTypeDescription
identifiersarrayContact's identifiers (supported types: email, phone)
idstringIdentifier's id
typestringIdentifier type
sourcestringIdentifier source
sendWelcomeMessageboolean (default: false)Send welcome message (will be sent only if welcome workflow is turned on) or not.
channelsobjectIdentifier's channels (supported channels: email, sms)
statusstringChannel status (available statuses: subscribed, unsubscribed, nonSubscribed)
statusDatestringStatus update date, ISO 8601 format. Example: 2017-05-30T15:14:22Z
contactIDstringContacts identifier in our system.
createdAtstring (format: date-time)Contacts creation date, ISO 8601 format. (example: 2017-05-30T14:11:12Z)
firstNamestringFirst name
lastNamestringLast name
tagsArray of stringContact 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"
countrystringCountry name
countryCodestring(2)ISO Country code (2 characters). You can find all country codes in Guides part.
statestringState
citystringCity
addressstringStreet, house number, apartment
postalCodestringContact's postal or zip code.
genderstring(1; m/f)Contact's gender. Can be: m - male, f - female
birthdatestring (format": date)Birthdate. Example: 1981-11-05
customPropertiesobjectYou 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
  • List and object types are not supported
  • Floats are rounded to 6 digits precision.
TypeDescription
numberSupported floats, ints. Example: 1; 1.23
booleanValues: true/false
stringMax length: 2048 characters
dateDate 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

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": ""
    }
}

Custom property height will be removed.