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

Get Contacts by Identifiers



Operation overview

operation-overview page anchor

POST/v3/marketing/contacts/search/identifiers/{identifier_type}

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

This endpoint allows you to retrieve up to 100 contacts matching the searched identifier values for one type of specified identifier.

identifier_type must be a valid identifier type: email, phone_number_id, external_id, or anonymous_id.

This endpoint should be used in place of the Search Contacts endpoint when you can provide exact identifiers and do not need to include other Segmentation Query Language (SGQL) filters when searching.

This endpoint returns a 200 status code when any contacts match the identifiers you supplied. When searching multiple identifiers in a single request, it is possible that some will match a contact while others will not. When a partially successful search like this is made, the matching contacts are returned in an object and an error message is returned for the identifiers that are not found.

This endpoint returns a 404 status code when no contacts are found for the provided identifiers.

A 400 status code is returned if any searched addresses are invalid.

Twilio SendGrid recommends exporting your contacts regularly as a backup to avoid issues or lost data.


Authentication

authentication page anchor
Property nameTypeRequiredDescription
Authorizationstringrequired
Default: Bearer <<YOUR_API_KEY_HERE>>
Property nameTypeRequiredDescription
identifier_typeenum<string>required

The type of identifier to search for.

Possible values:
emailphone_number_idexternal_idanonymous_id
SchemaExample
Property nameTypeRequiredDescriptionChild properties
identifiersarray[object]required

One or more more identifier values to search for in your Marketing Campaigns contacts.

200400401403404500

An object containing one or more of the identifiers matching the searched identifiers in your contacts.

SchemaExample
Property nameTypeRequiredDescriptionChild properties
resultobject

Get Contacts by Identifiers

get-contacts-by-identifiers page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
curl

_29
const client = require('@sendgrid/client');
_29
client.setApiKey(process.env.SENDGRID_API_KEY);
_29
_29
const identifier_type = "email";
_29
const data = {
_29
"identifiers": [
_29
{
_29
"email": "contact@example.com"
_29
},
_29
{
_29
"phone_number_id": "23"
_29
}
_29
]
_29
};
_29
_29
const request = {
_29
url: `/v3/marketing/contacts/search/identifiers/${identifier_type}`,
_29
method: 'POST',
_29
body: data
_29
}
_29
_29
client.request(request)
_29
.then(([response, body]) => {
_29
console.log(response.statusCode);
_29
console.log(response.body);
_29
})
_29
.catch(error => {
_29
console.error(error);
_29
});


Rate this page: