# API reference

> Every endpoint, field and answer of the OTP.ps REST API.

Base address: `https://otp.ps`. All requests need an [API key](/docs/authentication). Bodies are JSON (form-encoded bodies are accepted too); answers are JSON. The machine-readable version of this page is the **[OpenAPI 3.1 document](/openapi.json)**, built from the same code as the API.

## Send a code

`POST /api/v1/verify/send`

| Field | Type | | Description |
|---|---|---|---|
| `phone` | string | required | A Jawwal (059) or Ooredoo (056) mobile, written any common way. See [Phone numbers](/docs/phone-numbers). |
| `locale` | `"ar"` \| `"en"` | optional | Language of the message. Defaults to your account setting (Arabic for new accounts). |
| `purpose` | string | optional | One of `verify`, `login`, `signup`, `order`, `appointment`. Only changes the wording. Default `verify`. |

| Header | | Description |
|---|---|---|
| `Idempotency-Key` | optional | Up to 100 letters, digits or `- _ : .`. Retrying with the same key and request within 24 hours returns the first answer (with the header `Idempotent-Replayed: true`) instead of sending and charging again. The same key with a different request answers `409 idempotency_conflict`. Refusals that created nothing (validation, limits, balance) are not remembered, so they can be retried with the same key. |

**Answer `201`:** the [verification](#the-verification-object), plus `test_code` with a test key.

The message wording, by `purpose` (Arabic / English), after your business's name:

| `purpose` | Arabic | English |
|---|---|---|
| `verify` | رمز التحقق 4821، صالح 5 دقائق، لا تشاركه. | Your verification code is 4821. Valid for 5 min. Don't share it. |
| `login` | رمز الدخول … | Your login code is … |
| `signup` | رمز تفعيل حسابك … | Your sign-up code is … |
| `order` | رمز تأكيد طلبك … | Your order confirmation code is … |
| `appointment` | رمز تأكيد موعدك … | Your appointment confirmation code is … |

## Check a code

`POST /api/v1/verify/check`

| Field | Type | | Description |
|---|---|---|---|
| `id` | string | one of `id` / `phone` | The verification id from the send answer. Preferred. |
| `phone` | string | one of `id` / `phone` | Checks the latest code sent to this number with this key's mode. |
| `code` | string | required | What the customer typed. Spaces and Arabic-Indic digits are fine. |

**Answer `200`:** the verification plus:

| Field | Type | Description |
|---|---|---|
| `valid` | boolean | `true` only on the check that approved the code. **Rely on this.** |
| `attempts_left` | integer | Checks left for this code (0 once it is no longer pending). |

A wrong code is still a `200` answer, with `valid: false`.

## Get a verification

`GET /api/v1/verify/{id}`: **answer `200`:** the verification, or `404 not_found`.

## Get the balance

`GET /api/v1/balance`: **answer `200`:**

```json
{ "credits": 1250, "status": "active", "mode": "live" }
```

`credits` is the number of text messages left; `status` is `pending` (waiting for approval), `active` or `suspended`; `mode` is the key's mode.

## Get usage

`GET /api/v1/usage` (scope `read`): codes sent, approved and failed, and messages charged, for the key's mode, in Palestine time.

```json
{
  "mode": "live",
  "timezone": "Asia/Hebron",
  "today": { "date": "2026-11-19", "sent": 42, "approved": 37, "failed": 0, "segments": 42 },
  "month": { "month": "2026-11", "sent": 812, "approved": 701, "failed": 3, "segments": 812 },
  "days": [{ "date": "2026-11-19", "sent": 42, "approved": 37, "failed": 0, "segments": 42 }]
}
```

`days` has the last 30 days with any codes, newest first.

## Get limits

`GET /api/v1/limits` (scope `read`): the key's permissions, the code settings, the rate limits, and the spending limits with what has been used today and this month.

```json
{
  "mode": "live",
  "scopes": ["send", "check", "read"],
  "credits": 1250,
  "status": "active",
  "code": { "length": 4, "valid_minutes": 5, "max_attempts": 5 },
  "rate_limits": { "per_phone": [{ "seconds": 30, "max": 1 }, { "seconds": 3600, "max": 5 }, { "seconds": 86400, "max": 10 }], "per_account_per_minute": 120 },
  "spending": {
    "daily": { "limit": 300, "owner_cap": 500, "effective": 300, "used": 42 },
    "monthly": { "limit": null, "used": 812 },
    "key_daily": { "limit": null, "used": 40 },
    "resets": { "day_in_seconds": 36000, "month_in_seconds": 986400 }
  }
}
```

A `null` limit means there is none of that kind. See [spending limits](/docs/security#spending-limits).

## Verification links and webhooks

| | Scope | |
|---|---|---|
| `POST /api/v1/verify/links` | send | Create a [verification link](/docs/verification-links) (`url` only in this answer) |
| `GET /api/v1/verify/links` | read | List, newest first: `status`, `reference`, `limit` (1–100), `before` (a link id) |
| `GET /api/v1/verify/links/{id}` | read | One link |
| `POST /api/v1/verify/links/{id}/cancel` | send | Cancel a pending link (`409 invalid_state` otherwise) |
| `POST /api/v1/webhooks`, `GET /api/v1/webhooks`, `DELETE /api/v1/webhooks/{id}` | read | [Webhook](/docs/webhooks) addresses |

## The verification object

| Field | Type | Description |
|---|---|---|
| `id` | string | `ver_…` |
| `status` | string | `pending`, `approved`, `expired`, `failed` or `canceled`. See [lifecycle](/docs/verification-lifecycle). |
| `to` | string | The number, partly hidden: `0599 ••• 456`. |
| `network` | string | `jawwal` or `ooredoo`. |
| `purpose`, `locale` | string | As sent. |
| `segments` | integer | Text messages charged (0 with a test key, and when the message couldn't be sent). |
| `attempts` | integer | Checks made so far. |
| `test` | boolean | Made with a test key. |
| `created_at`, `expires_at` | string | ISO 8601, UTC. |
| `verified_at` | string \| null | When it was approved. |

## Errors

Errors answer an HTTP status of 400 or more with:

```json
{ "error": "rate_limited", "message": "Too many codes for this phone number. Try again later.", "retry_after": 27 }
```

The full list is on [Errors](/docs/errors).

## Limits

per number: one code every 30 seconds, 5 an hour and 10 a day; per account: 120 codes a minute (test and live keys are counted separately). `5` checks per code.

## Billing

A live send takes one credit per text message part: 70 characters in Arabic, 160 in English. The standard wording, with your name cut to 18 characters, always fits in one. A message the gateway refuses is not charged. Top-ups are done with OTP.ps; the balance is on the dashboard and at `GET /api/v1/balance`.

## Not available

No delivery reports or webhooks yet, and no separate resend endpoint (send again). Their absence is deliberate, not an omission in this page.
