Look up contacts and tags by phone batch

POST/api/v2/contacts/lookup

Send 1–100 phone numbers, bounded before normalization and deduplication. Contacts follow normalized input order; tags=[] means an existing untagged contact, while not_found lists normalized phones with no matching contact. A failed tag read fails the request. Company scope comes from authentication. Shares the cursor-page budget of 20 requests per 10 seconds per account.

Body ParametersJSONExpand Collapse

phone_numbers: array of string

ReturnsExpand Collapse

contacts: array of object { contact_id, phone, tags }

contact_id: string

phone: string

tags: array of string

not_found: array of string

status: "OK"

Look up contacts and tags by phone batch

curl https://api.sendblue.co/api/v2/contacts/lookup \
    -H 'Content-Type: application/json' \
    -H "sb-api-key-id: $SENDBLUE_API_API_KEY" \
    -H "sb-api-secret-key: $SENDBLUE_API_API_SECRET" \
    -d '{
          "phone_numbers": [
            "x"
          ]
        }'

{
  "contacts": [
    {
      "contact_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "phone": "phone",
      "tags": [
        "string"
      ]
    }
  ],
  "not_found": [
    "string"
  ],
  "status": "OK"
}

Returns Examples

{
  "contacts": [
    {
      "contact_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "phone": "phone",
      "tags": [
        "string"
      ]
    }
  ],
  "not_found": [
    "string"
  ],
  "status": "OK"
}