Search Contacts
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.
Property nameTypeRequiredDescription
Authorizationstring
required
Default:
Bearer <<YOUR_API_KEY_HERE>>
Encoding type:
application/json
SchemaExample
Property nameTypeRequiredDescriptionChild properties
querystring
required
An SGQL search string or other pattern.
200400401403404408500
Schema
Property nameTypeRequiredDescriptionChild properties
resultarray[contact-details3]
Optional
Show result properties
_metadataselfMetadata
Optional
Show _metadata properties
contact_countnumber
Optional
The total number of contacts matched.
1const client = require("@sendgrid/client");2client.setApiKey(process.env.SENDGRID_API_KEY);34const data = {5query:6"email LIKE 'ENTER_COMPLETE_OR_PARTIAL_EMAIL_ADDRESS_HERE%' AND CONTAINS(list_ids, 'YOUR_LIST_IDs')",7};89const request = {10url: `/v3/marketing/contacts/search`,11method: "POST",12body: data,13};1415client16.request(request)17.then(([response, body]) => {18console.log(response.statusCode);19console.log(response.body);20})21.catch((error) => {22console.error(error);23});