id:

Type: Integer
Length: 4 bytes (max: 4294967295)
The Envoke contact Id, this field is required for ALL delete, or update calls.

external_id

Type: String
Length: 32
The Envoke “external_id” field is a 32 character string. This field can be used to access the contact's unique "consent & subscription preferences" page hosted by Envoke.

remote_id:

Type: String
Length: 60 characters
An external database id useful when syncing contacts with a third party database such as a CRM.

email:

Type: String
Length: 60 characters
The contact's email address, this is generally unique per database.

Note: The email field is required when creating a contact.

first_name:

Type: String
Length: 20  characters
The contact's first name.

last_name:

Type: String
Length: 20
The contact's last name.

title:

Type: String
Length: 50
The contacts job title.

company:

Type: String
Length: 50
The contact's company name.

phone:

Type: String
Length: 25
The contact's phone number.

address_1:

Type: String
Length: 100
The contact's address line 1.
This is typically the street number and name.

address_2:

Type: String
Length: 100
The contact's address line 2.
This is typically the unit number if located at a multi-unit address such as an appartment building.

city:

Type: String
Length: 20
The contact's city name.

country:

Type: String
Length: 50
The contact's country name.
IMPORTANT NOTE: This field currently allows a full country name but we recommend using only 2 character ISO country codes. In a future release only valid ISO country codes or exact match country names will be allowed in this field. 

province:

Type: String
Length: 50
The contact's province name.

postal_code:

Type: String
Length: 15
The contact's postal or zip code.

website:

Type: String
Length: 255
The contact's website URL.

language:

Type: String
Length: 2 characters
The contact's language of choice.
Envoke supports the following subset of the 2 character ISO language codes for list segmentation purposes:

  • "en" = English
  • "fr" = French
  • "ar" = Arabic
  • "zh" = Chinese
  • "de" = German
  • "it"  =  Italian
  • "ja" =  Japanese
  • "ko" =  Korean
  • "pt" = Portuguese
  • "ru" = Russian
  • "es" = Spanish

Envoke supports the following language codes with full translations on the "consent & subscription preferences" page. 

  • "en" =  English
  • "fr" =  French

feedback:

Type: String
Length: 65,535 characters
The contact's comment / feedback field. 

consent_status:

Type: Enumerated List
The contact's consent status for sending emails.
List of valid consent values:

  • "Express": Explicit consent provided.
  • "Implied - Inquiry":  Consent expires 6 months after obtained. Applicable for Canadian contacts (for example: submitted a form). Auto-expiry is enabled for all accounts..
  • "Implied - Transaction": Consent expires 2 years after obtained. Applicable for Canadian contacts (for example: purchased tickets). Auto-expiry is enabled for all accounts..
  • "Implied": No Expiry: Applies to non-Canadian contacts or special cases (for example: alumni, mandatory emails to association members, etc.)
  • "Expired": Contacts whose implied status expired as per the rolling six month / two year expiry setting. Sending not allowed.
  • "Not provided": Contacts whose consent is unknown. Sending not allowed.
  • "Revoked": Consent revoked. Sending not allowed.
  • "External Spam Reported": Contacts reported spam via feedback loops. Sending not allowed.
  • "Envoke Spam Reported": Contacts reported spam on subscription management page. Sending not allowed.

Note: If no consent status is provided for a new contact then the consent will be “Not Provided” this means that the contact will not be able to receive emails from Envoke.

consent_description:

Type: String
Length: 65,535 characters
The contact's reason for consent / description.

Important Note: The consent description is required with all consent status updates that specify sending-allowed types (“Express” or “Implied”). If you try you will find that the API request submits ok without a “consent_description” but this is a current bug and will be patched.

consent_effective_date

Type: DateTime
Returned in RFC 3339 format in UTC time zone (e.g. 2017-10-27T18:19:57+00:00). This field should be supplied in the same format. If time zone is omitted UTC is assumed. This field can be filtered by $gt, $gte, $lt, $lte filter operators.

consent_expiry 

Type: Date
This is a date field, not datetime, returned in yyyy-mm-dd format. This field is ignored on updates.

Note: A blank consent expiry date value means there is no expiry.

custom_fields:

Type: Object with custom field name key / value pairs

Any custom fields associated with the contact's record.
The key is the custom field name as shown in the UI. The value is the custom field value for the contact. All values are expressed as String type fields including dates fields.

Example

"custom_fields": {
   "custom_field_name1": "Field Value 1"
}

interests:

Type:  Object with interest id key / value pairs, or object with interest name key / value pairs.

The key is either the interest id or the interest name as shown in the UI. The value is one of the following enumerated list values: "Set", "Unset"

When the interest is "Set" it will be added to the contact. 

When "Unset" it will be removed from the contact.

Object format examples

"interests": {
   "International": "Set",
   "Consumer": "Unset"
}
"interests": {
   "1235": "Set",
   "4377": "Unset"
}


OR

Type: Array of interest names.
The name is the interest "name" as shown in the UI, not the "display name". Each interest name in the Array will be "Set" meaning the interest is added to the contact. No interests will be unset

Array format example

"interests": [
   "International", "Consumer"
]

subscription interests:

Subscriptions are updated using the interest object (see above). All the same examples apply to subscriptions, except use the subscription ids or subscription names.

Object format example using the interest object to set and unset subscriptions.

"interests": {
   "Newsletter Subscription": "Set",
   "Specials": "Unset"
}
"interests": {
   "2345": "Set",
   "4557": "Unset"
}

autoresponders:

Type:  Object with nurture id key / value pairs, or , or object with nurutre name key / value pairs.
The key is either the nurture id or nurture name as shown in the UI. The value is one of the following enumerated list values: "Set", "Unset" and "Dequeue"

When the nurture sequence is "Set" it will be added to the contact and sequence messages will be queued for delivery. 

When "Unset" the nurture sequence will be removed from the contact record, and any pending unsent messages cancelled.

When set to "Dequeue" any messages scheduled to be sent to the contact will not be sent but the contact will still have the nurture sequence on their contact record.

Unset vs. Dequeue

We recommend using "Dequeue" to stop the sending of autoresponder messages, as "Unset" will remove the autoresponder record from the contact entirely.

Object format examples

"autoresponders": {
   "Marketing Sequence 1": "Dequeue",
   "Whitepaper Download": "Set"
}
"autoresponders": {
   "45756": "Dequeue",
   "32646": "Set"
}


OR

Type: Array of autoresponder / nurture names.
The name is the nurture "name" as shown in the UI. Each nurture name in the Array will be "Set" meaning the nurture sequence is added to the contact and the sequence messages will be queued for delivery. No nurture sequences will be unset.

Array format example

"autoresponders": [
   "Marketing Sequence 1", "Whitepaper Download"
]

 

Envoke Contact Object

{
   "id": "1234",
   "external_id": "1234",
   "remote_id": "",
   "first_name": "John",
   "last_name": "Johnson",
   "title": "Leading Leader",
   "email": "new-contact@api-testing.com",
   "company": "Envoke",
   "phone": "555-1234",
   "address_1": "555 Brant Street",
   "address_2": "",
   "city": "Toronto",
   "country": "CA",
   "province": "ON",
   "postal_code": "L1V 3X5",
   "website": "",
   "language": "en",
   "feedback": "",
   "consent_status": "Express",
   "consent_description": "Express consent given on website homepage form.",
   "consent_effective_date": "2017-10-27T18:19:57+00:00",
   "consent_expiry": "",
   "custom_fields": {
      "custom_field_name1": "Field Value 1"
   },
   "interests": [
      "Business Products",
      "International",
      "Consumer"
   ],
   "autoresponders": [
      "Marketing Sequence 1",
      "Whitepaper Download"
   ]
}
Did this answer your question?