Contacts
Get Contacts by Identifiers
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
- API Key
Headers
Request Body
One or more more identifier values to search for in your Marketing Campaigns contacts.
{
"identifiers": [
"test",
"23"
]
}
Path Parameters
Responses
An object containing one or more of the identifiers matching the searched identifiers in your contacts.
An identifiers value matching a searched identifier in your contacts.
A link to this object.
{
"result": {
"jane_doe@example.com": {
"contact": {
"address_line_1": "",
"address_line_2": "",
"alternate_emails": [
"janedoe@example1.com"
],
"city": "",
"country": "",
"email": "jane_doe@example.com",
"phone_number_id": "+14152279968",
"external_id": "extid_1709597080488434000_1_1",
"anonymous_id": "anonid_1709597080488436000_1_1",
"first_name": "Jane",
"id": "asdf-Jkl-zxCvBNm",
"last_name": "Doe",
"list_ids": [],
"segment_ids": [],
"postal_code": "",
"state_province_region": "",
"phone_number": "",
"whatsapp": "",
"line": "",
"facebook": "",
"unique_name": "",
"custom_fields": {},
"created_at": "2021-03-02T15:25:47Z",
"updated_at": "2021-03-30T15:26:16Z",
"_metadata": {
"self": "<metadata_url>"
}
}
}
}
}
the error message
the field that generated the error
helper text or docs for troubleshooting
{
"errors": [
{
"field": "field_name",
"message": "error message"
}
]
}
the error message
the field that generated the error
helper text or docs for troubleshooting
{
"errors": [
{
"field": "field_name",
"message": "error message"
}
]
}
the error message
the field that generated the error
helper text or docs for troubleshooting
{
"errors": [
{
"field": "field_name",
"message": "error message"
}
]
}
the error message
the field that generated the error
helper text or docs for troubleshooting
{
"errors": [
{
"field": "field_name",
"message": "error message"
}
]
}
Need some help?
We all do sometimes. Get help now from the Twilio SendGrid Support Team.
Running into a coding hurdle? Lean on the wisdom of the crowd by browsing the SendGrid tag on Stack Overflow or visiting Twilio's Stack Overflow Collective.