{ "openapi": "3.0.0", "servers": [ { "url": "https://api.contiguity.com/otp" } ], "info": { "version": "v2025.12.10", "title": "OTP API" }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" } }, "schemas": {}, "parameters": {} }, "paths": { "/verify": { "post": { "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "otp_id": { "type": "string", "description": "The OTP ID you received when sending the OTP", "example": "otp_1234567890" }, "otp": { "type": "string", "description": "The OTP inputted by the user", "example": "123456" } }, "required": [ "otp_id", "otp" ] } } } }, "responses": { "200": { "description": "Verify an OTP", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "req_xxxxxxxxxxxxxxxx" }, "timestamp": { "type": "number", "example": 1765397289220 }, "api_version": { "type": "string", "example": "v2025.12.10" }, "object": { "type": "string", "example": "response" }, "data": { "type": "object", "properties": { "verified": { "type": "boolean", "description": "Whether the OTP was verified or not", "example": true } }, "required": [ "verified" ] } }, "required": [ "id", "timestamp", "api_version", "object", "data" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "err_xxxxxxxxxxxxxxxx" }, "timestamp": { "type": "number", "example": 1765397289220 }, "api_version": { "type": "string", "example": "v2025.12.10" }, "object": { "type": "string", "example": "error" }, "data": { "type": "object", "properties": { "error": { "type": "string", "example": "Bad Request" }, "status": { "type": "number", "example": 400 } }, "required": [ "error", "status" ] } }, "required": [ "id", "timestamp", "api_version", "object", "data" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "err_xxxxxxxxxxxxxxxx" }, "timestamp": { "type": "number", "example": 1765397289220 }, "api_version": { "type": "string", "example": "v2025.12.10" }, "object": { "type": "string", "example": "error" }, "data": { "type": "object", "properties": { "error": { "type": "string", "example": "Unauthorized" }, "status": { "type": "number", "example": 401 } }, "required": [ "error", "status" ] } }, "required": [ "id", "timestamp", "api_version", "object", "data" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "err_xxxxxxxxxxxxxxxx" }, "timestamp": { "type": "number", "example": 1765397289220 }, "api_version": { "type": "string", "example": "v2025.12.10" }, "object": { "type": "string", "example": "error" }, "data": { "type": "object", "properties": { "error": { "type": "string", "example": "Forbidden" }, "status": { "type": "number", "example": 403 } }, "required": [ "error", "status" ] } }, "required": [ "id", "timestamp", "api_version", "object", "data" ] } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "err_xxxxxxxxxxxxxxxx" }, "timestamp": { "type": "number", "example": 1765397289220 }, "api_version": { "type": "string", "example": "v2025.12.10" }, "object": { "type": "string", "example": "error" }, "data": { "type": "object", "properties": { "error": { "type": "string", "example": "Internal Server Error" }, "status": { "type": "number", "example": 500 } }, "required": [ "error", "status" ] } }, "required": [ "id", "timestamp", "api_version", "object", "data" ] } } } } } } }, "/new": { "post": { "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "to": { "type": "string", "description": "Recipient's phone number", "example": "+1234567890" }, "language": { "type": "string", "description": "Language of the OTP message", "example": "en" }, "name": { "type": "string", "description": "Your app's name (customizes message to 'Your [name] code is...')", "example": "Contiguity" } }, "required": [ "to", "language", "name" ] } } } }, "responses": { "200": { "description": "Send a new OTP", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "req_xxxxxxxxxxxxxxxx" }, "timestamp": { "type": "number", "example": 1765397289220 }, "api_version": { "type": "string", "example": "v2025.12.10" }, "object": { "type": "string", "example": "response" }, "data": { "type": "object", "properties": { "otp_id": { "type": "string", "description": "The OTP's ID. Use it to refer to this verification in the future, such as when verifying the OTP or resending it.", "example": "otp_1234567890" } }, "required": [ "otp_id" ] } }, "required": [ "id", "timestamp", "api_version", "object", "data" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "err_xxxxxxxxxxxxxxxx" }, "timestamp": { "type": "number", "example": 1765397289220 }, "api_version": { "type": "string", "example": "v2025.12.10" }, "object": { "type": "string", "example": "error" }, "data": { "type": "object", "properties": { "error": { "type": "string", "example": "Bad Request" }, "status": { "type": "number", "example": 400 } }, "required": [ "error", "status" ] } }, "required": [ "id", "timestamp", "api_version", "object", "data" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "err_xxxxxxxxxxxxxxxx" }, "timestamp": { "type": "number", "example": 1765397289220 }, "api_version": { "type": "string", "example": "v2025.12.10" }, "object": { "type": "string", "example": "error" }, "data": { "type": "object", "properties": { "error": { "type": "string", "example": "Unauthorized" }, "status": { "type": "number", "example": 401 } }, "required": [ "error", "status" ] } }, "required": [ "id", "timestamp", "api_version", "object", "data" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "err_xxxxxxxxxxxxxxxx" }, "timestamp": { "type": "number", "example": 1765397289220 }, "api_version": { "type": "string", "example": "v2025.12.10" }, "object": { "type": "string", "example": "error" }, "data": { "type": "object", "properties": { "error": { "type": "string", "example": "Forbidden" }, "status": { "type": "number", "example": 403 } }, "required": [ "error", "status" ] } }, "required": [ "id", "timestamp", "api_version", "object", "data" ] } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "err_xxxxxxxxxxxxxxxx" }, "timestamp": { "type": "number", "example": 1765397289220 }, "api_version": { "type": "string", "example": "v2025.12.10" }, "object": { "type": "string", "example": "error" }, "data": { "type": "object", "properties": { "error": { "type": "string", "example": "Internal Server Error" }, "status": { "type": "number", "example": 500 } }, "required": [ "error", "status" ] } }, "required": [ "id", "timestamp", "api_version", "object", "data" ] } } } } } } }, "/resend": { "post": { "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "otp_id": { "type": "string", "description": "The OTP ID you received when sending the OTP", "example": "otp_1234567890" } }, "required": [ "otp_id" ] } } } }, "responses": { "200": { "description": "Resend an OTP", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "req_xxxxxxxxxxxxxxxx" }, "timestamp": { "type": "number", "example": 1765397289220 }, "api_version": { "type": "string", "example": "v2025.12.10" }, "object": { "type": "string", "example": "response" }, "data": { "type": "object", "properties": { "resent": { "type": "boolean", "description": "Whether the OTP was resent", "example": true } }, "required": [ "resent" ] } }, "required": [ "id", "timestamp", "api_version", "object", "data" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "err_xxxxxxxxxxxxxxxx" }, "timestamp": { "type": "number", "example": 1765397289220 }, "api_version": { "type": "string", "example": "v2025.12.10" }, "object": { "type": "string", "example": "error" }, "data": { "type": "object", "properties": { "error": { "type": "string", "example": "Bad Request" }, "status": { "type": "number", "example": 400 } }, "required": [ "error", "status" ] } }, "required": [ "id", "timestamp", "api_version", "object", "data" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "err_xxxxxxxxxxxxxxxx" }, "timestamp": { "type": "number", "example": 1765397289220 }, "api_version": { "type": "string", "example": "v2025.12.10" }, "object": { "type": "string", "example": "error" }, "data": { "type": "object", "properties": { "error": { "type": "string", "example": "Unauthorized" }, "status": { "type": "number", "example": 401 } }, "required": [ "error", "status" ] } }, "required": [ "id", "timestamp", "api_version", "object", "data" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "err_xxxxxxxxxxxxxxxx" }, "timestamp": { "type": "number", "example": 1765397289220 }, "api_version": { "type": "string", "example": "v2025.12.10" }, "object": { "type": "string", "example": "error" }, "data": { "type": "object", "properties": { "error": { "type": "string", "example": "Forbidden" }, "status": { "type": "number", "example": 403 } }, "required": [ "error", "status" ] } }, "required": [ "id", "timestamp", "api_version", "object", "data" ] } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "err_xxxxxxxxxxxxxxxx" }, "timestamp": { "type": "number", "example": 1765397289220 }, "api_version": { "type": "string", "example": "v2025.12.10" }, "object": { "type": "string", "example": "error" }, "data": { "type": "object", "properties": { "error": { "type": "string", "example": "Internal Server Error" }, "status": { "type": "number", "example": 500 } }, "required": [ "error", "status" ] } }, "required": [ "id", "timestamp", "api_version", "object", "data" ] } } } } } } }, "/reverse/cancel/{otp_id}": { "post": { "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Reverse OTP session ID", "example": "r_otp_123456" }, "required": true, "description": "Reverse OTP session ID", "name": "otp_id", "in": "path" } ], "responses": { "200": { "description": "Cancel an active Reverse OTP session", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "req_xxxxxxxxxxxxxxxx" }, "timestamp": { "type": "number", "example": 1765397289220 }, "api_version": { "type": "string", "example": "v2025.12.10" }, "object": { "type": "string", "example": "response" }, "data": { "type": "object", "properties": { "otp_id": { "type": "string", "description": "Reverse OTP session ID", "example": "r_otp_123456" }, "status": { "type": "string", "enum": [ "cancelled" ], "description": "New status of the session" } }, "required": [ "otp_id", "status" ] } }, "required": [ "id", "timestamp", "api_version", "object", "data" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "err_xxxxxxxxxxxxxxxx" }, "timestamp": { "type": "number", "example": 1765397289220 }, "api_version": { "type": "string", "example": "v2025.12.10" }, "object": { "type": "string", "example": "error" }, "data": { "type": "object", "properties": { "error": { "type": "string", "example": "Bad Request" }, "status": { "type": "number", "example": 400 } }, "required": [ "error", "status" ] } }, "required": [ "id", "timestamp", "api_version", "object", "data" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "err_xxxxxxxxxxxxxxxx" }, "timestamp": { "type": "number", "example": 1765397289220 }, "api_version": { "type": "string", "example": "v2025.12.10" }, "object": { "type": "string", "example": "error" }, "data": { "type": "object", "properties": { "error": { "type": "string", "example": "Unauthorized" }, "status": { "type": "number", "example": 401 } }, "required": [ "error", "status" ] } }, "required": [ "id", "timestamp", "api_version", "object", "data" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "err_xxxxxxxxxxxxxxxx" }, "timestamp": { "type": "number", "example": 1765397289220 }, "api_version": { "type": "string", "example": "v2025.12.10" }, "object": { "type": "string", "example": "error" }, "data": { "type": "object", "properties": { "error": { "type": "string", "example": "Forbidden" }, "status": { "type": "number", "example": 403 } }, "required": [ "error", "status" ] } }, "required": [ "id", "timestamp", "api_version", "object", "data" ] } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "err_xxxxxxxxxxxxxxxx" }, "timestamp": { "type": "number", "example": 1765397289220 }, "api_version": { "type": "string", "example": "v2025.12.10" }, "object": { "type": "string", "example": "error" }, "data": { "type": "object", "properties": { "error": { "type": "string", "example": "Internal Server Error" }, "status": { "type": "number", "example": 500 } }, "required": [ "error", "status" ] } }, "required": [ "id", "timestamp", "api_version", "object", "data" ] } } } } } } }, "/reverse/verify/{otp_id}": { "get": { "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Reverse OTP session ID", "example": "r_otp_123456" }, "required": true, "description": "Reverse OTP session ID", "name": "otp_id", "in": "path" } ], "responses": { "200": { "description": "Poll the status of a Reverse OTP session", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "req_xxxxxxxxxxxxxxxx" }, "timestamp": { "type": "number", "example": 1765397289220 }, "api_version": { "type": "string", "example": "v2025.12.10" }, "object": { "type": "string", "example": "response" }, "data": { "type": "object", "properties": { "otp_id": { "type": "string", "description": "Reverse OTP session ID", "example": "r_otp_123456" }, "status": { "type": "string", "enum": [ "pending", "verified", "cancelled", "expired" ], "description": "Current status of the session" }, "expires_at": { "type": "string", "description": "Expiration time in ISO format", "example": "2025-02-01T12:00:00.000Z" } }, "required": [ "otp_id", "status", "expires_at" ] } }, "required": [ "id", "timestamp", "api_version", "object", "data" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "err_xxxxxxxxxxxxxxxx" }, "timestamp": { "type": "number", "example": 1765397289220 }, "api_version": { "type": "string", "example": "v2025.12.10" }, "object": { "type": "string", "example": "error" }, "data": { "type": "object", "properties": { "error": { "type": "string", "example": "Bad Request" }, "status": { "type": "number", "example": 400 } }, "required": [ "error", "status" ] } }, "required": [ "id", "timestamp", "api_version", "object", "data" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "err_xxxxxxxxxxxxxxxx" }, "timestamp": { "type": "number", "example": 1765397289220 }, "api_version": { "type": "string", "example": "v2025.12.10" }, "object": { "type": "string", "example": "error" }, "data": { "type": "object", "properties": { "error": { "type": "string", "example": "Unauthorized" }, "status": { "type": "number", "example": 401 } }, "required": [ "error", "status" ] } }, "required": [ "id", "timestamp", "api_version", "object", "data" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "err_xxxxxxxxxxxxxxxx" }, "timestamp": { "type": "number", "example": 1765397289220 }, "api_version": { "type": "string", "example": "v2025.12.10" }, "object": { "type": "string", "example": "error" }, "data": { "type": "object", "properties": { "error": { "type": "string", "example": "Forbidden" }, "status": { "type": "number", "example": 403 } }, "required": [ "error", "status" ] } }, "required": [ "id", "timestamp", "api_version", "object", "data" ] } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "err_xxxxxxxxxxxxxxxx" }, "timestamp": { "type": "number", "example": 1765397289220 }, "api_version": { "type": "string", "example": "v2025.12.10" }, "object": { "type": "string", "example": "error" }, "data": { "type": "object", "properties": { "error": { "type": "string", "example": "Internal Server Error" }, "status": { "type": "number", "example": 500 } }, "required": [ "error", "status" ] } }, "required": [ "id", "timestamp", "api_version", "object", "data" ] } } } } } } }, "/reverse/initiate": { "post": { "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "type": "string", "description": "Expected sender phone number. Must be in E.164 format.", "example": "+15551234567" }, "factor": { "type": "string", "maxLength": 16, "description": "Code or phrase the user will send. Defaults to a random 4-digit code if not provided.", "example": "1234" }, "to": { "type": "string", "description": "Phone number to text. If you lease a number from Contiguity, you can enter it here. Defaults to a random Contiguity-owned number.", "example": "+16465550123" }, "language": { "type": "string", "default": "en", "description": "Language code for UI strings", "example": "en" }, "success_url": { "type": "string", "format": "uri", "description": "Webhook URL to post successful verification. By default, Contiguity will use your existing webhook preferences.", "example": "https://example.com/webhooks/otp/success" } }, "required": [ "number" ] } } } }, "responses": { "200": { "description": "Start a Reverse OTP verification session", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "req_xxxxxxxxxxxxxxxx" }, "timestamp": { "type": "number", "example": 1765397289220 }, "api_version": { "type": "string", "example": "v2025.12.10" }, "object": { "type": "string", "example": "response" }, "data": { "type": "object", "properties": { "otp_id": { "type": "string", "description": "Reverse OTP session ID", "example": "r_otp_123456" }, "number": { "type": "string", "description": "Sender number being verified", "example": "+15551234567" }, "factor": { "type": "string", "description": "Code or phrase to send", "example": "1234" }, "to": { "type": "string", "description": "Number to message", "example": "+16465550123" }, "expires_at": { "type": "string", "description": "Expiration time in ISO format", "example": "2025-02-01T12:00:00.000Z" }, "ui": { "type": "object", "properties": { "text": { "type": "string", "description": "Localized instruction to display", "example": "Text 1234 to +1 (646) 555-0123 to verify your phone number." }, "qr_code": { "type": "string", "description": "QR code payload – use your favorite QR code generation library to encode this URL", "example": "sms:+16465550123?body=1234" } }, "required": [ "text", "qr_code" ] }, "success_url": { "type": "string", "nullable": true, "description": "Webhook URL used to notify your app when Contiguity verifies the user's phone number", "example": "https://example.com/webhooks/otp/success" } }, "required": [ "otp_id", "number", "factor", "to", "expires_at", "ui", "success_url" ] } }, "required": [ "id", "timestamp", "api_version", "object", "data" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "err_xxxxxxxxxxxxxxxx" }, "timestamp": { "type": "number", "example": 1765397289220 }, "api_version": { "type": "string", "example": "v2025.12.10" }, "object": { "type": "string", "example": "error" }, "data": { "type": "object", "properties": { "error": { "type": "string", "example": "Bad Request" }, "status": { "type": "number", "example": 400 } }, "required": [ "error", "status" ] } }, "required": [ "id", "timestamp", "api_version", "object", "data" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "err_xxxxxxxxxxxxxxxx" }, "timestamp": { "type": "number", "example": 1765397289220 }, "api_version": { "type": "string", "example": "v2025.12.10" }, "object": { "type": "string", "example": "error" }, "data": { "type": "object", "properties": { "error": { "type": "string", "example": "Unauthorized" }, "status": { "type": "number", "example": 401 } }, "required": [ "error", "status" ] } }, "required": [ "id", "timestamp", "api_version", "object", "data" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "err_xxxxxxxxxxxxxxxx" }, "timestamp": { "type": "number", "example": 1765397289220 }, "api_version": { "type": "string", "example": "v2025.12.10" }, "object": { "type": "string", "example": "error" }, "data": { "type": "object", "properties": { "error": { "type": "string", "example": "Forbidden" }, "status": { "type": "number", "example": 403 } }, "required": [ "error", "status" ] } }, "required": [ "id", "timestamp", "api_version", "object", "data" ] } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "err_xxxxxxxxxxxxxxxx" }, "timestamp": { "type": "number", "example": 1765397289220 }, "api_version": { "type": "string", "example": "v2025.12.10" }, "object": { "type": "string", "example": "error" }, "data": { "type": "object", "properties": { "error": { "type": "string", "example": "Internal Server Error" }, "status": { "type": "number", "example": 500 } }, "required": [ "error", "status" ] } }, "required": [ "id", "timestamp", "api_version", "object", "data" ] } } } } } } } } }