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

  1. Start it with to: a number in E.164 form (+14155550123) gets an SMS, an email address an email (or pass channel). Pass the end user's ip, and your user_id if you have one: the fraud guard uses them.
  2. It is checked before anything is sent. A verification the fraud guard blocks is stored as blocked with its reasons, the call fails with verification_blocked, and nothing is sent or billed.
  3. The code goes out — 6 digits by default — and the verification is pending until it expires (10 minutes by default).
  4. Check the code. By to (the destination's latest verification) or by verification_id. The right code makes it approved (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

Tools

  • CLI: coss verify start, check, list, get, cancel and settings.
  • MCP server: coding agents get start_verification, check_verification, list_verifications, get_verification, cancel_verification, get_verify_settings and update_verify_settings.
  • Other languages: the API reference shows every operation in Python, Go, Ruby, PHP, Java and .NET.

Last updated