# 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.

```text
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`):

```bash
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.approved` arrives within seconds. See [Webhooks](/docs/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

| 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](/docs/security#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](/docs/sandbox)).
