Skip to contentSkip to navigationSkip to topbar
Twilio SendGrid Docs
On this page

Search Contacts

Operation overview

operation-overview page anchor

POST/v3/marketing/contacts/search

Base url: https://api.sendgrid.com (The Twilio SendGrid v3 API)

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.

Operation details

operation-details page anchor

Authentication

authentication page anchor

Headers

headers page anchor
Property nameTypeRequiredDescription
authorizationstring
required
Default: Bearer <<YOUR_API_KEY_HERE>>

Request body

request-body page anchor
Encoding type:application/json
SchemaExample
Property nameTypeRequiredDescriptionChild properties
querystring
required

An SGQL search string or other pattern.

Responses

responses page anchor
200400401403404408500
Schema
Property nameTypeRequiredDescriptionChild properties
resultarray[contact-details3]

Optional

MetadataselfMetadata

Optional

contactCountnumber

Optional

The total number of contacts matched.

Search ContactsLink to code sample: Search Contacts
1
const client = require("@sendgrid/client");

2
client.setApiKey(process.env.SENDGRID_API_KEY);

3


4
const data = {

5
  query:

6
    "email LIKE 'ENTER_COMPLETE_OR_PARTIAL_EMAIL_ADDRESS_HERE%' AND CONTAINS(list_ids, 'YOUR_LIST_IDs')",

7
};

8


9
const request = {

10
  url: `/v3/marketing/contacts/search`,

11
  method: "POST",

12
  body: data,

13
};

14


15
client

16
  .request(request)

17
  .then(([response, body]) => {

18
    console.log(response.statusCode);

19
    console.log(response.body);

20
  })

21
  .catch((error) => {

22
    console.error(error);

23
  });