Contact API Read
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

Return a list of contacts

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

Get a list of full contact objects. This list can be filtered by a number of conditions see API Filtering. The result set can be returned sorted, limited to a total number of results and paged by skipping a number of records. Note that the limit is 100 records in a single request and defaults to a limit to 10. You can also change the result object to a Key-Value pair or specific fields only.

NOTE: All examples below are formatted for readability, actual GET requests require URI encoding. Each example below also includes a cURL request. Make sure to change the API_ID and API_KEY with your values.

Skipping contacts and limiting the result set

Get the second set of 10 contact from 11-20
https://e1.envoke.com/v1/contacts?skip=10&limit=10

curl -X GET -u API_ID:API_KEY "https://e1.envoke.com/v1/contacts?skip=10&limit=10"

Return all contacts

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

curl -X GET -u API_ID:API_KEY "https://e1.envoke.com/v1/contacts"


Find 5 contacts sorted by email address ascending

https://e1.envoke.com/v1/contacts?sort[email]=ASC&limit=5

curl -X GET -u API_ID:API_KEY "https://e1.envoke.com/v1/contacts?sort%5Bemail%5D=ASC&limit=5"

  

Find a contact by email address

https://e1.envoke.com/v1/contacts?filter[email]=jon@doe.com

curl -X GET -u API_ID:API_KEY "https://e1.envoke.com/v1/contacts?filter%5Bemail%5D=jon%40doe.com"

  

Find a contact by custom field (regular expressions)

Setup filter object:
{
filter: {
"custom_fields.barcode": {
$regex: "abc"
}
}
}

Serialize object for use in query string (using jQuery.param()):
jQuery.param({filter: {"custom_fields.barcode":{$regex: "abc"}}});
Result:
filter%5Bcustom_fields.barcode%5D%5B%24regex%5D=abc

https://e1.envoke.com/v1/contacts?filter[custom_fields.barcode][$regex]=abc

curl -X GET -u API_ID:API_KEY "https://e1.envoke.com/v1/contacts?filter%5Bcustom_fields.barcode%5D%5B%24regex%5D=abc"

Find a contact by custom field (exact match)

https://e1.envoke.com/v1/contacts?filter[custom_fields.barcode]=abc

curl -X GET -u API_ID:API_KEY "https://e1.envoke.com/v1/contacts?filter%5Bcustom_fields.barcode%5D=abc"

Find a contact by tag/interest name

Find contacts with an interest called "API test".

https://e1.envoke.com/v1/contacts?filter[interests]=API test

curl -X GET -u API_ID:API_KEY "https://e1.envoke.com/v1/contacts?filter%5Binterests%5D=API%20test"

Find a single contact with the id "1234"

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

curl -X GET -u API_ID:API_KEY "https://e1.envoke.com/v1/contacts/1234"

  

Find a contact by email and return only the first and last name in the result

https://e1.envoke.com/v1/contacts?filter[email]=jon@doe.com&fields=first_name,last_name

curl -X GET -u API_ID:API_KEY "https://e1.envoke.com/v1/contacts?filter%5Bemail%5D=jon%40doe.com&fields=first_name%2Clast_name"

RESPONSE:
[
{
"first_name": "Jon",
"last_name": "Doe"
},
...
]

Find a contact by email and return the contact id

https://e1.envoke.com/v1/contacts?email=jon@doe.com&fields=id&limit=1

curl -X GET -u API_ID:API_KEY "https://e1.envoke.com/v1/contacts?email=jon%40doe.com&fields=id&limit=1"

RESPONSE:
{"id":"517959"}


Or get a KVP with {ID: EMAIL}:

https://e1.envoke.com/v1/contacts?email=jon@doe.com&result_type=kvp

curl -X GET -u API_ID:API_KEY "https://e1.envoke.com/v1/contacts?email=jon%40doe.com&result_type=kvp"

RESPONSE:
{"517959":"jon@doe.com"}

Return the id and email address KVP for all contacts

https://e1.envoke.com/v1/contacts?result_type=kvp

curl -X GET -u API_ID:API_KEY "https://e1.envoke.com/v1/contacts?result_type=kvp"

RESPONSE:
{
"31": "jon@doe.com",
"32": "test@gmail.com",
"33": "name@email.com",
...
}

Did this answer your question?