Verification links
Confirm a number without building any screen: OTP.ps hosts the page, texts the link or a code, and tells you when the customer confirms.
A verification link is a page OTP.ps hosts where your customer confirms the number you chose. Use it when you have no screen of your own to ask for a code: Shopify Flow, Zapier, Make, n8n, a WooCommerce block checkout, an order taken by phone, a thank-you page.
your system ──POST /api/v1/verify/links──▶ OTP.ps ──text message──▶ customer
│ opens the link, confirms
your system ◀── link.approved (webhook) ────────── OTP.ps ◀───────────┘Two ways to confirm
delivery | What happens | Messages charged |
|---|---|---|
sms (default) | OTP.ps texts the link to the number. The customer opens it and presses Confirm. Receiving the link proves they have the phone | One, when the link is made |
none | You share the link yourself (redirect after checkout, email, chat). The page texts a code to the number and the customer types it. At most 3 codes per link | One per code the customer asks for |
The text message for sms looks like this (one message, with your business's name):
متجر نور: لتأكيد طلبك افتح: https://otp.ps/v/Ab3dE5gH7jK9
The page shows your business's name, the masked number and nothing else: no OTP.ps menus, no sign-in. It speaks the link's locale.
Create a link
POST /api/v1/verify/links (scope send):
curl https://otp.ps/api/v1/verify/links \
-H "Authorization: Bearer $OTP_PS_API_KEY" -H "Content-Type: application/json" \
-H "Idempotency-Key: order-1042-link" \
-d '{"phone": "0599123456", "purpose": "order", "reference": "#1042", "delivery": "sms"}'| Field | Description | |
|---|---|---|
phone | required | A Jawwal or Ooredoo number. The customer can't change it on the page. |
purpose | optional | verify, login, signup, order, appointment. Changes the wording ("confirm your order"). |
locale | optional | ar or en. Defaults to your account's setting. |
delivery | optional | sms (default) or none, see above. |
reference | optional | Your own id, up to 100 characters, e.g. an order number. Comes back in every answer and webhook. |
return_url | optional | An https address. After confirming, the page sends the customer there with otp_link=<id>&otp_status=approved added. |
expires_in_minutes | optional | 5 to 4320 (3 days). Default 1440 (24 hours). |
The answer (201) is the link, plus url, the address to give the customer. url is only in this answer: OTP.ps keeps only a hash of it. An idempotent replay returns the link without url.
Know when it's confirmed
- Webhook (recommended):
link.approvedarrives within seconds. See Webhooks. - Polling:
GET /api/v1/verify/links/{id}, orGET /api/v1/verify/links?status=approvedfor the latest confirmed links. - Never trust
otp_status=approvedin the return address on its own: anyone can type it. Check the link's status with the API or wait for the webhook.
Statuses
| Status | Meaning | Webhook |
|---|---|---|
pending | Waiting for the customer | |
approved | Confirmed | link.approved |
expired | Not confirmed in time | link.expired |
canceled | You canceled it (POST /api/v1/verify/links/{id}/cancel) | link.canceled |
Limits and safety
- Everything that applies to codes applies to links: the per-number limits, your spending limits, your balance, test and live separation, idempotency.
- The link's secret part is 12 random characters. Pages can't be shown inside other sites, aren't indexed by search engines, and don't pass their address to other sites.
- Confirming needs a button press: a link preview or a virus scanner that opens the link doesn't confirm it.
- With a test key, no message is sent, the answer still has
url, and a code page shows the code (1234on sandbox numbers).