Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

Search Contacts



API Overview

api-overview page anchor

POST/v3/marketing/contacts/search

Base url: https://api.sendgrid.com

Use this endpoint to locate contacts.

The request body's query field accepts valid SGQL for searching for a contact.

Because contact emails are stored in lower case, using SGQL to search by email address requires the provided email address to be in lower case. The SGQL lower() function can be used for this.

Only the first 50 contacts that meet the search criteria will be returned.

If the query takes longer than 20 seconds, a 408 Request Timeout status will be returned.

Formatting the created_at and updated_at values as Unix timestamps is deprecated. Instead, they are returned as ISO format as string.


Authentication

authentication page anchor
Authorizationstringrequired
Default: Bearer <<YOUR_API_KEY_HERE>>
SchemaExample
querystringrequired

An SGQL search string or other pattern.

200400401403404408500
Schema
resultarray[object]

_metadataobject

contact_countnumber

The total number of contacts matched.

Search Contacts

search-contacts page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
curl

_21
const client = require('@sendgrid/client');
_21
client.setApiKey(process.env.SENDGRID_API_KEY);
_21
_21
const data = {
_21
"query": "email LIKE 'ENTER_COMPLETE_OR_PARTIAL_EMAIL_ADDRESS_HERE%' AND CONTAINS(list_ids, 'YOUR_LIST_IDs')"
_21
};
_21
_21
const request = {
_21
url: `/v3/marketing/contacts/search`,
_21
method: 'POST',
_21
body: data
_21
}
_21
_21
client.request(request)
_21
.then(([response, body]) => {
_21
console.log(response.statusCode);
_21
console.log(response.body);
_21
})
_21
.catch(error => {
_21
console.error(error);
_21
});


Rate this page: