Visit api.envoke.com to test APIs and get examples in 20+ languages
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
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:
https://e1.envoke.com/v1/contacts
{
"email" : "new-contact@api-testing.com",
"first_name" : "John"
}
curl -X POST -u API_ID:API_KEY -d "{\"email\":\"new-contact@api-testing.com\",\"first_name\":\"John\"}" "https://e1.envoke.com/v1/contacts"
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.
Upsert contacts (insert or update if 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:
https://e1.envoke.com/v1/contacts?upsert=1
{
"email" : "new-contact@api-testing.com",
"first_name" : "John"
}
curl -X POST -u API_ID:API_KEY -d "{\"email\":\"new-contact@api-testing.com\",\"first_name\":\"John\"}" "https://e1.envoke.com/v1/contacts?upsert=1"
Using a different key 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:
email (default)
remote_id
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:
https://e1.envoke.com/v1/contacts?keyfield=remote_id
{
"remote_id" : "436D-SF92-J4G5",
"email" : "new-contact@api-testing.com",
"first_name" : "John"
}
curl -X POST -u API_ID:API_KEY -d "{\"remote_id\":\"436D-SF92-J4G5\", \"email\":\"new-contact@api-testing.com\",\"first_name\":\"John\"}" "https://e1.envoke.com/v1/contacts?keyfield=remote_id"