Retrieve a contact

Fetch one contact by its id — or by its email address.

GET /v1/contacts/{id}

Requires a Full access API key.

Path parameters

Parameter	Type	Required	Description
id	string	Yes	The contact id, or the contact's email address. Anything containing an @ is treated as an address.

Example

curl

# by id
curl "https://api.sendgrail.com/v1/contacts/$CONTACT_ID" \
  -H "Authorization: Bearer $SENDGRAIL_API_KEY"

# or by email address
curl "https://api.sendgrail.com/v1/contacts/ada@example.com" \
  -H "Authorization: Bearer $SENDGRAIL_API_KEY"

Node.js

const res = await fetch(
  `https://api.sendgrail.com/v1/contacts/${encodeURIComponent('ada@example.com')}`,
  { headers: { Authorization: `Bearer ${process.env.SENDGRAIL_API_KEY}` } },
);

const contact = await res.json();

Response

The contact object:

{
  "object": "contact",
  "id": "3f1c9a0e-6c5e-4a2b-9f2d-2b1a7c8e4d31",
  "email": "ada@example.com",
  "first_name": "Ada",
  "last_name": "Lovelace",
  "unsubscribed": false,
  "unsubscribed_at": null,
  "bounced_at": null,
  "source": "api",
  "properties": {
    "company_name": "Analytical Engines Ltd",
    "seats": 12
  },
  "created_at": "2026-07-14T19:44:32+00:00"
}

Id or email address, everywhere

Every contact endpoint — retrieve, update, delete, segments, topics — accepts either form in the path. The address is the thing your own system already knows; requiring you to look the id up first would be a round trip for nothing.

Addresses are matched lower-cased, the same way they're stored, so /v1/contacts/Ada@Example.com finds the same record. URL-encode the address if your HTTP client doesn't do it for you.

Not yours means not found

A contact belonging to another team answers 404, not 403 — an id that isn't yours is an id that doesn't exist, as far as your key is concerned.

{
  "message": "Contact not found.",
  "code": "not_found",
  "request_id": "8f2c1e64-1b17-4f8c-9f0e-3b6c1e0f5c31"
}

A Sending-access key on this endpoint is a 403: it's a valid key, it simply isn't allowed here. See API keys and Errors.