API docs
API reference
A compact index of the OTPRelay API - the base URL, how to authenticate, every endpoint, the core objects, and the conventions that apply across the platform.
OTPRelay is a small, focused API: send a one-time passcode, check it, and read the result. This page indexes the surface. Each endpoint links to its own page with full request and response bodies. New here? Start with the Quickstart.
Base URL
All requests go to a single, path-versioned base URL. Requests and responses are JSON, and every field is snake_case.
Authentication
Authenticate with a secret API key passed as a bearer token in the Authorization header. Use sk_live_… against production and sk_test_… against the sandbox. Keys are account-scoped - see Authentication for key management and the test environment.
Endpoints
The API spans two resources on one delivery layer. The message resource is the Send API - deliver a code you generated and verify it yourself. The verificationresource is the Verify API - OTPRelay generates, sends, and checks the code for you. There is no webhook registration endpoint: you receive an object's events by passing a webhook_url on the send request - see Webhooks.
| Method | Endpoint | Description |
|---|---|---|
| POST | /v1/messages | Send a code |
| GET | /v1/messages/{id} | Retrieve a message |
| POST | /v1/verifications | Send a verification |
| POST | /v1/verifications/check | Check a verification |
| GET | /v1/verifications/{id} | Retrieve a verification |
| POST | /v1/verifications/{id}/cancel | Cancel a verification |
| GET | /v1/verifications | List verifications |
Objects
The Send API returns a message (msg_…) - a code you generated, delivered from the shared OTPRelay sender. The Verify API returns a verification (ver_…), whose attempts[] array records each SMS send as an attempt (att_…). Field-by-field definitions and the full status lists live on Send a code and The verification object.
Conventions
The same rules apply across every endpoint, so you can learn them once.
| Convention | Detail |
|---|---|
Idempotency-Key | Optional header on POST requests. Reusing the same key safely retries a create without sending a duplicate OTP. |
| Versioning | The API is path-versioned - every route is prefixed with /v1. |
| ID prefixes | IDs are typed by prefix: msg_ (message), ver_ (verification), att_ (attempt), evt_ (event). |
| Phone numbers | Always E.164, e.g. +966512345678. |
| Timestamps | ISO 8601 in UTC, e.g. 2026-06-16T10:00:00Z. |
| Errors | Failures return a structured body with error.type, code and message. See Errors. |
| Pagination | Cursor-based pagination for GET /v1/verifications is planned but not yet finalized. |
This page is an index