> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ugatext.com/llms.txt
> Use this file to discover all available pages before exploring further.

# OTP verification

> Verify phone numbers with one-time passcodes using the UgaText Verify API.

The Verify API sends a one-time code to a phone number and checks the code your user enters.

**1. Start a verification**

```bash theme={null}
curl -X POST https://ugatext.com/api/v1/verify/start \
  -H "Client-ID: YOUR_CLIENT_ID" \
  -H "Client-Secret: YOUR_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+256700000000",
    "external_reference": "user_reg_9841"
  }'
```

| Field | Required | Description |
| - | - | - |
| `phone_number` | Yes | Number to verify, in Uganda (+256), Kenya (+254), or DR Congo (+243). Use a [sandbox number](https://docs.ugatext.com/sandbox.md) for free testing. |
| `service_id` | No | Verify Service ID. Defaults to your account's default phone verification service. |
| `external_reference` | No | Your own reference, such as a user ID. |

Save the returned `verification_id`.

**2. Check the code**

```bash theme={null}
curl -X POST https://ugatext.com/api/v1/verify/check \
  -H "Client-ID: YOUR_CLIENT_ID" \
  -H "Client-Secret: YOUR_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "verification_id": "vfy_1760425200000_a1b2c3d4",
    "code": "482910"
  }'
```

## Verify errors

| Status | Code | Meaning |
| - | - | - |
| 400 | `MISSING_REQUIRED_FIELDS` | A required field is missing. |
| 400 | `INVALID_CODE` | The code is wrong. |
| 404 | `VERIFICATION_NOT_FOUND` | Unknown `verification_id`. |
| 410 | `CODE_EXPIRED` | The code has expired. |
| 410 | `SESSION_ALREADY_VERIFIED` | The session was already verified. |
| 429 | `COOLDOWN_ACTIVE` | Wait before starting another verification. |
| 429 | `MAX_ATTEMPTS_EXCEEDED` | Too many incorrect attempts. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.