# Get Contacts by Identifiers ## Operation overview ```json {"path":"https://api.sendgrid.com/v3/marketing/contacts/search/identifiers/{identifier_type}","method":"post","servers":[{"url":"https://api.sendgrid.com","description":"The Twilio SendGrid v3 API"}]} ``` Use this endpoint to retrieve up to 100 contacts that match the requested identifier values for a single identifier type. `identifier_type` must be a valid identifier type: `email`, `phone_number_id`, `external_id`, or `anonymous_id`. Use this endpoint instead of the [Search Contacts endpoint](/docs/sendgrid/api-reference/contacts/search-contacts) when you can provide exact identifiers and do not need to include other [Segmentation Query Language (SGQL)](/docs/sendgrid/for-developers/sending-email/segmentation-query-language/) filters when searching. This endpoint returns a `200` status code when any contacts match the identifiers you supplied. When searching multiple identifier values 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 identifier values that are not found. This endpoint returns a `404` status code when no contacts are found for the provided identifiers. This endpoint returns a `400` status code if any searched addresses are invalid. Twilio SendGrid recommends exporting your contacts regularly as a backup to avoid issues or lost data. ## Operation details ### Authentication API Key ### Headers ```json [{"in":"header","name":"Authorization","required":true,"default":"Bearer <>","schema":{"type":"string"}}] ``` ### Path parameters ```json [{"name":"identifier_type","in":"path","required":true,"description":"The type of identifier to search for. You can use only one type of identifier per search.","schema":{"type":"string","enum":["email","phone_number_id","external_id","anonymous_id"],"refName":"IdentifierType1","modelName":"IdentifierType1"}}] ``` ### Request body ```json {"schema":{"type":"object","description":"","required":["identifiers"],"example":{"identifiers":["contact@example.com"]},"properties":{"identifiers":{"type":"array","description":"One or more more identifier values of the given identifier type to search for in your Marketing Campaigns contacts.","items":{"type":"string"}}}},"encodingType":"application/json"} ``` ### Responses ```json [{"responseCode":"200","schema":{"description":"","content":{"application/json":{"schema":{"type":"object","description":"An object containing the contacts that match the searched identifier values.","example":{"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":""}}}}},"properties":{"result":{"type":"object","additionalProperties":{"type":"object","description":"An identifiers value matching a searched identifier in your contacts. For example, if you use the email identifier type, the email address will be returned.","properties":{"contact":{"title":"contact-details3","type":"object","required":["id","list_ids","segment_ids","created_at","updated_at"],"refName":"ContactDetails3","modelName":"ContactDetails3","properties":{"id":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"unique_name":{"type":"string"},"email":{"type":"string"},"phone_number_id":{"type":"string"},"external_id":{"type":"string"},"anonymous_id":{"type":"string"},"alternate_emails":{"type":"array","items":{"type":"string"}},"address_line_1":{"type":"string"},"address_line_2":{"type":"string"},"city":{"type":"string"},"state_province_region":{"type":"string"},"country":{"type":"string"},"postal_code":{"type":"string"},"phone_number":{"type":"string"},"whatsapp":{"type":"string"},"line":{"type":"string"},"facebook":{"type":"string"},"list_ids":{"type":"array","items":{"type":"string"}},"segment_ids":{"type":"array","items":{"type":"string"}},"custom_fields":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"_metadata":{"title":"selfMetadata","type":"object","refName":"SelfMetadata","modelName":"SelfMetadata","properties":{"self":{"type":"string","description":"A link to this object."}}}}},"error":{"type":"string"}}}}}}}}}},{"responseCode":"400","schema":{"description":"","content":{"application/json":{"schema":{"title":"error","type":"object","example":{"field":"field_name","message":"error message"},"required":["message"],"refName":"ContactsError","modelName":"ContactsError","properties":{"message":{"type":"string"},"field":{"type":"string"},"error_id":{"type":"string"},"parameter":{"type":"string"}}}}}}},{"responseCode":"401","schema":{"description":"","content":{"application/json":{"schema":{"type":"object","example":{"errors":[{"field":"field_name","message":"error message"}]},"refName":"ErrorResponse","modelName":"ErrorResponse","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string","description":"An error message."},"field":{"description":"When applicable, this property value will be the field that generated the error.","nullable":true,"type":"string"},"help":{"type":"object","description":"When applicable, this property value will be helper text or a link to documentation to help you troubleshoot the error."}}}},"id":{"type":"string","description":"When applicable, this property value will be an error ID."}}}}},"refName":"#/components/responses/MarketingContacts401","modelName":"__components_responses_MarketingContacts401"}},{"responseCode":"403","schema":{"description":"","content":{"application/json":{"schema":{"type":"object","example":{"errors":[{"field":"field_name","message":"error message"}]},"refName":"ErrorResponse","modelName":"ErrorResponse","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string","description":"An error message."},"field":{"description":"When applicable, this property value will be the field that generated the error.","nullable":true,"type":"string"},"help":{"type":"object","description":"When applicable, this property value will be helper text or a link to documentation to help you troubleshoot the error."}}}},"id":{"type":"string","description":"When applicable, this property value will be an error ID."}}}}},"refName":"#/components/responses/MarketingContacts403","modelName":"__components_responses_MarketingContacts403"}},{"responseCode":"404","schema":{"description":"","content":{"application/json":{"schema":{"title":"error","type":"object","example":{"field":"field_name","message":"error message"},"required":["message"],"refName":"ContactsError","modelName":"ContactsError","properties":{"message":{"type":"string"},"field":{"type":"string"},"error_id":{"type":"string"},"parameter":{"type":"string"}}}}}}},{"responseCode":"500","schema":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string"}}}}}}}}}}] ``` Get Contacts by Identifiers ```js const client = require("@sendgrid/client"); client.setApiKey(process.env.SENDGRID_API_KEY); const identifier_type = "email"; const data = { identifiers: ["contact@example.com"], }; const request = { url: `/v3/marketing/contacts/search/identifiers/${identifier_type}`, method: "POST", body: data, }; client .request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) .catch((error) => { console.error(error); }); ``` ```python import os from sendgrid import SendGridAPIClient sg = SendGridAPIClient(os.environ.get("SENDGRID_API_KEY")) identifier_type = "email" data = {"identifiers": ["contact@example.com"]} response = sg.client.marketing.contacts.search.identifiers._( identifier_type ).post(request_body=data) print(response.status_code) print(response.body) print(response.headers) ``` ```csharp using System; using System.Collections.Generic; using System.Threading.Tasks; using SendGrid; public class Program { public static async Task Main() { string apiKey = Environment.GetEnvironmentVariable("SENDGRID_API_KEY"); var client = new SendGridClient(apiKey); var identifierType = "email"; var data = @"{ ""identifiers"": [ ""contact@example.com"" ] }"; var response = await client.RequestAsync( method: SendGridClient.Method.POST, urlPath: $"marketing/contacts/search/identifiers/{identifierType}", requestBody: data); Console.WriteLine(response.StatusCode); Console.WriteLine(response.Body.ReadAsStringAsync().Result); Console.WriteLine(response.Headers.ToString()); } } ``` ```java import com.sendgrid.*; import java.io.IOException; import org.json.JSONObject; import java.util.HashMap; import java.util.Arrays; public class Example { public static void main(String[] args) throws IOException { try { SendGrid sg = new SendGrid(System.getenv("SENDGRID_API_KEY")); Request request = new Request(); request.setMethod(Method.POST); request.setEndpoint("/marketing/contacts/search/identifiers/email"); request.setBody(new JSONObject(new HashMap() { { put("identifiers", Arrays.asList("contact@example.com")); } }).toString()); Response response = sg.api(request); System.out.println(response.getStatusCode()); System.out.println(response.getBody()); System.out.println(response.getHeaders()); } catch (IOException ex) { throw ex; } } } ``` ```go package main import ( "fmt" "github.com/sendgrid/sendgrid-go" "os" ) func main() { apiKey := os.Getenv("SENDGRID_API_KEY") host := "https://api.sendgrid.com" request := sendgrid.GetRequest(apiKey, "/v3/marketing/contacts/search/identifiers/email", host) request.Method = "POST" request.Body = []byte(`{ "identifiers": [ "contact@example.com" ] }`) response, err := sendgrid.API(request) if err != nil { fmt.Println(err.Error()) os.Exit(1) } else { fmt.Println(response.StatusCode) fmt.Println(response.Body) fmt.Println(response.Headers) } } ``` ```php /sendgrid-php.php'; $apiKey = getenv("SENDGRID_API_KEY"); $sg = new \SendGrid($apiKey); $request_body = json_decode('{ "identifiers": [ "contact@example.com" ] }'); $identifier_type = "email"; try { $response = $sg->client ->marketing() ->contacts() ->search() ->identifiers() ->_($identifier_type) ->post($request_body); print $response->statusCode() . "\n"; print_r($response->headers()); print $response->body() . "\n"; } catch (Exception $ex) { echo "Caught exception: " . $ex->getMessage(); } ``` ```ruby require 'sendgrid-ruby' include SendGrid sg = SendGrid::API.new(api_key: ENV['SENDGRID_API_KEY']) data = JSON.parse('{ "identifiers": [ "contact@example.com" ] }') identifier_type = "email" response = sg.client.marketing.contacts.search.identifiers._(identifier_type).post(request_body: data) puts response.status_code puts response.headers puts response.body ``` ```bash curl -X POST "https://api.sendgrid.com/v3/marketing/contacts/search/identifiers/email" \ --header "Authorization: Bearer $SENDGRID_API_KEY" \ --header "Content-Type: application/json" \ --data '{"identifiers": ["contact@example.com"]}' ```