--- title: Known Contacts per Line | Sendblue Docs description: Check whether a contact is known or new on a specific Sendblue phone line --- Use the contact’s status to choose which number to send from. ``` GET https://api.sendblue.com/api/v2/lines/contact-status ``` The result uses the same rules as Sendblue’s new-contact limits. Adding a contact to your account does not make it known, and a contact known on one line can still be new on another. ## Query Parameters | Parameter | Type | Required | Description | | ----------------- | ------ | -------- | ------------------------------------------ | | `number` | string | Yes | Contact phone number (E.164 format). | | `sendblue_number` | string | Yes | Your Sendblue phone number (E.164 format). | Both values must be valid phone numbers, up to 64 characters each. Formatted phone numbers are converted to E.164. Email addresses, repeated values, and extra query parameters are not supported. The line must belong to your account. Old lines still available during a replacement grace period are also supported. ## Example Request Use your account’s API credentials. URL-encode the phone numbers to preserve the leading `+`: Terminal window ``` curl --get "https://api.sendblue.com/api/v2/lines/contact-status" \ --data-urlencode "number=+14155550200" \ --data-urlencode "sendblue_number=+14155550100" \ -H "sb-api-key-id: YOUR_API_KEY" \ -H "sb-api-secret-key: YOUR_API_SECRET" ``` You can also use a temporary bearer token. A line-scoped token can query only the lines it allows. ## Success Response (200) ``` { "status": "OK", "number": "+14155550200", "sendblue_number": "+14155550100", "classification": "known", "known_contact": true, "new_contact_lookback_days": 30, "sampled_at": "2026-10-06T19:00:00.000Z" } ``` ## Response Fields | Field | Type | Description | | --------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------ | | `status` | string | `OK` | | `number` | string | Contact phone number in E.164 format. | | `sendblue_number` | string | Sendblue phone number in E.164 format. | | `classification` | string | Contact status; see the table below. | | `known_contact` | boolean or null | `true` for known, `false` for new, or `null` when the status is unavailable or does not apply. | | `new_contact_lookback_days` | number or null | Days without activity before a contact counts as new again. `null` if this limit does not apply or the setting is unavailable. | | `sampled_at` | string | When the status was checked, as an ISO 8601 timestamp in UTC. | The example uses 30 days. Use the returned `new_contact_lookback_days` value rather than assuming this is the same for every account. ## Contact Status | Classification | `known_contact` | Description | | ---------------- | --------------- | --------------------------------------------------------------------------------------------------------------- | | `known` | `true` | Recent incoming or outgoing activity was found for this contact on this line and account. | | `new` | `false` | No activity was found within the returned number of days. | | `not_applicable` | `null` | These new-contact limits do not apply to the account, including inbound-only and free shared-line plans. | | `unavailable` | `null` | Sendblue could not check message history or the limit settings. Retry before using the result to choose a line. | `null` does not mean the contact is new. Check `classification` before using `known_contact`. ### What Counts as Activity Incoming messages count as activity. Outgoing messages count once Sendblue accepts them for sending; requests rejected before that point do not count. Only activity between this contact and this line on your account is included. After the returned number of days without activity, the contact becomes new again. Recent messages may take a short time to appear in the result. Known contacts do not count toward new-contact usage, but other sending rules and exemptions still apply. A daily limit of zero keeps the line paused, even for known contacts. ## Choosing a Sendblue Line 1. Get each line’s remaining capacity from [Line Usage and Capacity](/api-v2/line-usage/index.md). 2. Check the contact’s status on the line you want to use. 3. Reuse a line that knows the contact when possible. For a new contact, choose a line with capacity. Set `from_number` in your send request. 4. Check the send response. Other messages may have used the remaining capacity since your lookup. The lookup does not reserve capacity or choose a sender for you. `GET /api/v2/contacts` lists saved contacts; it does not report whether they are known on a line. ## Error Responses | HTTP Status | Description | | ----------- | ------------------------------------------------------------------------------------------------------------------ | | 400 | Missing, invalid, repeated, or unsupported query parameters. | | 401 | Invalid API credentials or temporary token. | | 403 | Missing authentication or a temporary token that does not allow the requested line. | | 404 | The line does not belong to your account, is no longer available during a replacement, or was deleted or archived. | | 429 | API request rate limit exceeded. | | 500 | Sendblue could not check whether the line belongs to your account. Retry the request. | If the line check succeeds but message history cannot be checked, the response is HTTP 200 with `classification: "unavailable"` and `known_contact: null`. Responses use `Cache-Control: no-store`. See the [API reference](/api/resources/lines/methods/get_contact_status/index.md) for the response schema.