API reference
Every endpoint, field and answer of the OTP.ps REST API.
Base address: https://otp.ps. All requests need an API key. 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, 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. |
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, 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:
{ "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.
{
"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.
{
"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.
Verification links and webhooks
| Scope | ||
|---|---|---|
POST /api/v1/verify/links | send | Create a verification link (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 addresses |
The verification object
| Field | Type | Description |
|---|---|---|
id | string | ver_… |
status | string | pending, approved, expired, failed or canceled. See 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:
{ "error": "rate_limited", "message": "Too many codes for this phone number. Try again later.", "retry_after": 27 }The full list is on 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.