# Check a phone number (/docs/api-reference/risk/check-risk-phone)

Phone intelligence on its own: whether the number exists in its country's numbering plan, its line type (mobile, landline, fixed or non-fixed VoIP, toll-free…) and carrier, and the last SIM swap where carriers share it. Stateless. A failed lookup is reported in `degraded`. Each live check that gets an answer is billed (`risk.phone_checks`; plans include some every month, and Free stops at its allowance); invalid numbers, failed lookups and sandbox checks are free. Limited per organization as well as per key. Sandbox keys see the fictional numbers `+1 202 555 01xx` (`0101` landline, `0102` non-fixed VoIP, `0103` fixed VoIP, `0104` a recent SIM swap, `0199` invalid, the rest mobile).

`POST https://api.coss.com/v1/risk/phone/check`

Authenticate with your API key as a bearer token (`Authorization: Bearer coss_test_…`). Responses are JSON with snake_case fields; errors are `{ error: { type, code, message, param?, issues?, request_id } }` (https://coss.com/docs/api-reference/errors.md).

## Request body

- `phone` (string, required, 1-32 characters): The number in E.164 (`+14155550123`); spaces, dashes, dots and brackets are ignored. Anything else is `valid: false`.

## Example request

TypeScript (the `coss` package):

```ts
import { Coss } from "coss";

const coss = new Coss({
  apiKey: process.env.COSS_API_KEY,
  baseUrl: "https://api.coss.com",
});

const { data, error } = await coss.risk.checkPhone("+14155550123");
```

HTTP:

```sh
curl -X POST "https://api.coss.com/v1/risk/phone/check" \
  -H "Authorization: Bearer $COSS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "phone": "+14155550123"
}'
```

## Response 200

What coss.com knows about the number.

- `object` ("risk_phone_check", required)
- `phone` (string, required): The number in E.164, or as given when it isn't.
- `valid` (boolean, required): A possible number in its country's numbering plan. When the lookup failed (`degraded`), only the E.164 syntax was checked.
- `country` (string | null, required): ISO 3166-1 alpha-2.
- `line_type` ("mobile" | "landline" | "fixed_voip" | "non_fixed_voip" | "toll_free" | "premium" | "shared_cost" | "personal" | "uan" | "voicemail" | "pager" | "unknown" | null, required): `fixed_voip` numbers belong to an address (cable, business lines); `non_fixed_voip` ones can be had online in minutes (Google Voice, app numbers), the kind used for throwaway accounts. `null` when it couldn't be looked up.
- `carrier` (object | null, required): The network the number is on now (after any port). `null` when unknown, and for toll-free, premium and personal numbers.
  - `name` (string | null, required)
  - `mobile_country_code` (string | null, required)
  - `mobile_network_code` (string | null, required): Only for mobile numbers.
- `sim_swap` (object | null, required): The mobile number's last SIM change. `null` where coss.com doesn't have that data (not every country and carrier).
  - `recent` (boolean, required): The SIM changed within `period`: someone may have taken the number over.
  - `swapped_at` (string | null, required): The last SIM change, where the carrier tells the date.
  - `period` (string | null, required): What `recent` means, as an ISO 8601 duration (`PT48H`).
- `degraded` (("phone_data" | "sim_swap")[], required): `phone_data` when the lookup failed or timed out (or had no line type for the number); `sim_swap` when the carrier didn't answer about the SIM.

Example:

```json
{
  "object": "risk_phone_check",
  "phone": "+14155550123",
  "valid": true,
  "country": "US",
  "line_type": "mobile",
  "carrier": {
    "name": "T-Mobile USA, Inc.",
    "mobile_country_code": "310",
    "mobile_network_code": "260"
  },
  "sim_swap": null,
  "degraded": []
}
```

## Errors

- `400`: The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).
- `401`: The API key is missing, invalid, revoked or expired (`authentication_error`).
- `402`: The plan's included phone checks are used up (`usage_limit_exceeded`), or live checks are paused by an overdue invoice or a spend limit (`billing_hold`).
- `403`: The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).
- `413`: The request body is larger than 5 MB (`payload_too_large`).
- `415`: The body is not sent as `application/json` (`unsupported_media_type`).
- `422`: The body failed validation (`validation_error`, see `issues`).
- `429`: Too many requests with this API key (`rate_limited`), too many phone checks for this organization (`phone_check_rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds.
- `500`: Unexpected server error (`api_error` / `internal_error`).
- `503`: Phone checks aren't available at the moment (`phone_lookup_unavailable`), or the API key could not be verified right now (`service_unavailable`). Retry later.