Contact API Insert

Consent

Be sure to add a consent_status field otherwise you won't be able to send emails to contacts.

Response

After a successful contact insert the Envoke contact ID is returned. This ID can be used to update the contact later.

Contact fields

View available contact fields that you can insert / update with the API

All example below show the POST URL followed by the POST data. Each example below also includes a cURL request. Make sure to change the API_ID and API_KEY with your values.

Endpoint: /contacts
​HTTP method: POST
​URL: https://e1.envoke.com/v1/contacts

Supply the full contact object JSON in the POST data. Example:

Existing contacts

When doing an insert, the API will return an error with a response indicating a duplicate contact, if the contact you're attempting to insert already exists in the database. Duplicates are checked by the contact's email address. In this case you can update the contact record or use the upsert operation described below, which inserts a contact or updates it if it already exists.

If the 'upsert' query parameter is set the Contact Insert API will create a contact if the email doesn't exist (standard insert) or update an existing contact if a matching email, id or keyfield is found in the request body.

Upsert reduces the number of API calls required when the outcome is simply an updated contact in Envoke.

Note: When the upsert does an update instead of an insert, the contact object supplied in the call will not replace the entire contact in the database, instead it will update the specified fields or append any new Tags or Subscriptions.

Supply the contact object JSON in the POST data. Example:

The normal behaviour of the API is to not clear field values from the contact record.

This is so you don't accidentally remove good contact information.

NOTE: Fields can be updated with a non blank value, but blank values are ignored by default.

To disable this behaviour and clear field values (using empty strings ""), include the "write_empty_values" query parameter in your request.

Example: Clearing the first_name field

Set the 'keyfield' query parameter to 'remote_id' to be able to insert contacts with your own external database id using the remote_id field. The keyfield parameter can be set to one of the following options:

IMPORTANT: Using your own remote id as the keyfield will allow the creation of duplicate email addresses in the database with unique remote_id fields.

Note: Having duplicate emails in the database might lead to contacts receiving an email more than once.

IMPORTANT: Please contact Envoke support if you wish to use a remote_id as your keyfield so we can disable your account's email field duplicate check validation.

Supply the full contact object JSON in the POST data. Example: