Loading...
Create a new OTP verification challenge for a receiver. SMX generates the code, resolves the project template, enforces cooldown and rate rules, and routes delivery through the linked Android device.
Create one OTP challenge for one receiver and return the verificationId your app will use in the verify step.
| Header | Required | Description |
|---|---|---|
| X-SMX-API-Key | Yes | Project API key for the public route. |
| Content-Type: application/json | Yes | Required for the JSON request body. |
| Idempotency-Key | Optional | Returns the existing queued or processed OTP if the same key is retried. |
| Field | Type | Required | Description |
|---|---|---|---|
| receiver | string | Yes | Target phone number. The backend trims the value and hashes it per project. |
| locale | string | No | Template locale. SMX falls back to en when the requested locale is unavailable. |
locale is not active or has no template configured on your Templates page, SMX automatically falls back to the default English (en) template.1{2 "success": true,3 "data": {4 "messageId": "msg_01hy78abc...",5 "verificationId": "v_992kjh12..."6 }7}| Status | When | Codes |
|---|---|---|
| 200 | OTP challenge was created, or an idempotent replay returned the existing result. | — |
| 400 | Cooldown, validation, or delivery prerequisites blocked the send. | OTP_RATE_LIMITED, DEVICE_NOT_LINKED, VALIDATION_FAILED |
| 401 | The API key header was missing or invalid. | API_KEY_MISSING, API_KEY_INVALID |
| 403 | The API key belongs to a project that is not active. | PROJECT_DISABLED |
400 Bad Request status with precise wait-time variables in the details object.1{2 "success": false,3 "origin": "api",4 "codes": ["OTP_RATE_LIMITED"],5 "message": "Please wait 24 seconds before requesting another OTP",6 "details": {7 "type": "COOLDOWN",8 "remainingSeconds": 24,9 "waitTimeSeconds": 3010 }11}