coss.comdocs

Check a code

POST
/v1/verifications/check

Checks the code the end user typed, by the verification's id or by the destination (its latest verification). valid: true approves it (verification.approved, billed once); a wrong code spends an attempt, and the last one fails it. Checking an approved verification again with its code stays valid until it expires, without being billed again.

Authorization

bearerAuth
headerAuthorizationBearer <token>

A secret API key from the dashboard: coss_live_… for production environments, coss_test_… for sandbox environments.

Header Parameters

Idempotency-Key?string

Makes retries safe: a repeated check with the same key returns the same answer without spending another attempt. 1-256 characters.

Length1 <= length <= 256
Coss-Version?"2026-10-10"

The API version (a date) to use for this request. Defaults to your organization's version, pinned to the latest one when it first used the API and upgraded from the dashboard. The SDK always sends the version it was built for.

Value in"2026-10-10"

Request Body

application/json
  1. body
verification_id?string

The verification to check. Give this or to.

Lengthlength <= 64
to?string

The destination the code was sent to: checks its most recent verification. Give this or verification_id.

Length1 <= length <= 320
code*string

The code the end user entered.

Match^\d{4,10}$

Response Body

Whether the code is right, and the verification after the check.

application/json
  1. response
object*"verification_check"
Value in"verification_check"
valid*boolean

Whether the code is right. Only true proves the end user has the phone or mailbox; checking an approved verification again with its code stays true until it expires.

verification*
import { Coss } from "coss";const coss = new Coss({  apiKey: process.env.COSS_API_KEY,  baseUrl: "https://api.coss.com",});const { data, error } = await coss.verify.check({  to: "+14155550199",  code: "482913",});
{  "object": "verification_check",  "valid": true,  "verification": {    "object": "verification",    "id": "vrf_01k8e2m4q2f3e9v6t5r1n0p8yz",    "channel": "sms",    "to": "+14155550199",    "country": "US",    "status": "approved",    "failure": null,    "reasons": [],    "attempts": 0,    "max_attempts": 5,    "sends": [],    "tags": [],    "sandbox": false,    "expires_at": "2026-11-10T12:10:00.000Z",    "approved_at": "2026-11-10T12:00:41.000Z",    "created_at": "2026-11-10T12:00:00.000Z"  }}