Skip to content Skip to navigation Skip to topbar

Search Contacts

Operation overview

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.

Operation details

Authentication

API Key

Headers

Property nameTypeRequiredDescription

Authorizationstringrequired

Default: Bearer <<YOUR_API_KEY_HERE>>

Request body

SchemaExample

Property nameTypeRequiredDescriptionChild properties

querystringrequired

An SGQL search string or other pattern.

Responses

200400401403404408500

Schema

Property nameTypeRequiredDescriptionChild properties

resultarray[object]

Show child properties for result

_metadataobject

Show child properties for _metadata

contact_countnumber

The total number of contacts matched.

Search Contacts

Node.js

Python

Java

PHP

Ruby

curl


_21const client = require('@sendgrid/client');
_21client.setApiKey(process.env.SENDGRID_API_KEY);
_21
_21const data = {
_21  "query": "email LIKE 'ENTER_COMPLETE_OR_PARTIAL_EMAIL_ADDRESS_HERE%' AND CONTAINS(list_ids, 'YOUR_LIST_IDs')"
_21};
_21
_21const request = {
_21  url: `/v3/marketing/contacts/search`,
_21  method: 'POST',
_21  body: data
_21}
_21
_21client.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  });