Building blocks
Review and tuning
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.
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: []
// }canonicalfolds the provider's aliasing (dots and+tagsat Gmail and similar): two addresses with the same canonical form reach one inbox.deliverabilitycomes from DNS (MX, A and AAAA records):undeliverablewhen the domain doesn't exist, has a null MX or has no record to deliver to;unknownwhen the lookup failed or took longer than 800 ms.domain_age_dayscomes 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_kindiscloud(a provider's published ranges: AWS, Google Cloud, Oracle, DigitalOcean…),hosting(a hosting network) orvpn(a network mostly used by commercial VPN and proxy services).asn,as_nameandcountrycome from IPinfo Lite. Network and country data by IPinfo.privacysays 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;nullwhere 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 isvalid: falseand isn't looked up.validsays whether the number exists in its country's numbering plan. line_typeismobile,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,pagerorunknown.carrieris the network the number is on now, so a number ported to another carrier shows its new one. It isnullfor toll-free, premium and personal numbers.sim_swapsays when a mobile number's SIM last changed, and whether that wasrecent(withinperiod, an ISO 8601 duration such asPT48H). 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 isnullwhere 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 (validthen 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,
checkPhonereturns a402,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,
checkPhonereturns a429(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