Getting started

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

deliveryWhat happensMessages 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 phoneOne, when the link is made
noneYou 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 linkOne 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.

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"}'
FieldDescription
phonerequiredA Jawwal or Ooredoo number. The customer can't change it on the page.
purposeoptionalverify, login, signup, order, appointment. Changes the wording ("confirm your order").
localeoptionalar or en. Defaults to your account's setting.
deliveryoptionalsms (default) or none, see above.
referenceoptionalYour own id, up to 100 characters, e.g. an order number. Comes back in every answer and webhook.
return_urloptionalAn https address. After confirming, the page sends the customer there with otp_link=<id>&otp_status=approved added.
expires_in_minutesoptional5 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.approved arrives within seconds. See Webhooks.
  • Polling: GET /api/v1/verify/links/{id}, or GET /api/v1/verify/links?status=approved for the latest confirmed links.
  • Never trust otp_status=approved in the return address on its own: anyone can type it. Check the link's status with the API or wait for the webhook.

Statuses

StatusMeaningWebhook
pendingWaiting for the customer
approvedConfirmedlink.approved
expiredNot confirmed in timelink.expired
canceledYou 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 (1234 on sandbox numbers).

View as Markdown