Verify
Prove someone has a phone number or a mailbox with a one-time code: how a verification goes, how it's priced and what's included.
coss.verify sends a one-time code to a phone number (SMS) or an email address and checks the
code the person typed. coss.com makes the code, sends it, keeps only a keyed hash of it, counts
the attempts and expires it; your backend makes two calls.
Sandbox keys and email codes work right away. Live SMS codes need a
sender: while coss.com's shared numbers roll out, set one of
your registered numbers in Verify's settings, or the call fails with
503 shared_sender_unavailable.
// 1. The user typed their number: send them a code.
const { : } = await ..({ : "+14155550123", : });
// 2. They typed the code they got: check it.
const { : } = await ..({ : "+14155550123", : "482913" });
if (?.) {
// The number is theirs.
}Only valid: true proves the person has the phone or mailbox. Check on your backend, never in the
browser, and treat the API key as you would any secret.
How a verification goes
- Start it with
to: a number in E.164 form (+14155550123) gets an SMS, an email address an email (or passchannel). Pass the end user'sip, and youruser_idif you have one: the fraud guard uses them. - It is checked before anything is sent. A verification the fraud guard blocks is stored as
blockedwith itsreasons, the call fails withverification_blocked, and nothing is sent or billed. - The code goes out — 6 digits by default — and the verification is
pendinguntil it expires (10 minutes by default). - Check the code. By
to(the destination's latest verification) or byverification_id. The right code makes itapproved(verification.approved); a wrong one spends an attempt, and the fifth wrong one fails it (verification.failed). Checking an approved verification again with its code stays valid until it expires, without being billed again.
Starting again for the same destination while a verification is pending sends a new code
(the earlier one stops working, and the expiry restarts), up to 5 times; cancel one with
coss.verify.cancel(id). Code length, lifetime, attempts, senders and the countries SMS codes
may go to are the environment's Verify settings, in the dashboard or through
coss.verify.settings.update():
const { : } = await ...({
: "Acme",
: "+14155550100",
: ["CA", "GB", "US"],
});sms_from must be one of your organization's numbers, and a live key's email_from must be on one
of its verified domains; restricted keys need the verify:update permission.
Pricing
You pay per approved verification, plus the channel: an SMS from your own number is billed as
any SMS, one from coss.com's shared numbers at the SMS price of its country (verify.sms), and
email costs nothing extra. Verifications that are blocked, fail or expire cost only the messages
actually sent. See pricing.
What's in it
Your own number or coss.com's shared numbers, countries and opt-outs.
Your own sender or coss.com's, and what the email says.
How SMS pumping is stopped before you pay for it, and every reason it gives.
Sandbox codes are always zeros.
Tools
- CLI:
coss verifystart,check,list,get,cancelandsettings. - MCP server: coding agents get
start_verification,check_verification,list_verifications,get_verification,cancel_verification,get_verify_settingsandupdate_verify_settings. - Other languages: the API reference shows every operation in Python, Go, Ruby, PHP, Java and .NET.
Last updated
On This Page