Check a one-time code

POST

/api/kyc/contact/verifications/:id/check

POST

/api/kyc/contact/verifications/:id/check

curl -X POST https://sandbox-api.toden.co/api/kyc/contact/verifications/id/check \
     -H "Authorization: Bearer <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "code": "000000"
}'

{
  "contactVerification": {
    "id": "cmt8s0a4p0003qw9k2m7f3cv1",
    "status": "verified",
    "channel": "phone",
    "destination": "+2348030000000",
    "attemptsUsed": 1,
    "expiresAt": "2026-09-12T10:05:00.000Z",
    "createdAt": "2026-09-12T10:00:00.000Z",
    "deliveryChannel": "test",
    "country": "NG",
    "signals": {
      "e164": "+2348030000000",
      "country": "NG",
      "callingCode": "234",
      "valid": true,
      "lineType": "mobile",
      "virtual": false
    },
    "externalUserId": "user_8f21",
    "chargedAmount": null,
    "verifiedAt": "2026-09-12T10:01:12.000Z"
  }
}

Checks the code the person typed. A correct code marks the challenge verified and returns the record. No proof token is returned, and a contact proved here cannot be carried into a verification submission.

Every call spends one attempt, including a repeat call on a challenge that is already verified. A wrong code answers 400 invalid_code with attemptsRemaining.

Billing. The check is charged once, when a code is first accepted, in production only. chargedAmount reports the cost. A repeat call does not charge again.

Error codes

`error`	Status	Meaning
`invalid_request`	400	The body failed validation.
`invalid_code`	400	The code is wrong. `attemptsRemaining` says how many tries are left.
`secret_key_required`	403	A publishable key was used. This endpoint accepts secret keys only.
`environment_mismatch`	403	The key belongs to an environment this deployment does not serve.
`ip_not_allowed`	403	The key has an IP allowlist and the calling address is not on it.
`organization_suspended`	403	The organisation is suspended. The response carries `reason` and `suspendedAt`.
`business_not_approved`	403	A live key was used before the business was approved for production.
`challenge_not_found`	404	No challenge with that id for this organisation and environment, or it was not created through this API.
`challenge_expired`	410	The five minute window has closed. Send a new code.
`too_many_attempts`	429	The attempt allowance is spent. Send a new code.

A missing or unknown key answers 401, where error is a short sentence rather than a code.

Requires a secret (sk_) key. A publishable key receives 403 secret_key_required.

Authentication

AuthorizationBearer

Send the API key as a Bearer token. Each operation states whether a publishable key is enough or a secret key is required.

Path parameters

idstringRequired

The contact verification id returned when the code was sent.

Request

This endpoint expects an object.

codestringRequired4-12 characters

The code the person typed.

Response

The code was accepted.

contactVerificationobject

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

410

Gone Error

429

Too Many Requests Error