{"openapi":"3.1.0","info":{"title":"OTP.ps API","version":"1.3.0","summary":"SMS verification codes (OTP) for Palestinian mobile numbers (Jawwal and Ooredoo).","description":"Send a one-time code by text message, then check what the customer typed. Arabic or English messages, starting with the business's name.\n\n**Flow:** `POST /api/v1/verify/send` → keep the `id` → the customer types the code → `POST /api/v1/verify/check` with `id` and `code` → trust only `valid: true`.\n\n**Keys belong on your server.** Never put a key in browser or mobile-app code. The API sends no CORS headers.\n\n**Codes:** 4 or 6 digits (account setting), valid 1–15 minutes (default 5), 5 tries, single use. A new code to the same number cancels the previous one. Resending is just sending again (after the cooldown).\n\n**Limits** (per account and key mode): per number one code every 30 s, 5 an hour, 10 a day; per account 120 a minute. Exceeding them answers 429 with `retry_after`.\n\n**Key permissions:** each key has scopes: `send` (POST /verify/send), `check` (POST /verify/check) and `read` (GET verification, balance, usage, limits). Keys made before scopes existed have all three. A missing scope answers 403 `insufficient_scope`.\n\n**Spending limits** (live messages only, Palestine time): a daily ceiling per account set by OTP.ps against SMS pumping, the business's own daily and monthly limits, and an optional daily limit per key. Reaching one answers 429 `spending_limit_reached` with `retry_after` until it resets. `GET /api/v1/limits` shows them with what has been used.\n\n**Verification links** (for platforms with no screen of their own: Shopify Flow, Zapier, Make, n8n, a thank-you page): `POST /api/v1/verify/links` gives a link to a page OTP.ps hosts. With `delivery: \"sms\"` OTP.ps texts the link and the customer presses Confirm; with `delivery: \"none\"` the business shares the link and the page texts a code. Either way the link becomes `approved` and a `link.approved` webhook is sent.\n\n**Webhooks:** register a public https address (`POST /api/v1/webhooks` or the dashboard) to receive `link.approved`, `link.expired` and `link.canceled`, signed with `OTP-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, \"<t>.<raw body>\")>`. Failed deliveries are retried for about a day.\n\n**Billing:** a prepaid balance counted in text messages. A live send takes one credit per message part (Arabic: 70 characters, English: 160); the standard wording always fits in one. A message the gateway refuses is not charged.\n\n**Idempotency:** send an `Idempotency-Key` header on `/verify/send` to retry safely. For 24 hours, the same key and request returns the first answer (with `Idempotent-Replayed: true`) without sending or charging again; the same key with a different request answers 409 `idempotency_conflict`. Refusals that created nothing (validation, limits, balance) are not remembered.\n\n**Sandbox:** test keys (`otp_test_…`) use the same endpoints and answers but never send a message or use credit, work before the account is approved, and return the code as `test_code`. Test and live verifications are fully separate. These numbers simulate outcomes with a test key:\n\n| Number | With a test key |\n|---|---|\n| `0599000001` | Sent successfully. The code is always 1234 (or 123456 for 6-digit codes). |\n| `0569000001` | Ooredoo number, sent successfully. The code is always 1234 (or 123456). |\n| `0599000002` | The gateway refuses the message: 502 sms_failed. Nothing is charged. |\n| `0599000003` | Answers 402 insufficient_balance, as if the account had no credit left. |\n| `0599000004` | Answers 429 rate_limited with retry_after 30, as if the number had just received a code. |\n| `0599000005` | Sent successfully with code 1234 (or 123456), but the code has already expired: checking it answers status expired. |\n\nDelivery status is not available: the gateway confirms only that it accepted the message.","contact":{"name":"OTP.ps","url":"https://otp.ps"}},"externalDocs":{"description":"Developer documentation","url":"https://otp.ps/docs"},"servers":[{"url":"https://otp.ps","description":"OTP.ps"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Verification","description":"Send and check codes."},{"name":"Links","description":"Verification links: a page OTP.ps hosts where the customer confirms the number."},{"name":"Webhooks","description":"Addresses that receive link events."},{"name":"Account","description":"Balance and account state."}],"paths":{"/api/v1/verify/send":{"post":{"operationId":"sendVerification","tags":["Verification"],"summary":"Send a code","description":"Sends a new code by text message to a Jawwal or Ooredoo number. Any earlier unused code for that number (same key mode) is cancelled.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. Up to 100 letters, digits or - _ : . characters. Retrying with the same key and request within 24 hours returns the first answer instead of sending again.","schema":{"type":"string","pattern":"^[A-Za-z0-9_\\-:.]{1,100}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendRequest"},"examples":{"order":{"summary":"Cash-on-delivery order, Arabic","value":{"phone":"0599123456","purpose":"order","locale":"ar"}},"login":{"summary":"Login, English","value":{"phone":"+970569123456","purpose":"login","locale":"en"}}}},"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/SendRequest"}}}},"responses":{"201":{"description":"The code was sent (or, with a test key, made). Keep `id` to check the code.","headers":{"Idempotent-Replayed":{"description":"`true` when this is the remembered answer to an earlier request with the same Idempotency-Key.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendResponse"},"examples":{"live":{"value":{"id":"ver_9f2KxQe1Lm0aBcDe","status":"pending","to":"0599 ••• 456","network":"jawwal","purpose":"order","locale":"ar","segments":1,"attempts":0,"test":false,"created_at":"2026-11-19T10:00:00.000Z","expires_at":"2026-11-19T10:05:00.000Z","verified_at":null}},"test":{"summary":"Test key","value":{"id":"ver_9f2KxQe1Lm0aBcDe","status":"pending","to":"0599 ••• 456","network":"jawwal","purpose":"order","locale":"ar","segments":0,"attempts":0,"test":true,"created_at":"2026-11-19T10:00:00.000Z","expires_at":"2026-11-19T10:05:00.000Z","verified_at":null,"test_code":"1234"}}}}}},"400":{"description":"`invalid_request`: The body isn't a JSON object, or a field is missing or has a value that isn't allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_request":{"value":{"error":"invalid_request","message":"The body isn't a JSON object, or a field is missing or has a value that isn't allowed."}}}}}},"401":{"description":"`unauthorized`: The API key is missing, malformed, unknown or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"unauthorized":{"value":{"error":"unauthorized","message":"The API key is missing, malformed, unknown or revoked."}}}}}},"402":{"description":"`insufficient_balance`: Not enough credit left for this message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_balance":{"value":{"error":"insufficient_balance","message":"Not enough credit left for this message."}}}}}},"403":{"description":"`insufficient_scope`: This API key isn't allowed to do this (its permissions don't include send, check or read). `account_pending`: The account is waiting for approval, so live keys can't send yet. `account_suspended`: The account is suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"value":{"error":"insufficient_scope","message":"This API key isn't allowed to do this (its permissions don't include send, check or read)."}},"account_pending":{"value":{"error":"account_pending","message":"The account is waiting for approval, so live keys can't send yet."}},"account_suspended":{"value":{"error":"account_suspended","message":"The account is suspended."}}}}}},"409":{"description":"`idempotency_conflict`: This Idempotency-Key was already used with a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_conflict":{"value":{"error":"idempotency_conflict","message":"This Idempotency-Key was already used with a different request."}}}}}},"422":{"description":"`invalid_phone`: The number is not a valid Palestinian mobile number. `unsupported_network`: The number is valid but not on Jawwal (059) or Ooredoo (056).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_phone":{"value":{"error":"invalid_phone","message":"The number is not a valid Palestinian mobile number."}},"unsupported_network":{"value":{"error":"unsupported_network","message":"The number is valid but not on Jawwal (059) or Ooredoo (056)."}}}}}},"429":{"description":"`rate_limited`: Too many codes for this number (or this account) in a short time. `spending_limit_reached`: A spending limit is reached: the account's daily or monthly message limit, the daily ceiling set by OTP.ps, or this key's daily limit.","headers":{"Retry-After":{"description":"Seconds to wait.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":"rate_limited","message":"Too many codes for this number (or this account) in a short time.","retry_after":27}},"spending_limit_reached":{"value":{"error":"spending_limit_reached","message":"A spending limit is reached: the account's daily or monthly message limit, the daily ceiling set by OTP.ps, or this key's daily limit."}}}}}},"502":{"description":"`sms_failed`: The text message gateway refused or couldn't take the message. Nothing was charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sms_failed":{"value":{"error":"sms_failed","message":"The text message gateway refused or couldn't take the message. Nothing was charged."}}}}}}}}},"/api/v1/verify/check":{"post":{"operationId":"checkVerification","tags":["Verification"],"summary":"Check a code","description":"Checks the code the customer typed. Give `id` (preferred) or `phone` (the latest code sent to that number with this key's mode). Each code allows 5 checks; `valid` is true only on the check that approves it.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckRequest"},"examples":{"byId":{"value":{"id":"ver_9f2KxQe1Lm0aBcDe","code":"4821"}},"byPhone":{"value":{"phone":"0599123456","code":"4821"}}}},"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/CheckRequest"}}}},"responses":{"200":{"description":"The check was made. Look at `valid` (and `status` / `attempts_left` to explain a refusal).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckResponse"},"examples":{"right":{"summary":"Right code","value":{"id":"ver_9f2KxQe1Lm0aBcDe","status":"approved","to":"0599 ••• 456","network":"jawwal","purpose":"order","locale":"ar","segments":1,"attempts":1,"test":false,"created_at":"2026-11-19T10:00:00.000Z","expires_at":"2026-11-19T10:05:00.000Z","verified_at":"2026-11-19T10:01:12.000Z","valid":true,"attempts_left":0}},"wrong":{"summary":"Wrong code","value":{"id":"ver_9f2KxQe1Lm0aBcDe","status":"pending","to":"0599 ••• 456","network":"jawwal","purpose":"order","locale":"ar","segments":1,"attempts":2,"test":false,"created_at":"2026-11-19T10:00:00.000Z","expires_at":"2026-11-19T10:05:00.000Z","verified_at":null,"valid":false,"attempts_left":3}},"expired":{"summary":"Too late","value":{"id":"ver_9f2KxQe1Lm0aBcDe","status":"expired","to":"0599 ••• 456","network":"jawwal","purpose":"order","locale":"ar","segments":1,"attempts":0,"test":false,"created_at":"2026-11-19T10:00:00.000Z","expires_at":"2026-11-19T10:05:00.000Z","verified_at":null,"valid":false,"attempts_left":0}}}}}},"400":{"description":"`invalid_request`: The body isn't a JSON object, or a field is missing or has a value that isn't allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_request":{"value":{"error":"invalid_request","message":"The body isn't a JSON object, or a field is missing or has a value that isn't allowed."}}}}}},"401":{"description":"`unauthorized`: The API key is missing, malformed, unknown or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"unauthorized":{"value":{"error":"unauthorized","message":"The API key is missing, malformed, unknown or revoked."}}}}}},"403":{"description":"`insufficient_scope`: This API key isn't allowed to do this (its permissions don't include send, check or read).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"value":{"error":"insufficient_scope","message":"This API key isn't allowed to do this (its permissions don't include send, check or read)."}}}}}},"404":{"description":"`not_found`: No verification with that id (or for that number) exists for this key's account and mode.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_found":{"value":{"error":"not_found","message":"No verification with that id (or for that number) exists for this key's account and mode."}}}}}},"422":{"description":"`invalid_phone`: The number is not a valid Palestinian mobile number. `unsupported_network`: The number is valid but not on Jawwal (059) or Ooredoo (056).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_phone":{"value":{"error":"invalid_phone","message":"The number is not a valid Palestinian mobile number."}},"unsupported_network":{"value":{"error":"unsupported_network","message":"The number is valid but not on Jawwal (059) or Ooredoo (056)."}}}}}}}}},"/api/v1/verify/{id}":{"get":{"operationId":"getVerification","tags":["Verification"],"summary":"Get a verification","description":"The verification's current state. Only verifications of the key's own account and mode are visible.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"example":"ver_9f2KxQe1Lm0aBcDe"}],"responses":{"200":{"description":"The verification.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Verification"},"example":{"id":"ver_9f2KxQe1Lm0aBcDe","status":"pending","to":"0599 ••• 456","network":"jawwal","purpose":"order","locale":"ar","segments":1,"attempts":0,"test":false,"created_at":"2026-11-19T10:00:00.000Z","expires_at":"2026-11-19T10:05:00.000Z","verified_at":null}}}},"401":{"description":"`unauthorized`: The API key is missing, malformed, unknown or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"unauthorized":{"value":{"error":"unauthorized","message":"The API key is missing, malformed, unknown or revoked."}}}}}},"403":{"description":"`insufficient_scope`: This API key isn't allowed to do this (its permissions don't include send, check or read).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"value":{"error":"insufficient_scope","message":"This API key isn't allowed to do this (its permissions don't include send, check or read)."}}}}}},"404":{"description":"`not_found`: No verification with that id (or for that number) exists for this key's account and mode.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_found":{"value":{"error":"not_found","message":"No verification with that id (or for that number) exists for this key's account and mode."}}}}}}}}},"/api/v1/verify/links":{"post":{"operationId":"createLink","tags":["Links"],"summary":"Create a verification link","description":"A link to a page OTP.ps hosts where the customer confirms the number. delivery sms (default): OTP.ps texts the link (one message, charged like a code) and the customer presses Confirm. delivery none: you share the link; the page texts a code (charged when sent). Needs the `send` scope. Supports Idempotency-Key.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[A-Za-z0-9_\\-:.]{1,100}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LinkRequest"},"examples":{"cod":{"summary":"Cash-on-delivery order, texted to the customer","value":{"phone":"0599123456","purpose":"order","reference":"#1042","delivery":"sms"}}}}}},"responses":{"201":{"description":"The link. `url` is returned only here.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LinkCreated"},"example":{"id":"lnk_Xq3vB9kLm2Pz7RtY","object":"link","status":"pending","to":"0599 ••• 456","network":"jawwal","purpose":"order","locale":"ar","delivery":"sms","reference":"#1042","return_url":null,"segments":1,"test":false,"created_at":"2026-11-19T10:00:00.000Z","expires_at":"2026-11-20T10:00:00.000Z","opened_at":null,"approved_at":null,"url":"https://otp.ps/v/Ab3dE5gH7jK9"}}}},"400":{"description":"`invalid_request`: The body isn't a JSON object, or a field is missing or has a value that isn't allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_request":{"value":{"error":"invalid_request","message":"The body isn't a JSON object, or a field is missing or has a value that isn't allowed."}}}}}},"401":{"description":"`unauthorized`: The API key is missing, malformed, unknown or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"unauthorized":{"value":{"error":"unauthorized","message":"The API key is missing, malformed, unknown or revoked."}}}}}},"402":{"description":"`insufficient_balance`: Not enough credit left for this message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_balance":{"value":{"error":"insufficient_balance","message":"Not enough credit left for this message."}}}}}},"403":{"description":"`insufficient_scope`: This API key isn't allowed to do this (its permissions don't include send, check or read). `account_pending`: The account is waiting for approval, so live keys can't send yet. `account_suspended`: The account is suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"value":{"error":"insufficient_scope","message":"This API key isn't allowed to do this (its permissions don't include send, check or read)."}},"account_pending":{"value":{"error":"account_pending","message":"The account is waiting for approval, so live keys can't send yet."}},"account_suspended":{"value":{"error":"account_suspended","message":"The account is suspended."}}}}}},"404":{"description":"`not_found`: No verification with that id (or for that number) exists for this key's account and mode.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_found":{"value":{"error":"not_found","message":"No verification with that id (or for that number) exists for this key's account and mode."}}}}}},"409":{"description":"`idempotency_conflict`: This Idempotency-Key was already used with a different request. `invalid_state`: The verification link can't be changed any more: it is already approved, expired or canceled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_conflict":{"value":{"error":"idempotency_conflict","message":"This Idempotency-Key was already used with a different request."}},"invalid_state":{"value":{"error":"invalid_state","message":"The verification link can't be changed any more: it is already approved, expired or canceled."}}}}}},"422":{"description":"`invalid_phone`: The number is not a valid Palestinian mobile number. `unsupported_network`: The number is valid but not on Jawwal (059) or Ooredoo (056).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_phone":{"value":{"error":"invalid_phone","message":"The number is not a valid Palestinian mobile number."}},"unsupported_network":{"value":{"error":"unsupported_network","message":"The number is valid but not on Jawwal (059) or Ooredoo (056)."}}}}}},"429":{"description":"`rate_limited`: Too many codes for this number (or this account) in a short time. `spending_limit_reached`: A spending limit is reached: the account's daily or monthly message limit, the daily ceiling set by OTP.ps, or this key's daily limit.","headers":{"Retry-After":{"description":"Seconds to wait.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":"rate_limited","message":"Too many codes for this number (or this account) in a short time.","retry_after":27}},"spending_limit_reached":{"value":{"error":"spending_limit_reached","message":"A spending limit is reached: the account's daily or monthly message limit, the daily ceiling set by OTP.ps, or this key's daily limit."}}}}}},"502":{"description":"`sms_failed`: The text message gateway refused or couldn't take the message. Nothing was charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sms_failed":{"value":{"error":"sms_failed","message":"The text message gateway refused or couldn't take the message. Nothing was charged."}}}}}}}},"get":{"operationId":"listLinks","tags":["Links"],"summary":"List links","description":"Newest first, for the key's mode. Needs the `read` scope. Good for polling: `?status=approved`.","parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["pending","approved","expired","canceled"]}},{"name":"reference","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"before","in":"query","description":"A link id: only links created before it.","schema":{"type":"string"}}],"responses":{"200":{"description":"Links.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LinkList"},"example":{"data":[{"id":"lnk_Xq3vB9kLm2Pz7RtY","object":"link","status":"pending","to":"0599 ••• 456","network":"jawwal","purpose":"order","locale":"ar","delivery":"sms","reference":"#1042","return_url":null,"segments":1,"test":false,"created_at":"2026-11-19T10:00:00.000Z","expires_at":"2026-11-20T10:00:00.000Z","opened_at":null,"approved_at":null}],"has_more":false}}}},"400":{"description":"`invalid_request`: The body isn't a JSON object, or a field is missing or has a value that isn't allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_request":{"value":{"error":"invalid_request","message":"The body isn't a JSON object, or a field is missing or has a value that isn't allowed."}}}}}},"401":{"description":"`unauthorized`: The API key is missing, malformed, unknown or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"unauthorized":{"value":{"error":"unauthorized","message":"The API key is missing, malformed, unknown or revoked."}}}}}},"402":{"description":"`insufficient_balance`: Not enough credit left for this message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_balance":{"value":{"error":"insufficient_balance","message":"Not enough credit left for this message."}}}}}},"403":{"description":"`insufficient_scope`: This API key isn't allowed to do this (its permissions don't include send, check or read). `account_pending`: The account is waiting for approval, so live keys can't send yet. `account_suspended`: The account is suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"value":{"error":"insufficient_scope","message":"This API key isn't allowed to do this (its permissions don't include send, check or read)."}},"account_pending":{"value":{"error":"account_pending","message":"The account is waiting for approval, so live keys can't send yet."}},"account_suspended":{"value":{"error":"account_suspended","message":"The account is suspended."}}}}}},"404":{"description":"`not_found`: No verification with that id (or for that number) exists for this key's account and mode.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_found":{"value":{"error":"not_found","message":"No verification with that id (or for that number) exists for this key's account and mode."}}}}}},"409":{"description":"`idempotency_conflict`: This Idempotency-Key was already used with a different request. `invalid_state`: The verification link can't be changed any more: it is already approved, expired or canceled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_conflict":{"value":{"error":"idempotency_conflict","message":"This Idempotency-Key was already used with a different request."}},"invalid_state":{"value":{"error":"invalid_state","message":"The verification link can't be changed any more: it is already approved, expired or canceled."}}}}}},"422":{"description":"`invalid_phone`: The number is not a valid Palestinian mobile number. `unsupported_network`: The number is valid but not on Jawwal (059) or Ooredoo (056).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_phone":{"value":{"error":"invalid_phone","message":"The number is not a valid Palestinian mobile number."}},"unsupported_network":{"value":{"error":"unsupported_network","message":"The number is valid but not on Jawwal (059) or Ooredoo (056)."}}}}}},"429":{"description":"`rate_limited`: Too many codes for this number (or this account) in a short time. `spending_limit_reached`: A spending limit is reached: the account's daily or monthly message limit, the daily ceiling set by OTP.ps, or this key's daily limit.","headers":{"Retry-After":{"description":"Seconds to wait.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":"rate_limited","message":"Too many codes for this number (or this account) in a short time.","retry_after":27}},"spending_limit_reached":{"value":{"error":"spending_limit_reached","message":"A spending limit is reached: the account's daily or monthly message limit, the daily ceiling set by OTP.ps, or this key's daily limit."}}}}}},"502":{"description":"`sms_failed`: The text message gateway refused or couldn't take the message. Nothing was charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sms_failed":{"value":{"error":"sms_failed","message":"The text message gateway refused or couldn't take the message. Nothing was charged."}}}}}}}}},"/api/v1/verify/links/{id}":{"get":{"operationId":"getLink","tags":["Links"],"summary":"Get a link","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The link.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Link"},"example":{"id":"lnk_Xq3vB9kLm2Pz7RtY","object":"link","status":"pending","to":"0599 ••• 456","network":"jawwal","purpose":"order","locale":"ar","delivery":"sms","reference":"#1042","return_url":null,"segments":1,"test":false,"created_at":"2026-11-19T10:00:00.000Z","expires_at":"2026-11-20T10:00:00.000Z","opened_at":null,"approved_at":null}}}},"400":{"description":"`invalid_request`: The body isn't a JSON object, or a field is missing or has a value that isn't allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_request":{"value":{"error":"invalid_request","message":"The body isn't a JSON object, or a field is missing or has a value that isn't allowed."}}}}}},"401":{"description":"`unauthorized`: The API key is missing, malformed, unknown or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"unauthorized":{"value":{"error":"unauthorized","message":"The API key is missing, malformed, unknown or revoked."}}}}}},"402":{"description":"`insufficient_balance`: Not enough credit left for this message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_balance":{"value":{"error":"insufficient_balance","message":"Not enough credit left for this message."}}}}}},"403":{"description":"`insufficient_scope`: This API key isn't allowed to do this (its permissions don't include send, check or read). `account_pending`: The account is waiting for approval, so live keys can't send yet. `account_suspended`: The account is suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"value":{"error":"insufficient_scope","message":"This API key isn't allowed to do this (its permissions don't include send, check or read)."}},"account_pending":{"value":{"error":"account_pending","message":"The account is waiting for approval, so live keys can't send yet."}},"account_suspended":{"value":{"error":"account_suspended","message":"The account is suspended."}}}}}},"404":{"description":"`not_found`: No verification with that id (or for that number) exists for this key's account and mode.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_found":{"value":{"error":"not_found","message":"No verification with that id (or for that number) exists for this key's account and mode."}}}}}},"409":{"description":"`idempotency_conflict`: This Idempotency-Key was already used with a different request. `invalid_state`: The verification link can't be changed any more: it is already approved, expired or canceled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_conflict":{"value":{"error":"idempotency_conflict","message":"This Idempotency-Key was already used with a different request."}},"invalid_state":{"value":{"error":"invalid_state","message":"The verification link can't be changed any more: it is already approved, expired or canceled."}}}}}},"422":{"description":"`invalid_phone`: The number is not a valid Palestinian mobile number. `unsupported_network`: The number is valid but not on Jawwal (059) or Ooredoo (056).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_phone":{"value":{"error":"invalid_phone","message":"The number is not a valid Palestinian mobile number."}},"unsupported_network":{"value":{"error":"unsupported_network","message":"The number is valid but not on Jawwal (059) or Ooredoo (056)."}}}}}},"429":{"description":"`rate_limited`: Too many codes for this number (or this account) in a short time. `spending_limit_reached`: A spending limit is reached: the account's daily or monthly message limit, the daily ceiling set by OTP.ps, or this key's daily limit.","headers":{"Retry-After":{"description":"Seconds to wait.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":"rate_limited","message":"Too many codes for this number (or this account) in a short time.","retry_after":27}},"spending_limit_reached":{"value":{"error":"spending_limit_reached","message":"A spending limit is reached: the account's daily or monthly message limit, the daily ceiling set by OTP.ps, or this key's daily limit."}}}}}},"502":{"description":"`sms_failed`: The text message gateway refused or couldn't take the message. Nothing was charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sms_failed":{"value":{"error":"sms_failed","message":"The text message gateway refused or couldn't take the message. Nothing was charged."}}}}}}}}},"/api/v1/verify/links/{id}/cancel":{"post":{"operationId":"cancelLink","tags":["Links"],"summary":"Cancel a link","description":"The link stops working and `link.canceled` is sent. Only pending links can be canceled (else 409 `invalid_state`).","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The canceled link.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Link"},"example":{"id":"lnk_Xq3vB9kLm2Pz7RtY","object":"link","status":"canceled","to":"0599 ••• 456","network":"jawwal","purpose":"order","locale":"ar","delivery":"sms","reference":"#1042","return_url":null,"segments":1,"test":false,"created_at":"2026-11-19T10:00:00.000Z","expires_at":"2026-11-20T10:00:00.000Z","opened_at":null,"approved_at":null}}}},"400":{"description":"`invalid_request`: The body isn't a JSON object, or a field is missing or has a value that isn't allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_request":{"value":{"error":"invalid_request","message":"The body isn't a JSON object, or a field is missing or has a value that isn't allowed."}}}}}},"401":{"description":"`unauthorized`: The API key is missing, malformed, unknown or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"unauthorized":{"value":{"error":"unauthorized","message":"The API key is missing, malformed, unknown or revoked."}}}}}},"402":{"description":"`insufficient_balance`: Not enough credit left for this message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_balance":{"value":{"error":"insufficient_balance","message":"Not enough credit left for this message."}}}}}},"403":{"description":"`insufficient_scope`: This API key isn't allowed to do this (its permissions don't include send, check or read). `account_pending`: The account is waiting for approval, so live keys can't send yet. `account_suspended`: The account is suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"value":{"error":"insufficient_scope","message":"This API key isn't allowed to do this (its permissions don't include send, check or read)."}},"account_pending":{"value":{"error":"account_pending","message":"The account is waiting for approval, so live keys can't send yet."}},"account_suspended":{"value":{"error":"account_suspended","message":"The account is suspended."}}}}}},"404":{"description":"`not_found`: No verification with that id (or for that number) exists for this key's account and mode.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_found":{"value":{"error":"not_found","message":"No verification with that id (or for that number) exists for this key's account and mode."}}}}}},"409":{"description":"`idempotency_conflict`: This Idempotency-Key was already used with a different request. `invalid_state`: The verification link can't be changed any more: it is already approved, expired or canceled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_conflict":{"value":{"error":"idempotency_conflict","message":"This Idempotency-Key was already used with a different request."}},"invalid_state":{"value":{"error":"invalid_state","message":"The verification link can't be changed any more: it is already approved, expired or canceled."}}}}}},"422":{"description":"`invalid_phone`: The number is not a valid Palestinian mobile number. `unsupported_network`: The number is valid but not on Jawwal (059) or Ooredoo (056).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_phone":{"value":{"error":"invalid_phone","message":"The number is not a valid Palestinian mobile number."}},"unsupported_network":{"value":{"error":"unsupported_network","message":"The number is valid but not on Jawwal (059) or Ooredoo (056)."}}}}}},"429":{"description":"`rate_limited`: Too many codes for this number (or this account) in a short time. `spending_limit_reached`: A spending limit is reached: the account's daily or monthly message limit, the daily ceiling set by OTP.ps, or this key's daily limit.","headers":{"Retry-After":{"description":"Seconds to wait.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":"rate_limited","message":"Too many codes for this number (or this account) in a short time.","retry_after":27}},"spending_limit_reached":{"value":{"error":"spending_limit_reached","message":"A spending limit is reached: the account's daily or monthly message limit, the daily ceiling set by OTP.ps, or this key's daily limit."}}}}}},"502":{"description":"`sms_failed`: The text message gateway refused or couldn't take the message. Nothing was charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sms_failed":{"value":{"error":"sms_failed","message":"The text message gateway refused or couldn't take the message. Nothing was charged."}}}}}}}}},"/api/v1/webhooks":{"post":{"operationId":"createWebhook","tags":["Webhooks"],"summary":"Add a webhook address","description":"For the key's mode (test keys: events of test links). Returns the signing secret once. Needs the `read` scope.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookRequest"},"example":{"url":"https://hooks.example.com/otp","events":["link.approved"]}}}},"responses":{"201":{"description":"The address and its secret.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookCreated"},"example":{"id":"whe_Ab12Cd34Ef56","object":"webhook","url":"https://hooks.example.com/otp","events":["link.approved"],"test":false,"description":"","created_at":"2026-11-19T10:00:00.000Z","secret":"whsec_…"}}}},"400":{"description":"`invalid_request`: The body isn't a JSON object, or a field is missing or has a value that isn't allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_request":{"value":{"error":"invalid_request","message":"The body isn't a JSON object, or a field is missing or has a value that isn't allowed."}}}}}},"401":{"description":"`unauthorized`: The API key is missing, malformed, unknown or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"unauthorized":{"value":{"error":"unauthorized","message":"The API key is missing, malformed, unknown or revoked."}}}}}},"403":{"description":"`insufficient_scope`: This API key isn't allowed to do this (its permissions don't include send, check or read).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"value":{"error":"insufficient_scope","message":"This API key isn't allowed to do this (its permissions don't include send, check or read)."}}}}}},"404":{"description":"`not_found`: No verification with that id (or for that number) exists for this key's account and mode.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_found":{"value":{"error":"not_found","message":"No verification with that id (or for that number) exists for this key's account and mode."}}}}}}}},"get":{"operationId":"listWebhooks","tags":["Webhooks"],"summary":"List webhook addresses","responses":{"200":{"description":"Addresses (without secrets).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookList"},"example":{"data":[{"id":"whe_Ab12Cd34Ef56","object":"webhook","url":"https://hooks.example.com/otp","events":["link.approved"],"test":false,"description":"","created_at":"2026-11-19T10:00:00.000Z"}]}}}},"400":{"description":"`invalid_request`: The body isn't a JSON object, or a field is missing or has a value that isn't allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_request":{"value":{"error":"invalid_request","message":"The body isn't a JSON object, or a field is missing or has a value that isn't allowed."}}}}}},"401":{"description":"`unauthorized`: The API key is missing, malformed, unknown or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"unauthorized":{"value":{"error":"unauthorized","message":"The API key is missing, malformed, unknown or revoked."}}}}}},"403":{"description":"`insufficient_scope`: This API key isn't allowed to do this (its permissions don't include send, check or read).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"value":{"error":"insufficient_scope","message":"This API key isn't allowed to do this (its permissions don't include send, check or read)."}}}}}},"404":{"description":"`not_found`: No verification with that id (or for that number) exists for this key's account and mode.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_found":{"value":{"error":"not_found","message":"No verification with that id (or for that number) exists for this key's account and mode."}}}}}}}}},"/api/v1/webhooks/{id}":{"delete":{"operationId":"deleteWebhook","tags":["Webhooks"],"summary":"Remove a webhook address","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Removed.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"type":"boolean"}},"required":["id","deleted"]}}}},"400":{"description":"`invalid_request`: The body isn't a JSON object, or a field is missing or has a value that isn't allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_request":{"value":{"error":"invalid_request","message":"The body isn't a JSON object, or a field is missing or has a value that isn't allowed."}}}}}},"401":{"description":"`unauthorized`: The API key is missing, malformed, unknown or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"unauthorized":{"value":{"error":"unauthorized","message":"The API key is missing, malformed, unknown or revoked."}}}}}},"403":{"description":"`insufficient_scope`: This API key isn't allowed to do this (its permissions don't include send, check or read).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"value":{"error":"insufficient_scope","message":"This API key isn't allowed to do this (its permissions don't include send, check or read)."}}}}}},"404":{"description":"`not_found`: No verification with that id (or for that number) exists for this key's account and mode.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_found":{"value":{"error":"not_found","message":"No verification with that id (or for that number) exists for this key's account and mode."}}}}}}}}},"/api/v1/usage":{"get":{"operationId":"getUsage","tags":["Account"],"summary":"Get usage","description":"Codes sent, approved and failed, and messages charged: today, this month and each of the last 30 days, in Palestine time, for the key's mode. Needs the `read` scope.","responses":{"200":{"description":"Usage.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Usage"},"example":{"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}]}}}},"401":{"description":"`unauthorized`: The API key is missing, malformed, unknown or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"unauthorized":{"value":{"error":"unauthorized","message":"The API key is missing, malformed, unknown or revoked."}}}}}},"403":{"description":"`insufficient_scope`: This API key isn't allowed to do this (its permissions don't include send, check or read).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"value":{"error":"insufficient_scope","message":"This API key isn't allowed to do this (its permissions don't include send, check or read)."}}}}}}}}},"/api/v1/limits":{"get":{"operationId":"getLimits","tags":["Account"],"summary":"Get limits","description":"The key's permissions, code settings, rate limits, and spending limits with what has been used. Needs the `read` scope.","responses":{"200":{"description":"Limits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Limits"},"example":{"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}}}}}},"401":{"description":"`unauthorized`: The API key is missing, malformed, unknown or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"unauthorized":{"value":{"error":"unauthorized","message":"The API key is missing, malformed, unknown or revoked."}}}}}},"403":{"description":"`insufficient_scope`: This API key isn't allowed to do this (its permissions don't include send, check or read).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"value":{"error":"insufficient_scope","message":"This API key isn't allowed to do this (its permissions don't include send, check or read)."}}}}}}}}},"/api/v1/balance":{"get":{"operationId":"getBalance","tags":["Account"],"summary":"Get the balance","responses":{"200":{"description":"Credits left and the account's state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Balance"},"example":{"credits":1250,"status":"active","mode":"live"}}}},"401":{"description":"`unauthorized`: The API key is missing, malformed, unknown or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"unauthorized":{"value":{"error":"unauthorized","message":"The API key is missing, malformed, unknown or revoked."}}}}}},"403":{"description":"`insufficient_scope`: This API key isn't allowed to do this (its permissions don't include send, check or read).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"value":{"error":"insufficient_scope","message":"This API key isn't allowed to do this (its permissions don't include send, check or read)."}}}}}}}}}},"webhooks":{"link.approved":{"post":{"summary":"link.approved","description":"Sent to your webhook address. Check the OTP-Signature header before trusting it. Answer 2xx within 8 seconds; anything else is retried for about a day.","parameters":[{"name":"OTP-Signature","in":"header","required":true,"schema":{"type":"string"},"example":"t=1763546400,v1=5257a869…"},{"name":"OTP-Event-Id","in":"header","required":true,"schema":{"type":"string"}},{"name":"OTP-Event-Type","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"example":{"id":"evt_9aB3cD4eF5gH6iJ7","type":"link.approved","created_at":"2026-11-19T10:03:00.000Z","test":false,"data":{"id":"lnk_Xq3vB9kLm2Pz7RtY","object":"link","status":"approved","to":"0599 ••• 456","network":"jawwal","purpose":"order","locale":"ar","delivery":"sms","reference":"#1042","return_url":null,"segments":1,"test":false,"created_at":"2026-11-19T10:00:00.000Z","expires_at":"2026-11-20T10:00:00.000Z","opened_at":null,"approved_at":"2026-11-19T10:03:00.000Z"}}}}},"responses":{"200":{"description":"Received."}}}},"link.expired":{"post":{"summary":"link.expired","description":"Sent to your webhook address. Check the OTP-Signature header before trusting it. Answer 2xx within 8 seconds; anything else is retried for about a day.","parameters":[{"name":"OTP-Signature","in":"header","required":true,"schema":{"type":"string"},"example":"t=1763546400,v1=5257a869…"},{"name":"OTP-Event-Id","in":"header","required":true,"schema":{"type":"string"}},{"name":"OTP-Event-Type","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"example":{"id":"evt_9aB3cD4eF5gH6iJ7","type":"link.expired","created_at":"2026-11-19T10:03:00.000Z","test":false,"data":{"id":"lnk_Xq3vB9kLm2Pz7RtY","object":"link","status":"expired","to":"0599 ••• 456","network":"jawwal","purpose":"order","locale":"ar","delivery":"sms","reference":"#1042","return_url":null,"segments":1,"test":false,"created_at":"2026-11-19T10:00:00.000Z","expires_at":"2026-11-20T10:00:00.000Z","opened_at":null,"approved_at":null}}}}},"responses":{"200":{"description":"Received."}}}},"link.canceled":{"post":{"summary":"link.canceled","description":"Sent to your webhook address. Check the OTP-Signature header before trusting it. Answer 2xx within 8 seconds; anything else is retried for about a day.","parameters":[{"name":"OTP-Signature","in":"header","required":true,"schema":{"type":"string"},"example":"t=1763546400,v1=5257a869…"},{"name":"OTP-Event-Id","in":"header","required":true,"schema":{"type":"string"}},{"name":"OTP-Event-Type","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"example":{"id":"evt_9aB3cD4eF5gH6iJ7","type":"link.canceled","created_at":"2026-11-19T10:03:00.000Z","test":false,"data":{"id":"lnk_Xq3vB9kLm2Pz7RtY","object":"link","status":"canceled","to":"0599 ••• 456","network":"jawwal","purpose":"order","locale":"ar","delivery":"sms","reference":"#1042","return_url":null,"segments":1,"test":false,"created_at":"2026-11-19T10:00:00.000Z","expires_at":"2026-11-20T10:00:00.000Z","opened_at":null,"approved_at":null}}}}},"responses":{"200":{"description":"Received."}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"An API key from the dashboard: `otp_live_…` (real messages, uses credit) or `otp_test_…` (sandbox). The `X-API-Key` header is accepted too."}},"schemas":{"SendRequest":{"type":"object","properties":{"phone":{"description":"A Jawwal (059) or Ooredoo (056) mobile number, written any common way: 0599123456, 599123456, +970599123456, +972599123456, 00970599123456, with spaces or dashes, or in Arabic-Indic digits. It is always sent as +970.","examples":["0599123456","+970 59 912 3456"],"type":["string","number"]},"locale":{"type":"string","enum":["ar","en"],"description":"Language of the text message. Defaults to the account's setting (Arabic for new accounts)."},"purpose":{"type":"string","enum":["verify","login","signup","order","appointment"],"description":"Only changes the wording of the message (e.g. order: “Your order confirmation code is …”). Defaults to verify."}},"required":["phone"],"additionalProperties":{}},"CheckRequest":{"type":"object","properties":{"id":{"description":"The verification id from the send answer. Preferred.","type":"string"},"phone":{"description":"Instead of id: checks the latest code sent to this number with this key's mode.","examples":["0599123456","+970 59 912 3456"],"type":["string","number"]},"code":{"description":"What the customer typed. Spaces and Arabic-Indic digits are accepted.","examples":["4821"],"type":["string","number"]}},"required":["code"],"additionalProperties":{}},"Verification":{"type":"object","properties":{"id":{"type":"string","examples":["ver_9f2KxQe1Lm0aBcDe"]},"status":{"type":"string","enum":["pending","approved","expired","failed","canceled"],"description":"pending: waiting for the code. approved: the right code was checked. expired: not checked in time. failed: too many wrong tries, or the message couldn't be sent. canceled: replaced by a newer code to the same number."},"to":{"type":"string","description":"The number, partly hidden.","examples":["0599 ••• 456"]},"network":{"type":"string","enum":["jawwal","ooredoo"]},"purpose":{"type":"string","enum":["verify","login","signup","order","appointment"],"description":"Only changes the wording of the message (e.g. order: “Your order confirmation code is …”). Defaults to verify."},"locale":{"type":"string","enum":["ar","en"],"description":"Language of the text message. Defaults to the account's setting (Arabic for new accounts)."},"segments":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Text messages charged for this code (0 for test keys and for messages that couldn't be sent)."},"attempts":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Checks made so far."},"test":{"type":"boolean","description":"True when made with a test key (sandbox)."},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"expires_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"verified_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},{"type":"null"}]}},"required":["id","status","to","network","purpose","locale","segments","attempts","test","created_at","expires_at","verified_at"],"additionalProperties":false},"SendResponse":{"type":"object","properties":{"id":{"type":"string","examples":["ver_9f2KxQe1Lm0aBcDe"]},"status":{"type":"string","enum":["pending","approved","expired","failed","canceled"],"description":"pending: waiting for the code. approved: the right code was checked. expired: not checked in time. failed: too many wrong tries, or the message couldn't be sent. canceled: replaced by a newer code to the same number."},"to":{"type":"string","description":"The number, partly hidden.","examples":["0599 ••• 456"]},"network":{"type":"string","enum":["jawwal","ooredoo"]},"purpose":{"type":"string","enum":["verify","login","signup","order","appointment"],"description":"Only changes the wording of the message (e.g. order: “Your order confirmation code is …”). Defaults to verify."},"locale":{"type":"string","enum":["ar","en"],"description":"Language of the text message. Defaults to the account's setting (Arabic for new accounts)."},"segments":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Text messages charged for this code (0 for test keys and for messages that couldn't be sent)."},"attempts":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Checks made so far."},"test":{"type":"boolean","description":"True when made with a test key (sandbox)."},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"expires_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"verified_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},{"type":"null"}]},"test_code":{"description":"Test keys only: the code that would have been sent. Never present with a live key.","type":"string"}},"required":["id","status","to","network","purpose","locale","segments","attempts","test","created_at","expires_at","verified_at"],"additionalProperties":false},"CheckResponse":{"type":"object","properties":{"id":{"type":"string","examples":["ver_9f2KxQe1Lm0aBcDe"]},"status":{"type":"string","enum":["pending","approved","expired","failed","canceled"],"description":"pending: waiting for the code. approved: the right code was checked. expired: not checked in time. failed: too many wrong tries, or the message couldn't be sent. canceled: replaced by a newer code to the same number."},"to":{"type":"string","description":"The number, partly hidden.","examples":["0599 ••• 456"]},"network":{"type":"string","enum":["jawwal","ooredoo"]},"purpose":{"type":"string","enum":["verify","login","signup","order","appointment"],"description":"Only changes the wording of the message (e.g. order: “Your order confirmation code is …”). Defaults to verify."},"locale":{"type":"string","enum":["ar","en"],"description":"Language of the text message. Defaults to the account's setting (Arabic for new accounts)."},"segments":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Text messages charged for this code (0 for test keys and for messages that couldn't be sent)."},"attempts":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Checks made so far."},"test":{"type":"boolean","description":"True when made with a test key (sandbox)."},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"expires_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"verified_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},{"type":"null"}]},"valid":{"type":"boolean","description":"True only on the check that approved the code. Rely on this field."},"attempts_left":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["id","status","to","network","purpose","locale","segments","attempts","test","created_at","expires_at","verified_at","valid","attempts_left"],"additionalProperties":false},"Balance":{"type":"object","properties":{"credits":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Text messages left."},"status":{"type":"string","enum":["pending","active","suspended"],"description":"pending: waiting for approval (test keys only). active: live keys work."},"mode":{"type":"string","enum":["live","test"],"description":"The mode of the key used."}},"required":["credits","status","mode"],"additionalProperties":false},"Usage":{"type":"object","properties":{"mode":{"type":"string","enum":["live","test"],"description":"Usage of the key's own mode."},"timezone":{"type":"string","const":"Asia/Hebron"},"today":{"type":"object","properties":{"date":{"type":"string"},"sent":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Codes handed to the gateway (or made, with a test key)."},"approved":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Codes the customer typed correctly."},"failed":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Messages the gateway refused (not charged)."},"segments":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Text messages charged."}},"required":["date","sent","approved","failed","segments"],"additionalProperties":false},"month":{"type":"object","properties":{"month":{"type":"string","examples":["2026-11"]},"sent":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Codes handed to the gateway (or made, with a test key)."},"approved":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Codes the customer typed correctly."},"failed":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Messages the gateway refused (not charged)."},"segments":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Text messages charged."}},"required":["month","sent","approved","failed","segments"],"additionalProperties":false},"days":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","examples":["2026-11-19"]},"sent":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Codes handed to the gateway (or made, with a test key)."},"approved":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Codes the customer typed correctly."},"failed":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Messages the gateway refused (not charged)."},"segments":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Text messages charged."}},"required":["date","sent","approved","failed","segments"],"additionalProperties":false},"description":"The last 30 days with any codes, newest first."}},"required":["mode","timezone","today","month","days"],"additionalProperties":false},"Limits":{"type":"object","properties":{"mode":{"type":"string","enum":["live","test"]},"scopes":{"type":"array","items":{"type":"string","enum":["send","check","read"]},"description":"What this key may do."},"credits":{"type":"integer","minimum":0,"maximum":9007199254740991},"status":{"type":"string","enum":["pending","active","suspended"]},"code":{"type":"object","properties":{"length":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"valid_minutes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"max_attempts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["length","valid_minutes","max_attempts"],"additionalProperties":false},"rate_limits":{"type":"object","properties":{"per_phone":{"type":"array","items":{"type":"object","properties":{"seconds":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"max":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["seconds","max"],"additionalProperties":false}},"per_account_per_minute":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["per_phone","per_account_per_minute"],"additionalProperties":false},"spending":{"type":"object","properties":{"daily":{"type":"object","properties":{"limit":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}],"description":"The business's own daily limit."},"owner_cap":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"The daily ceiling set by OTP.ps (protection against SMS pumping)."},"effective":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"The lower of the two."},"used":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["limit","owner_cap","effective","used"],"additionalProperties":false},"monthly":{"type":"object","properties":{"limit":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}],"description":"Messages; null means no limit of this kind."},"used":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["limit","used"],"additionalProperties":false},"key_daily":{"anyOf":[{"type":"object","properties":{"limit":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}],"description":"Messages; null means no limit of this kind."},"used":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["limit","used"],"additionalProperties":false},{"type":"null"}],"description":"This key's own daily limit."},"resets":{"type":"object","properties":{"day_in_seconds":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"month_in_seconds":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["day_in_seconds","month_in_seconds"],"additionalProperties":false}},"required":["daily","monthly","key_daily","resets"],"additionalProperties":false,"description":"Live messages only, counted in Palestine time. Test keys spend nothing."}},"required":["mode","scopes","credits","status","code","rate_limits","spending"],"additionalProperties":false},"Link":{"type":"object","properties":{"id":{"type":"string","examples":["lnk_Xq3vB9kLm2Pz7RtY"]},"object":{"type":"string","const":"link"},"status":{"type":"string","enum":["pending","approved","expired","canceled"],"description":"pending: waiting for the customer. approved: confirmed (link.approved was sent). expired: not confirmed in time. canceled: canceled by the business."},"to":{"type":"string","examples":["0599 ••• 456"]},"network":{"type":"string","enum":["jawwal","ooredoo"]},"purpose":{"type":"string","enum":["verify","login","signup","order","appointment"],"description":"Only changes the wording of the message (e.g. order: “Your order confirmation code is …”). Defaults to verify."},"locale":{"type":"string","enum":["ar","en"],"description":"Language of the text message. Defaults to the account's setting (Arabic for new accounts)."},"delivery":{"type":"string","enum":["sms","none"],"description":"sms: OTP.ps texted the link; the customer presses Confirm. none: the business shares the link; the page texts a code."},"reference":{"type":"string","description":"The business's own id (e.g. an order number), as given."},"return_url":{"description":"Where the page sends the customer after confirming, with otp_link and otp_status added.","type":["string","null"]},"segments":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Text messages charged for the link itself (delivery sms). Codes sent from the page are charged as verifications."},"test":{"type":"boolean"},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"expires_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"opened_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},{"type":"null"}]},"approved_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},{"type":"null"}]}},"required":["id","object","status","to","network","purpose","locale","delivery","reference","return_url","segments","test","created_at","expires_at","opened_at","approved_at"],"additionalProperties":false},"LinkCreated":{"type":"object","properties":{"id":{"type":"string","examples":["lnk_Xq3vB9kLm2Pz7RtY"]},"object":{"type":"string","const":"link"},"status":{"type":"string","enum":["pending","approved","expired","canceled"],"description":"pending: waiting for the customer. approved: confirmed (link.approved was sent). expired: not confirmed in time. canceled: canceled by the business."},"to":{"type":"string","examples":["0599 ••• 456"]},"network":{"type":"string","enum":["jawwal","ooredoo"]},"purpose":{"type":"string","enum":["verify","login","signup","order","appointment"],"description":"Only changes the wording of the message (e.g. order: “Your order confirmation code is …”). Defaults to verify."},"locale":{"type":"string","enum":["ar","en"],"description":"Language of the text message. Defaults to the account's setting (Arabic for new accounts)."},"delivery":{"type":"string","enum":["sms","none"],"description":"sms: OTP.ps texted the link; the customer presses Confirm. none: the business shares the link; the page texts a code."},"reference":{"type":"string","description":"The business's own id (e.g. an order number), as given."},"return_url":{"description":"Where the page sends the customer after confirming, with otp_link and otp_status added.","type":["string","null"]},"segments":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Text messages charged for the link itself (delivery sms). Codes sent from the page are charged as verifications."},"test":{"type":"boolean"},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"expires_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"opened_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},{"type":"null"}]},"approved_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},{"type":"null"}]},"url":{"description":"The link to give the customer. Returned only when the link is made (not on an idempotent replay); OTP.ps keeps only a hash of it.","type":"string"}},"required":["id","object","status","to","network","purpose","locale","delivery","reference","return_url","segments","test","created_at","expires_at","opened_at","approved_at"],"additionalProperties":false},"LinkRequest":{"type":"object","properties":{"phone":{"description":"A Jawwal (059) or Ooredoo (056) mobile number, written any common way: 0599123456, 599123456, +970599123456, +972599123456, 00970599123456, with spaces or dashes, or in Arabic-Indic digits. It is always sent as +970.","examples":["0599123456","+970 59 912 3456"],"type":["string","number"]},"purpose":{"type":"string","enum":["verify","login","signup","order","appointment"],"description":"Only changes the wording of the message (e.g. order: “Your order confirmation code is …”). Defaults to verify."},"locale":{"type":"string","enum":["ar","en"],"description":"Language of the text message. Defaults to the account's setting (Arabic for new accounts)."},"delivery":{"description":"Default \"sms\".","type":"string","enum":["sms","none"]},"reference":{"type":"string","maxLength":100},"return_url":{"description":"https address (optional).","type":"string"},"expires_in_minutes":{"description":"Default 1440 (24 hours).","type":"integer","minimum":5,"maximum":4320}},"required":["phone"],"additionalProperties":{}},"LinkList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Link"}},"has_more":{"type":"boolean","description":"Ask again with before=<the last id> for older links."}},"required":["data","has_more"],"additionalProperties":false},"Webhook":{"type":"object","properties":{"id":{"type":"string","examples":["whe_Ab12Cd34Ef56"]},"object":{"type":"string","const":"webhook"},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string","enum":["link.approved","link.expired","link.canceled"]}},"test":{"type":"boolean","description":"Receives events of test links (made with a test key) or of live links."},"description":{"type":"string"},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","object","url","events","test","description","created_at"],"additionalProperties":false},"WebhookCreated":{"type":"object","properties":{"id":{"type":"string","examples":["whe_Ab12Cd34Ef56"]},"object":{"type":"string","const":"webhook"},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string","enum":["link.approved","link.expired","link.canceled"]}},"test":{"type":"boolean","description":"Receives events of test links (made with a test key) or of live links."},"description":{"type":"string"},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"secret":{"type":"string","description":"The signing secret (whsec_…). Shown once: store it."}},"required":["id","object","url","events","test","description","created_at","secret"],"additionalProperties":false},"WebhookList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Webhook"}}},"required":["data"],"additionalProperties":false},"WebhookRequest":{"type":"object","properties":{"url":{"type":"string","description":"Public https address that will receive the events."},"events":{"description":"Default: all.","type":"array","items":{"type":"string","enum":["link.approved","link.expired","link.canceled"]}},"description":{"type":"string","maxLength":100}},"required":["url"],"additionalProperties":{}},"WebhookEvent":{"type":"object","properties":{"id":{"type":"string","examples":["evt_9aB3cD4eF5gH6iJ7"]},"type":{"type":"string","enum":["link.approved","link.expired","link.canceled","ping"]},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"test":{"type":"boolean"},"data":{"anyOf":[{"$ref":"#/components/schemas/Link"},{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}]}},"required":["id","type","created_at","test","data"],"additionalProperties":false},"Error":{"type":"object","properties":{"error":{"type":"string","enum":["unauthorized","insufficient_scope","invalid_request","invalid_phone","unsupported_network","idempotency_conflict","invalid_state","account_pending","account_suspended","insufficient_balance","rate_limited","spending_limit_reached","sms_failed","not_found"]},"message":{"type":"string","description":"A human-readable explanation, in English."},"retry_after":{"description":"rate_limited only: seconds to wait. Also sent as the Retry-After header.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["error","message"],"additionalProperties":false}}},"x-otp-ps":{"purposes":["verify","login","signup","order","appointment"],"networks":[{"name":"jawwal","prefix":"059"},{"name":"ooredoo","prefix":"056"}],"sandboxNumbers":[{"phone":"0599000001","e164":"+970599000001","network":"jawwal","outcome":"fixed_code","description":"Sent successfully. The code is always 1234 (or 123456 for 6-digit codes)."},{"phone":"0569000001","e164":"+970569000001","network":"ooredoo","outcome":"fixed_code","description":"Ooredoo number, sent successfully. The code is always 1234 (or 123456)."},{"phone":"0599000002","e164":"+970599000002","network":"jawwal","outcome":"sms_failed","description":"The gateway refuses the message: 502 sms_failed. Nothing is charged."},{"phone":"0599000003","e164":"+970599000003","network":"jawwal","outcome":"insufficient_balance","description":"Answers 402 insufficient_balance, as if the account had no credit left."},{"phone":"0599000004","e164":"+970599000004","network":"jawwal","outcome":"rate_limited","description":"Answers 429 rate_limited with retry_after 30, as if the number had just received a code."},{"phone":"0599000005","e164":"+970599000005","network":"jawwal","outcome":"expires_immediately","description":"Sent successfully with code 1234 (or 123456), but the code has already expired: checking it answers status expired."}]}}