> Every page of the Heythere docs is listed in https://heythere.io/docs/llms.txt: fetch it to find a page instead of guessing its URL.

# Verifications: send one-time codes on WhatsApp

> Prove that a customer holds a phone number by sending a one-time code on WhatsApp from your own number, then checking the code they type.

Before Camille books a repair on her repair shop's website, the site needs to know that the number she typed is hers. It asks Heythere to start a verification: Heythere sends a six-digit code to Camille on WhatsApp, from the shop's own number, and the site checks the code she types. The shop needs no other provider for its codes.

`startVerification` takes the sending number, Camille's number, a `purpose`, and the `language` of the message. The purpose says why she receives a code: `sign_in`, `sign_up`, or `action_confirmation`, such as confirming a payment. `checkVerificationCode` then answers `approved`, `incorrect` with the attempts left, `expired`, or `too_many_attempts`.

## What does Camille receive?

A WhatsApp message with her code and a button to copy it, sent through an authentication [message template](https://heythere.io/docs/concepts/message-templates) that Heythere creates on the shop's business account the first time it needs one. In Heythere, her [conversation](https://heythere.io/docs/concepts/conversations) with the shop shows a `verification_code` message with its purpose and its delivery, never the code: Heythere keeps only a fingerprint of it. When Camille never wrote to the shop, she becomes a [contact](https://heythere.io/docs/concepts/contacts) known by her phone number.

## How long does a code work?

A code works for 10 minutes and takes 5 attempts. Starting a new verification of the same number and purpose replaces the pending one, so only the newer code works. Heythere refuses a code sent too soon after another, or too many codes to one number, one workspace, or one country, which keeps someone from flooding Camille with codes.

## What does a code cost?

A delivered code counts in a [billed conversation](https://heythere.io/docs/concepts/usage#what-is-a-billed-conversation-) like any other message. A code WhatsApp never delivers is never billed.

## Where to look when a code does not arrive?

`getVerification` shows how far WhatsApp carried the code, and why it failed when it did, such as a number that is not on WhatsApp. When WhatsApp refuses the code outright, `startVerification` answers with that reason at once.

## In the API

Every operation is a REST endpoint and, unless marked REST only, an MCP tool of the same name. [The OpenAPI document](https://app.heythere.io/api/openapi.json) describes their parameters, payloads, and errors.


- `startVerification`: Send a one-time verification code on WhatsApp. `POST /api/organizations/{organizationId}/workspaces/{workspaceId}/verifications`
- `checkVerificationCode`: Check a verification code. `POST /api/organizations/{organizationId}/workspaces/{workspaceId}/verifications/{verificationId}/check`
- `getVerification`: Get a verification. `GET /api/organizations/{organizationId}/workspaces/{workspaceId}/verifications/{verificationId}`
