# Email, IP and phone checks (/docs/risk/lookups)

The signals behind assessments are also available alone, for when you want a fact rather than a
decision: checking an address or a number as someone types it, or enriching your own records. Checks are
stateless: coss.com stores and counts nothing about the address or number, so they never say one was
seen before (assessments do, through velocity and duplicates). Request logs keep neither the input
nor the answer.

## Email [#email]

```ts twoslash
import { Coss } from "coss";
const coss = new Coss();
// ---cut---
const { data } = await coss.risk.checkEmail("ada@gnail.com");
// {
//   valid: true, domain: "gnail.com", canonical: "ada@gnail.com",
//   disposable: false, deliverability: "deliverable",
//   role_account: false, free_provider: false,
//   suggestion: "gmail.com", domain_age_days: 7300, degraded: []
// }
```

- `canonical` folds the provider's aliasing (dots and `+tags` at Gmail and similar): two addresses
  with the same canonical form reach one inbox.
- `deliverability` comes from DNS (MX, A and AAAA records): `undeliverable` when the domain doesn't
  exist, has a null MX or has no record to deliver to; `unknown` when the lookup failed or took
  longer than 800 ms.
- `domain_age_days` comes from the domain's registry (RDAP), only for organizations' own domains
  (not free providers or disposable domains). coss.com sends the registry only the domain.
- Lookups that failed are listed in `degraded` (`email_dns`, `domain_age`).

## IP [#ip]

```ts twoslash
import { Coss } from "coss";
const coss = new Coss();
// ---cut---
const { data } = await coss.risk.checkIp("185.220.101.1");
// {
//   ip: "185.220.101.1", version: 4, private: false, tor: true,
//   hosting: false, hosting_provider: null, hosting_kind: null,
//   asn: 60729, as_name: "…", country: "DE", privacy: null, degraded: []
// }
```

- `hosting_kind` is `cloud` (a provider's published ranges: AWS, Google Cloud, Oracle,
  DigitalOcean…), `hosting` (a hosting network) or `vpn` (a network mostly used by commercial VPN and
  proxy services).
- `asn`, `as_name` and `country` come from IPinfo Lite. Network and country data by
  [IPinfo](https://ipinfo.io).
- `privacy` says whether the address itself is a VPN exit, a proxy (residential proxies included) or
  a privacy relay (iCloud Private Relay…), and which service, from coss.com's IP privacy data provider;
  `null` where coss.com doesn't have that data, and for private addresses. Without it, `hosting_kind:
  "vpn"` is only a guess from the network.
- `degraded: ["ip_data"]` means some IP data is unavailable at the moment; `ip_privacy`, that the
  privacy data provider failed or took longer than 500 ms.

## Phone [#phone]

```ts twoslash
import { Coss } from "coss";
const coss = new Coss();
// ---cut---
const { data } = await coss.risk.checkPhone("+1 415 555 0123");
// {
//   phone: "+14155550123", valid: true, country: "US",
//   line_type: "non_fixed_voip",
//   carrier: { name: "…", mobile_country_code: "…", mobile_network_code: "…" },
//   sim_swap: null, degraded: []
// }
```

- Numbers are E.164 (`+` and the country code); spaces, dashes, dots and brackets are ignored.
  Anything else is `valid: false` and isn't looked up. `valid` says whether the number exists in its
  country's numbering plan.
- `line_type` is `mobile`, `landline`, `fixed_voip` (VoIP tied to an address: cable and business
  lines), `non_fixed_voip` (numbers anyone can get online in minutes, such as Google Voice and app
  numbers: the usual kind for throwaway accounts), `toll_free`, `premium`, `shared_cost`, `personal`,
  `uan`, `voicemail`, `pager` or `unknown`.
- `carrier` is the network the number is on now, so a number ported to another carrier shows its new
  one. It is `null` for toll-free, premium and personal numbers.
- `sim_swap` says when a mobile number's SIM last changed, and whether that was `recent` (within
  `period`, an ISO 8601 duration such as `PT48H`). A SIM changed just before a login or a password
  reset is how phone numbers get taken over. Carriers share this only in some countries, so it is
  `null` where coss.com doesn't have it.
- Phone data comes from Twilio, which coss.com sends only the number. `degraded: ["phone_data"]`
  means the lookup failed or took longer than 2 seconds (`valid` then only checks the syntax);
  `sim_swap`, that the carrier didn't answer about the SIM.
- Live phone checks cost $0.01 per check, and every plan includes
  100 risk phone checks a month (the Free plan stops there: beyond it, `checkPhone`
  returns a `402`, `usage_limit_exceeded`). Only checks that got an answer
  count; numbers that aren't E.164, failed lookups and sandbox checks are free. See
  [billing](/docs/billing) for the rates.
- They are also limited per organization: 5 per second (bursts of 10) and 1,000 per day. Over that,
  `checkPhone` returns a `429` (`phone_check_rate_limited`). Sandbox checks don't count.

All checks count against the same per-key limit as assessments (100 per second, bursts of 200), and
sandbox keys see the [test inputs](/docs/risk/testing).
