Look up a contact by an address they hold

POST

/api/v3/contacts/lookup

curl --request POST \
  --url https://api.tryletterhead.com/api/v3/contacts/lookup \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "api": true, "medium": "sms", "address": "+15555550100" }'

• Production

Resolves a company-level contact from an address they hold on another notification medium — currently SMS phone numbers only. Deliberately a POST rather than a GET /contacts/{address}-style lookup: a phone number in a URL would land in access logs, proxy logs, and browser history.

The address is normalized the same way it was when the contact registered it, so you can send whatever format you hold — no need to pre-format it yourself.

This is a company-level (v3) read. Authenticate with a company API key as a Bearer token.

Authorizations

• bearerAuth

Request Body ^required

Media type application/json

object

api

Required. Set to true to authenticate with an API key.

boolean

medium

required

The notification medium the address belongs to. Currently only sms is supported.

string

Allowed values: sms

address

required

The address to search for, in whatever format you hold it.

string

Example

{
  "api": true,
  "medium": "sms",
  "address": "+15555550100"
}

Responses

200

200 OK. Returns the matching contact — same shape as GET /api/v3/contacts/{email}.

Media type application/json

object

items

The matching contact. Full field list under GET /api/v3/contacts/{email}.

object

message

string

total

integer

Example

{
  "items": {
    "email": "[email protected]",
    "firstName": "Avery",
    "lastName": "Chen"
  },
  "message": "Contact retrieved.",
  "total": 1
}