Reference

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

FieldTypeDescription
phonestringrequiredA Jawwal (059) or Ooredoo (056) mobile, written any common way. See Phone numbers.
locale"ar" | "en"optionalLanguage of the message. Defaults to your account setting (Arabic for new accounts).
purposestringoptionalOne of verify, login, signup, order, appointment. Only changes the wording. Default verify.
HeaderDescription
Idempotency-KeyoptionalUp 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:

purposeArabicEnglish
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

FieldTypeDescription
idstringone of id / phoneThe verification id from the send answer. Preferred.
phonestringone of id / phoneChecks the latest code sent to this number with this key's mode.
codestringrequiredWhat the customer typed. Spaces and Arabic-Indic digits are fine.

Answer 200: the verification plus:

FieldTypeDescription
validbooleantrue only on the check that approved the code. Rely on this.
attempts_leftintegerChecks 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.

Scope
POST /api/v1/verify/linkssendCreate a verification link (url only in this answer)
GET /api/v1/verify/linksreadList, newest first: status, reference, limit (1–100), before (a link id)
GET /api/v1/verify/links/{id}readOne link
POST /api/v1/verify/links/{id}/cancelsendCancel a pending link (409 invalid_state otherwise)
POST /api/v1/webhooks, GET /api/v1/webhooks, DELETE /api/v1/webhooks/{id}readWebhook addresses

The verification object

FieldTypeDescription
idstringver_…
statusstringpending, approved, expired, failed or canceled. See lifecycle.
tostringThe number, partly hidden: 0599 ••• 456.
networkstringjawwal or ooredoo.
purpose, localestringAs sent.
segmentsintegerText messages charged (0 with a test key, and when the message couldn't be sent).
attemptsintegerChecks made so far.
testbooleanMade with a test key.
created_at, expires_atstringISO 8601, UTC.
verified_atstring | nullWhen 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.

View as Markdown