Email, IP and phone checks

Look up an email address, IP address or phone number on its own, without an assessment.

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

const {  } = await ..("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

const {  } = await ..("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.
  • 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

const {  } = await ..("+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 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.

Last updated