Skip to main content
Contact API Update

Update a contact with the API

Marcel Ursprung avatar
Written by Marcel Ursprung
Updated over 7 months ago

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

Update a single contact using the contact's Envoke ID or email address as the key field. Read more about the difference between various contact IDs.

Endpoint: /contacts/
HTTP method: PATCH
URL: https://e1.envoke.com/v1/contacts/{CONTACT_ID}

Replace {CONTACT_ID} with the contact's Envoke id and include the contact update object JSON in the PATCH data.

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

Update a contact with the id "1234"

https://e1.envoke.com/v1/contacts/1234

{
"province" : "MB",
"city" : "Winnipeg"
}
curl -X PATCH -u API_ID:API_KEY -d "{\"province\":\"MB\",\"city\":\"Winnipeg\"}" "https://e1.envoke.com/v1/contacts/1234"

Update a contact using email address

Alternatively you can update a contact by providing the email address in the PATCH JSON data. For this, just use the /v1/contacts route, the contact ID is not required.

https://e1.envoke.com/v1/contacts

{
   "email" : "example@api.com",
"first_name" : "UPDATED"
}
curl -X PATCH -u API_ID:API_KEY -d "{\"email\":\"example@api.com\",\"first_name\":\"UPDATED\"}" "https://e1.envoke.com/v1/contacts"

Using a different key field

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

  • id (default)

  • email (default if id is missing)

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

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

Deleting / clearing field values

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

https://e1.envoke.com/v1/contacts?write_empty_values=1

{
"email" : "example@api.com",
"first_name" : ""
}
curl -X PATCH -u API_ID:API_KEY -d "{\"email\":\"example@api.com\",\"first_name\":\"\"}" "https://e1.envoke.com/v1/contacts?write_empty_values=1"

Did this answer your question?