---
title: "Verify a sign-up code"
method: POST
path: "/api/v1/auth/verify"
tags: ["authentication"]
---

# Verify a sign-up code

`POST /api/v1/auth/verify`

Verifies the one-time code for a `verificationId`. This endpoint has **two
possible outcomes**, and you must branch on the response body:

- **Signing in to an existing account** — the account and API key are
  returned immediately. **The API key is returned only once — store it
  immediately.**
- **Registering a new account** — the email is now verified, but an account
  is *not* created yet. The response carries a `registrationId` instead.
  Registering requires a verified phone number: continue with
  [Register a phone number](#operation/registerNumber), then
  [Verify a phone number](#operation/verifyNumber), which creates the
  account and returns the same shape as the sign-in outcome.

In short: **if the response contains `registrationId`, the flow is not
finished.** A new number's inbound voice-agent prompt is always the default
at creation; change it afterwards with
[Update a phone number](#operation/updateNumber).

## Request body

- object
  - `verificationId` string, required
  - `code` string, required — The 6-digit code from the email.

## Response `200`

Verified. Either the account (sign-in) or a `registrationId` (registration still needs a verified phone number).

- union
  - AuthenticatedAccount — A completed sign-in or registration. Returned by both [Verify a sign-up code](#operation/verifySignup) (when signing in) and [Verify a phone number](#operation/verifyNumber) (when registering).
    - `apiKey` string, nullable — Your API key. Shown once, when the account is created.
    - `accountId` string
    - `created` boolean — True when this call created the account.
    - `phoneNumber` string, nullable — The Dial number provisioned for the account, if any. This is not the phone number used to register.
    - `phoneNumberId` string, nullable
    - `message` string
  - PendingPhoneRegistration — The email is verified but no account exists yet, because registering requires a verified phone number. Continue with [Register a phone number](#operation/registerNumber).
    - `registrationId` string, required — Identifies this registration for the phone-verification calls.

## Other responses

- `400` — The request body failed validation.
- `401` — Missing or invalid API key.
- `429` — Too many attempts. Wait before retrying. During registration this also covers the cap on verification codes sent to a single phone number.

---

[API](https://skmtc.net/getdial/apis/rest-api.md) · [All operations](https://skmtc.net/getdial/apis/rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/getdial/rest-api/revisions/5f4eb30ac29a/schema)