- List assessments GET
- Assess an event POST
- Retrieve an assessment GET
- Report an assessment's outcome POST
- List allow and block list entries GET
- Add an allow or block list entry POST
- Retrieve a list entry GET
- Remove a list entry DELETE
- Forget a user DELETE
- Retrieve the risk settings GET
- Update the risk settings PATCH
- Retrieve the calibration GET
- List rules GET
- Create a rule POST
- Retrieve a rule GET
- Update a rule PATCH
- Delete a rule DELETE
- Check an email address POST
- Check an IP address POST
- Check a phone number POST
- Classify content POST
- Check a rate limit POST
- List rate limit buckets GET
- Create a rate limit bucket POST
- Retrieve a rate limit bucket GET
- Update a rate limit bucket PATCH
- Delete a rate limit bucket DELETE
Check a phone number
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).
bearerAuthAuthorizationBearer <token>A secret API key from the dashboard: coss_live_… for production environments, coss_test_… for sandbox environments.
Coss-Version?"2026-10-10"The API version (a date) to use for this request. Defaults to your organization's version, pinned to the latest one when it first used the API and upgraded from the dashboard. The SDK always sends the version it was built for.
"2026-10-10"application/json- body
- body
- …
phone*stringThe number in E.164 (+14155550123); spaces, dashes, dots and brackets are ignored. Anything else is valid: false.
1 <= length <= 32What coss.com knows about the number.
application/json- response
- response
- …
object*"risk_phone_check""risk_phone_check"phone*stringThe number in E.164, or as given when it isn't.
valid*booleanA possible number in its country's numbering plan. When the lookup failed (degraded), only the E.164 syntax was checked.
country*|ISO 3166-1 alpha-2.
line_type*|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.
"mobile""landline""fixed_voip""non_fixed_voip""toll_free""premium""shared_cost""personal""uan""voicemail""pager""unknown"nullcarrier*|The network the number is on now (after any port). null when unknown, and for toll-free, premium and personal numbers.
sim_swap*|The mobile number's last SIM change. null where coss.com doesn't have that data (not every country and carrier).
degraded*array<>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.
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");{ "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": []}