# Verify (/docs/verify)

`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](/docs/verify/sms#which-number-sends-it): 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`.

```ts twoslash
import { Coss } from "coss";
const coss = new Coss();
declare const userIp: string;
// ---cut---
// 1. The user typed their number: send them a code.
const { data: verification } = await coss.verify.start({ to: "+14155550123", ip: userIp });

// 2. They typed the code they got: check it.
const { data: check } = await coss.verify.check({ to: "+14155550123", code: "482913" });
if (check?.valid) {
  // 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 [#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](/docs/verify/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()`:

```ts twoslash
import { Coss } from "coss";

const coss = new Coss({ apiKey: "coss_test_…" });
// ---cut---
const { data: settings } = await coss.verify.settings.update({
  app_name: "Acme",
  sms_from: "+14155550100",
  allowed_countries: ["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 [#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](/pricing).

## What's in it [#whats-in-it]

<Cards>
  <Card title="SMS codes" href="/https/coss.com/docs/verify/sms">
    Your own number or coss.com's shared numbers, countries and opt-outs.
  </Card>
  <Card title="Email codes" href="/https/coss.com/docs/verify/email">
    Your own sender or coss.com's, and what the email says.
  </Card>
  <Card title="Fraud guard" href="/https/coss.com/docs/verify/fraud-guard">
    How SMS pumping is stopped before you pay for it, and every reason it gives.
  </Card>
  <Card title="Testing" href="/https/coss.com/docs/verify/testing">
    Sandbox codes are always zeros.
  </Card>
</Cards>

## Tools [#tools]

- **CLI**: [`coss verify`](/docs/cli#verify) `start`, `check`, `list`, `get`, `cancel` and `settings`.
- **MCP server**: [coding agents](/docs/mcp#tools) get `start_verification`, `check_verification`, `list_verifications`,
  `get_verification`, `cancel_verification`, `get_verify_settings` and `update_verify_settings`.
- **Other languages**: the [API reference](/docs/api-reference) shows every operation in Python, Go, Ruby,
  PHP, Java and .NET.
