Contact API Fields
Marcel Ursprung avatar
Written by Marcel Ursprung
Updated over a week ago

Visit api.envoke.com to test APIs and get examples in 20+ languages

Visit api.envoke.com to test APIs and get examples in 20+ programming languages

Related API operations:

These fields can be updated with the contact API

id

Type: Integer
Length: 4 bytes (max: 4294967295)
The Envoke contact ID.

Required for all delete, or update calls. Not required for contact insert.


email

Required

Type: String
Length: 60 characters
Required when creating a new contact.


consent_status

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

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.


consent_description

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

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.

Note: The consent_effective_date can't be updated for the current consent record. Only a new consent record can be created with a consent_effective_date in combination with a consent_status field.


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.


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.


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


phone

Type: String
Length: 25


address_1

Type: String
Length: 100
Primary address line.


address_2

Type: String
Length: 100
Secondary address line.


city

Type: String
Length: 20


country

Type: String
Length: 50

This field 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


postal_code

Type: String
Length: 15


website

Type: String
Length: 255


language

Type: String
Length: 2 characters

The following subset of the 2 character ISO language codes is supported:

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


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


Tags / interests

Note: Tags are called interests in the API.

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"
]


subscriptions

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

Note: If no consent status is provided (see consent section above) for a contact then the consent will be “Not Provided” this means that the contact will not be able to receive emails from Envoke. Nurture campaigns will not be set on contacts without consent.

Type:  Object with nurture id key / value pairs, or , or object with nurture 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?