Skip to main content
All CollectionsAPIContact update APIs
Contact API Fields
Contact API Fields
Marcel Ursprung avatar
Written by Marcel Ursprung
Updated over 3 months 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.

consent_force_downgrade

Type: Boolean

Default: False
When set to true, this field will allow the consent status to be downgraded from a higher status to a lower status. Downgrading is by default disabled to not accidentally overwrite a better consent status.

This is not a standard field that is returned with the contact object. This is an optional field that's not required unless a consent downgrade is required.

With this field set to true:

  • Express consent can be downgraded to implied consent.

  • A recent implied consent can be downgraded to an older implied consent.

  • Any sendable consent can be downgraded to "Not provided".

Note: This will allow a downgrade of all consent types except the Spam reported types.

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

Mandatory consent

Similar to subscriptions, mandatory consent is updated using the interest object (see above). All the same examples apply, except use the name "Mandatory consent".

If you wish to use the ID method, submit a support request asking us for your mandatory consent ID.

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

"interests": {
   "Mandatory consent": "Set"
}
"interests": {
   "83293": "Set",
}

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": "",
   "consent_force_downgrade": false,
   "custom_fields": {
      "custom_field_name1": "Field Value 1"
   },
   "interests": [
      "Business Products",
      "International",
      "Consumer"
   ],
   "autoresponders": [
      "Marketing Sequence 1",
      "Whitepaper Download"
   ]
}
Did this answer your question?