Check whether a contact is known on a line

GET/api/v2/lines/contact-status

Check whether a contact is known or new on one of your Sendblue lines. The result uses the same message history and inactivity window as new-contact limits. Incoming messages and outgoing messages accepted for sending count as activity; rejected requests do not. A saved contact is not required, and activity on another line or account does not count.

The lookup does not reserve capacity. Other sending rules still apply. Line-scoped temporary tokens can query only the lines they allow. Only number and sendblue_number query parameters are accepted.

Query ParametersExpand Collapse

number: string

Contact phone number (E.164 format). Formatted phone numbers are converted to E.164; email addresses are not supported.

maxLength64

sendblue_number: string

Your Sendblue phone number (E.164 format). Old lines still available during a replacement grace period are also supported.

maxLength64

ReturnsExpand Collapse

LineContactStatusResponse object { classification, known_contact, new_contact_lookback_days, 4 more }

classification: "known" or "new" or "not_applicable" or "unavailable"

Known or new contact status. Returns not_applicable if these limits do not apply, or unavailable if Sendblue could not check the status.

One of the following:

"known"

"new"

"not_applicable"

"unavailable"

known_contact: boolean

True for known, false for new, and null for not_applicable or unavailable. Other sending rules still apply.

new_contact_lookback_days: number

Days without activity before a contact counts as new again. Null if this limit does not apply or the setting is unavailable.

minimum0

exclusiveMinimum

number: string

Contact phone number in E.164 format.

sampled_at: string

When the contact status was checked in ISO 8601 UTC.

formatdate-time

sendblue_number: string

Sendblue phone number in E.164 format.

status: "OK"

Check whether a contact is known on a line

curl https://api.sendblue.co/api/v2/lines/contact-status \
    -H "sb-api-key-id: $SENDBLUE_API_API_KEY" \
    -H "sb-api-secret-key: $SENDBLUE_API_API_SECRET"

{
  "classification": "known",
  "known_contact": true,
  "new_contact_lookback_days": 30,
  "number": "+14155550200",
  "sampled_at": "2026-10-06T19:00:00.000Z",
  "sendblue_number": "+14155550100",
  "status": "OK"
}

Returns Examples

{
  "classification": "known",
  "known_contact": true,
  "new_contact_lookback_days": 30,
  "number": "+14155550200",
  "sampled_at": "2026-10-06T19:00:00.000Z",
  "sendblue_number": "+14155550100",
  "status": "OK"
}