{ "openapi": "3.0.3", "info": { "title": "Bitcall OTP API", "version": "1.0.0", "description": "Rent numbers and receive one-time passcodes.\n\nEvery endpoint is reached through the Bitcall gateway and authenticated with your\nkey id and secret, sent as the `x-key-id` and `x-api-secret` headers.\n\nSingle resources return `{ \"data\": … }`. Lists return `{ \"data\": [ … ], \"meta\": { … } }`\nwith one-based `page` and `pageSize` (default 50, maximum 200).\n\nErrors return `{ \"error\": { \"code\", \"message\", \"requestId\" } }`. Every response carries\nan `x-request-id` header; quote it when contacting support." }, "servers": [ { "url": "https://api.bitcall.io", "description": "Bitcall API gateway" } ], "tags": [ { "name": "Activations" }, { "name": "Catalog" } ], "security": [ { "KeyId": [], "ApiSecret": [] } ], "paths": { "/v1/otp/activations": { "post": { "tags": [ "Activations" ], "operationId": "createOtpActivation", "summary": "Receive SMS", "description": "Rents a number for a service and country, and starts waiting for its code. The rental is charged on success and the activation begins in `waiting`. `serviceId` identifies the offer to rent and comes from [GET /v1/otp/services](/openapi/otp/catalog/listOtpServices). It is opaque: send it back as published.", "responses": { "201": { "description": "Success.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "activationId": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "waiting", "activating", "received", "completed", "expired", "cancelled", "refunded", "unknown" ] }, "actions": { "type": "object", "properties": { "canResend": { "type": "boolean" }, "canReactivate": { "type": "boolean" } }, "required": [ "canResend", "canReactivate" ], "additionalProperties": false }, "serviceId": { "type": "string", "description": "The offer this order was placed against — the same value the catalogue publishes." }, "service": { "type": "string" }, "countryCode": { "type": "string" }, "phoneNumber": { "type": "string" }, "price": { "type": "object", "properties": { "amount": { "type": "number", "example": 1.0025 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "example": "EUR" } }, "required": [ "amount", "currency" ], "additionalProperties": false }, "code": { "type": "string" }, "expiresAt": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "resend": { "type": "object", "properties": { "cooldownSeconds": { "type": "number" }, "price": { "type": "object", "properties": { "amount": { "type": "number", "example": 1.0025 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "example": "EUR" } }, "required": [ "amount", "currency" ], "additionalProperties": false } }, "additionalProperties": false } }, "required": [ "activationId", "status", "actions" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false }, "example": { "data": { "activationId": "ord_EXAMPLE_activation_000000000000000003", "status": "unknown", "actions": { "canResend": false, "canReactivate": false }, "service": "adidas", "countryCode": "US_1", "phoneNumber": "+12025550121", "price": { "amount": 0.336276, "currency": "EUR" }, "expiresAt": "2026-09-15T23:43:25.000Z" } } } } }, "400": { "description": "VALIDATION_ERROR", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "VALIDATION_ERROR", "message": "The request is not valid. See `fields` for what to correct.", "requestId": "9f1c7b2e-…" } } } } }, "401": { "description": "AUTHENTICATION_REQUIRED · INVALID_API_KEY", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "AUTHENTICATION_REQUIRED", "message": "This endpoint requires an API key.", "requestId": "9f1c7b2e-…" } } } } }, "409": { "description": "CONFLICT · INSUFFICIENT_BALANCE · PRODUCT_UNAVAILABLE", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "CONFLICT", "message": "The resource is not in a state that allows this operation.", "requestId": "9f1c7b2e-…" } } } } }, "429": { "description": "RATE_LIMITED", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" }, "retry-after": { "description": "Whole seconds to wait before retrying.", "required": true, "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Retry after the interval in `Retry-After`.", "requestId": "9f1c7b2e-…" } } } } }, "500": { "description": "INTERNAL_ERROR", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Something went wrong on our side.", "requestId": "9f1c7b2e-…" } } } } }, "502": { "description": "SERVICE_RESPONSE_INVALID", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "SERVICE_RESPONSE_INVALID", "message": "The upstream service returned an unexpected response.", "requestId": "9f1c7b2e-…" } } } } }, "503": { "description": "SERVICE_UNAVAILABLE", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "The service is temporarily unavailable. Try again shortly.", "requestId": "9f1c7b2e-…" } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "serviceId": { "type": "string", "minLength": 1, "description": "The offer to rent, taken from the catalogue: `pools[].serviceId` on GET /v1/otp/services (or any other catalogue offer). Opaque — send it back exactly as published; do not assemble one." } }, "required": [ "serviceId" ], "additionalProperties": false }, "example": { "serviceId": "CHARLIE-US-openai_/_chatgpt" } } } } }, "get": { "tags": [ "Activations" ], "operationId": "listOtpActivations", "summary": "List activations", "description": "Returns your activations, newest first, optionally filtered by status.", "responses": { "200": { "description": "Success.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "activationId": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "waiting", "activating", "received", "completed", "expired", "cancelled", "refunded", "unknown" ] }, "actions": { "type": "object", "properties": { "canResend": { "type": "boolean" }, "canReactivate": { "type": "boolean" } }, "required": [ "canResend", "canReactivate" ], "additionalProperties": false }, "serviceId": { "type": "string", "description": "The offer this order was placed against — the same value the catalogue publishes." }, "service": { "type": "string" }, "countryCode": { "type": "string" }, "phoneNumber": { "type": "string" }, "price": { "type": "object", "properties": { "amount": { "type": "number", "example": 1.0025 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "example": "EUR" } }, "required": [ "amount", "currency" ], "additionalProperties": false }, "code": { "type": "string" }, "expiresAt": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "resend": { "type": "object", "properties": { "cooldownSeconds": { "type": "number" }, "price": { "type": "object", "properties": { "amount": { "type": "number", "example": 1.0025 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "example": "EUR" } }, "required": [ "amount", "currency" ], "additionalProperties": false } }, "additionalProperties": false } }, "required": [ "activationId", "status", "actions" ], "additionalProperties": false } }, "meta": { "type": "object", "properties": { "page": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "example": 1 }, "pageSize": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "example": 50 }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "example": 137 }, "totalPages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "example": 3 }, "hasNext": { "type": "boolean", "example": true } }, "required": [ "page", "pageSize", "hasNext" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false }, "example": { "data": [ { "activationId": "ord_EXAMPLE_activation_000000000000000001", "status": "cancelled", "actions": { "canResend": false, "canReactivate": true }, "serviceId": "BRAVO-US-gmx", "service": "GMX", "countryCode": "US_1", "phoneNumber": "+12025550143", "price": { "amount": 0.508725, "currency": "EUR" }, "expiresAt": "2026-09-15T13:16:46.000Z", "createdAt": "2026-09-15T12:56:46.923Z", "updatedAt": "2026-09-15T23:19:08.044Z", "resend": { "price": { "amount": 0.508725, "currency": "EUR" } } }, { "activationId": "ord_EXAMPLE_activation_000000000000000002", "status": "cancelled", "actions": { "canResend": false, "canReactivate": true }, "serviceId": "BRAVO-US-instagram_/_threads", "service": "Instagram / Threads", "countryCode": "US_1", "phoneNumber": "+12025550187", "price": { "amount": 27.574627, "currency": "EUR" }, "expiresAt": "2026-09-11T16:01:10.000Z", "createdAt": "2026-09-11T15:41:10.106Z", "updatedAt": "2026-09-11T16:01:18.107Z", "resend": { "price": { "amount": 27.574627, "currency": "EUR" } } } ], "meta": { "page": 1, "pageSize": 2, "total": 47, "totalPages": 24, "hasNext": true } } } } }, "400": { "description": "VALIDATION_ERROR", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "VALIDATION_ERROR", "message": "The request is not valid. See `fields` for what to correct.", "requestId": "9f1c7b2e-…" } } } } }, "401": { "description": "AUTHENTICATION_REQUIRED · INVALID_API_KEY", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "AUTHENTICATION_REQUIRED", "message": "This endpoint requires an API key.", "requestId": "9f1c7b2e-…" } } } } }, "409": { "description": "CONFLICT", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "CONFLICT", "message": "The resource is not in a state that allows this operation.", "requestId": "9f1c7b2e-…" } } } } }, "429": { "description": "RATE_LIMITED", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" }, "retry-after": { "description": "Whole seconds to wait before retrying.", "required": true, "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Retry after the interval in `Retry-After`.", "requestId": "9f1c7b2e-…" } } } } }, "500": { "description": "INTERNAL_ERROR", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Something went wrong on our side.", "requestId": "9f1c7b2e-…" } } } } }, "502": { "description": "SERVICE_RESPONSE_INVALID", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "SERVICE_RESPONSE_INVALID", "message": "The upstream service returned an unexpected response.", "requestId": "9f1c7b2e-…" } } } } }, "503": { "description": "SERVICE_UNAVAILABLE", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "The service is temporarily unavailable. Try again shortly.", "requestId": "9f1c7b2e-…" } } } } } }, "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "waiting", "activating", "received", "completed", "expired", "cancelled", "refunded", "unknown" ] }, "example": "waiting" }, { "name": "page", "in": "query", "required": false, "schema": { "default": 1, "type": "integer", "minimum": 1, "maximum": 10000 }, "example": 1 }, { "name": "pageSize", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 }, "example": 50 } ] } }, "/v1/otp/activations/{activationId}": { "get": { "tags": [ "Activations" ], "operationId": "getOtpActivation", "summary": "Get an activation", "description": "Returns one activation, including the received code once it arrives. Poll this after renting a number.", "responses": { "200": { "description": "Success.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "activationId": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "waiting", "activating", "received", "completed", "expired", "cancelled", "refunded", "unknown" ] }, "actions": { "type": "object", "properties": { "canResend": { "type": "boolean" }, "canReactivate": { "type": "boolean" } }, "required": [ "canResend", "canReactivate" ], "additionalProperties": false }, "serviceId": { "type": "string", "description": "The offer this order was placed against — the same value the catalogue publishes." }, "service": { "type": "string" }, "countryCode": { "type": "string" }, "phoneNumber": { "type": "string" }, "price": { "type": "object", "properties": { "amount": { "type": "number", "example": 1.0025 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "example": "EUR" } }, "required": [ "amount", "currency" ], "additionalProperties": false }, "code": { "type": "string" }, "expiresAt": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "resend": { "type": "object", "properties": { "cooldownSeconds": { "type": "number" }, "price": { "type": "object", "properties": { "amount": { "type": "number", "example": 1.0025 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "example": "EUR" } }, "required": [ "amount", "currency" ], "additionalProperties": false } }, "additionalProperties": false } }, "required": [ "activationId", "status", "actions" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false }, "example": { "data": { "activationId": "ord_EXAMPLE_activation_000000000000000001", "status": "cancelled", "actions": { "canResend": false, "canReactivate": true }, "serviceId": "BRAVO-US-gmx", "service": "GMX", "countryCode": "US_1", "phoneNumber": "+12025550143", "price": { "amount": 0.508725, "currency": "EUR" }, "expiresAt": "2026-09-15T13:16:46.000Z", "createdAt": "2026-09-15T12:56:46.923Z", "updatedAt": "2026-09-15T23:19:08.044Z", "resend": { "price": { "amount": 0.508725, "currency": "EUR" } } } } } } }, "400": { "description": "VALIDATION_ERROR", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "VALIDATION_ERROR", "message": "The request is not valid. See `fields` for what to correct.", "requestId": "9f1c7b2e-…" } } } } }, "401": { "description": "AUTHENTICATION_REQUIRED · INVALID_API_KEY", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "AUTHENTICATION_REQUIRED", "message": "This endpoint requires an API key.", "requestId": "9f1c7b2e-…" } } } } }, "404": { "description": "NOT_FOUND", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "No such resource.", "requestId": "9f1c7b2e-…" } } } } }, "409": { "description": "CONFLICT", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "CONFLICT", "message": "The resource is not in a state that allows this operation.", "requestId": "9f1c7b2e-…" } } } } }, "429": { "description": "RATE_LIMITED", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" }, "retry-after": { "description": "Whole seconds to wait before retrying.", "required": true, "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Retry after the interval in `Retry-After`.", "requestId": "9f1c7b2e-…" } } } } }, "500": { "description": "INTERNAL_ERROR", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Something went wrong on our side.", "requestId": "9f1c7b2e-…" } } } } }, "502": { "description": "SERVICE_RESPONSE_INVALID", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "SERVICE_RESPONSE_INVALID", "message": "The upstream service returned an unexpected response.", "requestId": "9f1c7b2e-…" } } } } }, "503": { "description": "SERVICE_UNAVAILABLE", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "The service is temporarily unavailable. Try again shortly.", "requestId": "9f1c7b2e-…" } } } } } }, "parameters": [ { "name": "activationId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^ord_[A-Za-z0-9_-]{20,128}$" } } ] } }, "/v1/otp/activations/{activationId}/cancel": { "post": { "tags": [ "Activations" ], "operationId": "cancelOtpActivation", "summary": "Cancel an activation", "description": "Releases a number before its code arrives and refunds the rental while the activation is still cancellable. Immediately after purchase, cancellation may be temporarily unavailable while the provider enforces a short minimum-hold: during this window the call returns 409 CANCELLATION_NOT_AVAILABLE_YET — wait a short while, then retry. The block lifts on its own, nothing is charged for the refused attempt, and a successful cancellation still refunds the rental. Once it is no longer cancellable — already cancelled, or a code has already arrived — the call returns 409 CONFLICT and nothing changes.", "responses": { "200": { "description": "Success.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "activationId": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "waiting", "activating", "received", "completed", "expired", "cancelled", "refunded", "unknown" ] }, "actions": { "type": "object", "properties": { "canResend": { "type": "boolean" }, "canReactivate": { "type": "boolean" } }, "required": [ "canResend", "canReactivate" ], "additionalProperties": false }, "serviceId": { "type": "string", "description": "The offer this order was placed against — the same value the catalogue publishes." }, "service": { "type": "string" }, "countryCode": { "type": "string" }, "phoneNumber": { "type": "string" }, "price": { "type": "object", "properties": { "amount": { "type": "number", "example": 1.0025 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "example": "EUR" } }, "required": [ "amount", "currency" ], "additionalProperties": false }, "code": { "type": "string" }, "expiresAt": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "resend": { "type": "object", "properties": { "cooldownSeconds": { "type": "number" }, "price": { "type": "object", "properties": { "amount": { "type": "number", "example": 1.0025 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "example": "EUR" } }, "required": [ "amount", "currency" ], "additionalProperties": false } }, "additionalProperties": false } }, "required": [ "activationId", "status", "actions" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false }, "example": { "data": { "activationId": "ord_EXAMPLE_activation_000000000000000001", "status": "cancelled", "actions": { "canResend": false, "canReactivate": true }, "serviceId": "BRAVO-US-gmx", "service": "GMX", "countryCode": "US_1", "phoneNumber": "+12025550143", "price": { "amount": 0.508725, "currency": "EUR" }, "expiresAt": "2026-09-15T13:16:46.000Z", "createdAt": "2026-09-15T12:56:46.923Z", "updatedAt": "2026-09-15T23:19:08.044Z", "resend": { "price": { "amount": 0.508725, "currency": "EUR" } } } } } } }, "400": { "description": "VALIDATION_ERROR", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "VALIDATION_ERROR", "message": "The request is not valid. See `fields` for what to correct.", "requestId": "9f1c7b2e-…" } } } } }, "401": { "description": "AUTHENTICATION_REQUIRED · INVALID_API_KEY", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "AUTHENTICATION_REQUIRED", "message": "This endpoint requires an API key.", "requestId": "9f1c7b2e-…" } } } } }, "404": { "description": "NOT_FOUND", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "No such resource.", "requestId": "9f1c7b2e-…" } } } } }, "409": { "description": "CONFLICT · CANCELLATION_NOT_AVAILABLE_YET", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "CONFLICT", "message": "The resource is not in a state that allows this operation.", "requestId": "9f1c7b2e-…" } } } } }, "429": { "description": "RATE_LIMITED", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" }, "retry-after": { "description": "Whole seconds to wait before retrying.", "required": true, "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Retry after the interval in `Retry-After`.", "requestId": "9f1c7b2e-…" } } } } }, "500": { "description": "INTERNAL_ERROR", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Something went wrong on our side.", "requestId": "9f1c7b2e-…" } } } } }, "502": { "description": "SERVICE_RESPONSE_INVALID", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "SERVICE_RESPONSE_INVALID", "message": "The upstream service returned an unexpected response.", "requestId": "9f1c7b2e-…" } } } } }, "503": { "description": "SERVICE_UNAVAILABLE", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "The service is temporarily unavailable. Try again shortly.", "requestId": "9f1c7b2e-…" } } } } } }, "parameters": [ { "name": "activationId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^ord_[A-Za-z0-9_-]{20,128}$" } } ] } }, "/v1/otp/activations/{activationId}/resend": { "post": { "tags": [ "Activations" ], "operationId": "resendOtpCode", "summary": "Ask for the code again", "description": "Requests another send of the code on the same number. Subject to a cooldown, and chargeable where the activation carries a resend price.", "responses": { "200": { "description": "Success.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "activationId": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "waiting", "activating", "received", "completed", "expired", "cancelled", "refunded", "unknown" ] }, "actions": { "type": "object", "properties": { "canResend": { "type": "boolean" }, "canReactivate": { "type": "boolean" } }, "required": [ "canResend", "canReactivate" ], "additionalProperties": false }, "serviceId": { "type": "string", "description": "The offer this order was placed against — the same value the catalogue publishes." }, "service": { "type": "string" }, "countryCode": { "type": "string" }, "phoneNumber": { "type": "string" }, "price": { "type": "object", "properties": { "amount": { "type": "number", "example": 1.0025 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "example": "EUR" } }, "required": [ "amount", "currency" ], "additionalProperties": false }, "code": { "type": "string" }, "expiresAt": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "resend": { "type": "object", "properties": { "cooldownSeconds": { "type": "number" }, "price": { "type": "object", "properties": { "amount": { "type": "number", "example": 1.0025 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "example": "EUR" } }, "required": [ "amount", "currency" ], "additionalProperties": false } }, "additionalProperties": false } }, "required": [ "activationId", "status", "actions" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false }, "example": { "data": { "activationId": "ord_EXAMPLE_activation_000000000000000001", "status": "waiting", "actions": { "canResend": false, "canReactivate": true }, "serviceId": "BRAVO-US-gmx", "service": "GMX", "countryCode": "US_1", "phoneNumber": "+12025550143", "price": { "amount": 0.508725, "currency": "EUR" }, "expiresAt": "2026-09-15T13:16:46.000Z", "createdAt": "2026-09-15T12:56:46.923Z", "updatedAt": "2026-09-15T23:19:08.044Z", "resend": { "price": { "amount": 0.508725, "currency": "EUR" } } } } } } }, "400": { "description": "VALIDATION_ERROR", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "VALIDATION_ERROR", "message": "The request is not valid. See `fields` for what to correct.", "requestId": "9f1c7b2e-…" } } } } }, "401": { "description": "AUTHENTICATION_REQUIRED · INVALID_API_KEY", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "AUTHENTICATION_REQUIRED", "message": "This endpoint requires an API key.", "requestId": "9f1c7b2e-…" } } } } }, "404": { "description": "NOT_FOUND", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "No such resource.", "requestId": "9f1c7b2e-…" } } } } }, "409": { "description": "CONFLICT · INSUFFICIENT_BALANCE", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "CONFLICT", "message": "The resource is not in a state that allows this operation.", "requestId": "9f1c7b2e-…" } } } } }, "429": { "description": "RATE_LIMITED", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" }, "retry-after": { "description": "Whole seconds to wait before retrying.", "required": true, "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Retry after the interval in `Retry-After`.", "requestId": "9f1c7b2e-…" } } } } }, "500": { "description": "INTERNAL_ERROR", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Something went wrong on our side.", "requestId": "9f1c7b2e-…" } } } } }, "502": { "description": "SERVICE_RESPONSE_INVALID", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "SERVICE_RESPONSE_INVALID", "message": "The upstream service returned an unexpected response.", "requestId": "9f1c7b2e-…" } } } } }, "503": { "description": "SERVICE_UNAVAILABLE", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "The service is temporarily unavailable. Try again shortly.", "requestId": "9f1c7b2e-…" } } } } } }, "parameters": [ { "name": "activationId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^ord_[A-Za-z0-9_-]{20,128}$" } } ] } }, "/v1/otp/activations/{activationId}/reactivate": { "post": { "tags": [ "Activations" ], "operationId": "reactivateOtpActivation", "summary": "Reactivate an activation", "description": "Reopens an expired or cancelled activation on the same number so it can receive a further code. Chargeable. Only available for a short window after the activation ends, on supported number pools — the `canReactivate` flag on an activation is a best-effort hint from its state, so reactivation can still be refused (409 REACTIVATION_UNAVAILABLE) when the provider window has closed; start a new activation in that case.", "responses": { "200": { "description": "Success.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "activationId": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "waiting", "activating", "received", "completed", "expired", "cancelled", "refunded", "unknown" ] }, "actions": { "type": "object", "properties": { "canResend": { "type": "boolean" }, "canReactivate": { "type": "boolean" } }, "required": [ "canResend", "canReactivate" ], "additionalProperties": false }, "serviceId": { "type": "string", "description": "The offer this order was placed against — the same value the catalogue publishes." }, "service": { "type": "string" }, "countryCode": { "type": "string" }, "phoneNumber": { "type": "string" }, "price": { "type": "object", "properties": { "amount": { "type": "number", "example": 1.0025 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "example": "EUR" } }, "required": [ "amount", "currency" ], "additionalProperties": false }, "code": { "type": "string" }, "expiresAt": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "resend": { "type": "object", "properties": { "cooldownSeconds": { "type": "number" }, "price": { "type": "object", "properties": { "amount": { "type": "number", "example": 1.0025 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "example": "EUR" } }, "required": [ "amount", "currency" ], "additionalProperties": false } }, "additionalProperties": false } }, "required": [ "activationId", "status", "actions" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false }, "example": { "data": { "activationId": "ord_EXAMPLE_activation_000000000000000001", "status": "waiting", "actions": { "canResend": false, "canReactivate": true }, "serviceId": "BRAVO-US-gmx", "service": "GMX", "countryCode": "US_1", "phoneNumber": "+12025550143", "price": { "amount": 0.508725, "currency": "EUR" }, "expiresAt": "2026-09-15T13:16:46.000Z", "createdAt": "2026-09-15T12:56:46.923Z", "updatedAt": "2026-09-15T23:19:08.044Z", "resend": { "price": { "amount": 0.508725, "currency": "EUR" } } } } } } }, "400": { "description": "VALIDATION_ERROR", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "VALIDATION_ERROR", "message": "The request is not valid. See `fields` for what to correct.", "requestId": "9f1c7b2e-…" } } } } }, "401": { "description": "AUTHENTICATION_REQUIRED · INVALID_API_KEY", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "AUTHENTICATION_REQUIRED", "message": "This endpoint requires an API key.", "requestId": "9f1c7b2e-…" } } } } }, "404": { "description": "NOT_FOUND", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "No such resource.", "requestId": "9f1c7b2e-…" } } } } }, "409": { "description": "CONFLICT · INSUFFICIENT_BALANCE · REACTIVATION_UNAVAILABLE", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "CONFLICT", "message": "The resource is not in a state that allows this operation.", "requestId": "9f1c7b2e-…" } } } } }, "429": { "description": "RATE_LIMITED", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" }, "retry-after": { "description": "Whole seconds to wait before retrying.", "required": true, "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Retry after the interval in `Retry-After`.", "requestId": "9f1c7b2e-…" } } } } }, "500": { "description": "INTERNAL_ERROR", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Something went wrong on our side.", "requestId": "9f1c7b2e-…" } } } } }, "502": { "description": "SERVICE_RESPONSE_INVALID", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "SERVICE_RESPONSE_INVALID", "message": "The upstream service returned an unexpected response.", "requestId": "9f1c7b2e-…" } } } } }, "503": { "description": "SERVICE_UNAVAILABLE", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "The service is temporarily unavailable. Try again shortly.", "requestId": "9f1c7b2e-…" } } } } } }, "parameters": [ { "name": "activationId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^ord_[A-Za-z0-9_-]{20,128}$" } } ] } }, "/v1/otp/pools": { "get": { "tags": [ "Catalog" ], "operationId": "listOtpPools", "summary": "List number pools", "description": "Returns the number pools available to you, by their public codes. A pool is a grouping of numbers, not something you can rent directly: use its code to filter [GET /v1/otp/services](/openapi/otp/catalog/listOtpServices), and rent with the `serviceId` from a catalog offer — whose first segment is this same code.", "responses": { "200": { "description": "Success.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "pool": { "type": "string", "description": "The pool’s public code (`CHARLIE`) — the value the `pool` filter on GET /v1/otp/services accepts, and the first segment of every `serviceId` from that pool. A pool is a grouping of numbers, not something you can buy: to rent a number use the `serviceId` on a catalogue offer." }, "serviceCount": { "type": "number" } }, "additionalProperties": false } }, "meta": { "type": "object", "properties": { "page": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "example": 1 }, "pageSize": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "example": 50 }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "example": 137 }, "totalPages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "example": 3 }, "hasNext": { "type": "boolean", "example": true } }, "required": [ "page", "pageSize", "hasNext" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false }, "example": { "data": [ { "pool": "BRAVO", "serviceCount": 172 }, { "pool": "CHARLIE", "serviceCount": 1312 } ], "meta": { "page": 1, "pageSize": 2, "total": 11, "totalPages": 6, "hasNext": true } } } } }, "400": { "description": "VALIDATION_ERROR", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "VALIDATION_ERROR", "message": "The request is not valid. See `fields` for what to correct.", "requestId": "9f1c7b2e-…" } } } } }, "401": { "description": "AUTHENTICATION_REQUIRED · INVALID_API_KEY", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "AUTHENTICATION_REQUIRED", "message": "This endpoint requires an API key.", "requestId": "9f1c7b2e-…" } } } } }, "409": { "description": "CONFLICT", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "CONFLICT", "message": "The resource is not in a state that allows this operation.", "requestId": "9f1c7b2e-…" } } } } }, "429": { "description": "RATE_LIMITED", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" }, "retry-after": { "description": "Whole seconds to wait before retrying.", "required": true, "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Retry after the interval in `Retry-After`.", "requestId": "9f1c7b2e-…" } } } } }, "500": { "description": "INTERNAL_ERROR", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Something went wrong on our side.", "requestId": "9f1c7b2e-…" } } } } }, "502": { "description": "SERVICE_RESPONSE_INVALID", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "SERVICE_RESPONSE_INVALID", "message": "The upstream service returned an unexpected response.", "requestId": "9f1c7b2e-…" } } } } }, "503": { "description": "SERVICE_UNAVAILABLE", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "The service is temporarily unavailable. Try again shortly.", "requestId": "9f1c7b2e-…" } } } } } }, "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "schema": { "default": 1, "type": "integer", "minimum": 1, "maximum": 10000 }, "example": 1 }, { "name": "pageSize", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 }, "example": 50 } ] } }, "/v1/otp/countries": { "get": { "tags": [ "Catalog" ], "operationId": "listOtpCountries", "summary": "List countries", "description": "Returns the countries with numbers available to you. A `null` starter price means the country has no priced services under your profile.", "responses": { "200": { "description": "Success.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "countryCode": { "type": "string" }, "name": { "type": "string" }, "flag": { "type": "string" }, "serviceCount": { "type": "number" }, "availableCount": { "type": "number" }, "startingPrice": { "type": "object", "properties": { "amount": { "type": "number", "example": 1.0025 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "example": "EUR" } }, "required": [ "amount", "currency" ], "additionalProperties": false }, "price": { "type": "object", "properties": { "min": { "type": "number" }, "max": { "type": "number" }, "average": { "type": "number" }, "currency": { "type": "string" } }, "required": [ "min", "max", "average", "currency" ], "additionalProperties": false }, "poolCount": { "type": "number", "description": "How many pool offers exist for this entry, before the inline cap." }, "pools": { "type": "array", "items": { "type": "object", "properties": { "serviceId": { "type": "string", "description": "Send this as `serviceId` to POST /v1/otp/activations to rent a number from this offer. Composite and opaque — pool, country and service in one value (`CHARLIE-US-openai_/_chatgpt`); read it, do not build it." }, "price": { "type": "object", "properties": { "amount": { "type": "number", "example": 1.0025 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "example": "EUR" } }, "required": [ "amount", "currency" ], "additionalProperties": false }, "availableCount": { "type": "number" }, "successRate": { "type": "number" } }, "additionalProperties": false }, "description": "At most `MAX_POOLS_PER_ENTRY` offers, cheapest first. `poolCount` reports how many exist in total." } }, "additionalProperties": false } }, "meta": { "type": "object", "properties": { "page": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "example": 1 }, "pageSize": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "example": 50 }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "example": 137 }, "totalPages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "example": 3 }, "hasNext": { "type": "boolean", "example": true } }, "required": [ "page", "pageSize", "hasNext" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false }, "example": { "data": [ { "countryCode": "JM_1", "name": "Jamaica", "flag": "https://flagcdn.com/48x36/jm.png", "serviceCount": 62, "startingPrice": { "amount": 0.508725, "currency": "EUR" } }, { "countryCode": "US_1", "name": "United States (Virtual)", "flag": "https://flagcdn.com/48x36/us.png", "serviceCount": 1270, "startingPrice": { "amount": 1.008828, "currency": "EUR" } } ], "meta": { "page": 1, "pageSize": 3, "total": 170, "totalPages": 57, "hasNext": true } } } } }, "400": { "description": "VALIDATION_ERROR", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "VALIDATION_ERROR", "message": "The request is not valid. See `fields` for what to correct.", "requestId": "9f1c7b2e-…" } } } } }, "401": { "description": "AUTHENTICATION_REQUIRED · INVALID_API_KEY", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "AUTHENTICATION_REQUIRED", "message": "This endpoint requires an API key.", "requestId": "9f1c7b2e-…" } } } } }, "409": { "description": "CONFLICT", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "CONFLICT", "message": "The resource is not in a state that allows this operation.", "requestId": "9f1c7b2e-…" } } } } }, "429": { "description": "RATE_LIMITED", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" }, "retry-after": { "description": "Whole seconds to wait before retrying.", "required": true, "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Retry after the interval in `Retry-After`.", "requestId": "9f1c7b2e-…" } } } } }, "500": { "description": "INTERNAL_ERROR", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Something went wrong on our side.", "requestId": "9f1c7b2e-…" } } } } }, "502": { "description": "SERVICE_RESPONSE_INVALID", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "SERVICE_RESPONSE_INVALID", "message": "The upstream service returned an unexpected response.", "requestId": "9f1c7b2e-…" } } } } }, "503": { "description": "SERVICE_UNAVAILABLE", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "The service is temporarily unavailable. Try again shortly.", "requestId": "9f1c7b2e-…" } } } } } }, "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "schema": { "default": 1, "type": "integer", "minimum": 1, "maximum": 10000 }, "example": 1 }, { "name": "pageSize", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 }, "example": 50 } ] } }, "/v1/otp/services": { "get": { "tags": [ "Catalog" ], "operationId": "listOtpServices", "summary": "List services", "description": "Returns the services you can rent numbers for, searchable by name. Each entry’s `pools[]` are the individual offers, and each offer carries the `serviceId` you send to [POST /v1/otp/activations](/openapi/otp/activations/createOtpActivation).", "responses": { "200": { "description": "Success.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "slug": { "type": "string" }, "availableCount": { "type": "number" }, "price": { "type": "object", "properties": { "min": { "type": "number" }, "max": { "type": "number" }, "average": { "type": "number" }, "currency": { "type": "string" } }, "required": [ "min", "max", "average", "currency" ], "additionalProperties": false }, "poolCount": { "type": "number", "description": "How many pool offers exist for this entry, before the inline cap." }, "pools": { "type": "array", "items": { "type": "object", "properties": { "serviceId": { "type": "string", "description": "Send this as `serviceId` to POST /v1/otp/activations to rent a number from this offer. Composite and opaque — pool, country and service in one value (`CHARLIE-US-openai_/_chatgpt`); read it, do not build it." }, "price": { "type": "object", "properties": { "amount": { "type": "number", "example": 1.0025 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "example": "EUR" } }, "required": [ "amount", "currency" ], "additionalProperties": false }, "availableCount": { "type": "number" }, "successRate": { "type": "number" } }, "additionalProperties": false }, "description": "At most `MAX_POOLS_PER_ENTRY` offers, cheapest first. `poolCount` reports how many exist in total." } }, "additionalProperties": false } }, "meta": { "type": "object", "properties": { "page": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "example": 1 }, "pageSize": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "example": 50 }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "example": 137 }, "totalPages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "example": 3 }, "hasNext": { "type": "boolean", "example": true } }, "required": [ "page", "pageSize", "hasNext" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false }, "example": { "data": [ { "name": "adidas", "slug": "adidas", "availableCount": 42780784, "price": { "min": 0.336276, "max": 52.29522, "average": 5.820161, "currency": "EUR" }, "poolCount": 125, "pools": [ { "serviceId": "ALPHA-46-adidas", "price": { "amount": 0.336276, "currency": "EUR" }, "availableCount": 9999 }, { "serviceId": "ALPHA-229-adidas", "price": { "amount": 1.345104, "currency": "EUR" }, "availableCount": 5851 }, { "serviceId": "DELTA-AR-adidas", "price": { "amount": 2.190105, "currency": "EUR" }, "availableCount": 23034 }, { "serviceId": "ALPHA-258-adidas", "price": { "amount": 2.353932, "currency": "EUR" }, "availableCount": 265 }, { "serviceId": "ALPHA-27-adidas", "price": { "amount": 2.353932, "currency": "EUR" }, "availableCount": 3100 } ] }, { "name": "Instagram", "slug": "instagram", "availableCount": 178805402, "price": { "min": 0.845001, "max": 126.103477, "average": 6.760009, "currency": "EUR" }, "poolCount": 303, "pools": [ { "serviceId": "DELTA-CO-instagram_/_threads", "price": { "amount": 0.845001, "currency": "EUR" }, "availableCount": 18189030 }, { "serviceId": "DELTA-ID-instagram_/_threads", "price": { "amount": 0.845001, "currency": "EUR" }, "availableCount": 2736514 }, { "serviceId": "DELTA-VN-instagram_/_threads", "price": { "amount": 0.845001, "currency": "EUR" }, "availableCount": 2814619 }, { "serviceId": "BRAVO-KG-instagram_/_threads", "price": { "amount": 0.845001, "currency": "EUR" }, "availableCount": 15769 }, { "serviceId": "DELTA-BR-instagram_/_threads", "price": { "amount": 1.008828, "currency": "EUR" }, "availableCount": 15996468 } ] } ], "meta": { "page": 1, "pageSize": 3, "total": 2838, "totalPages": 946, "hasNext": true } } } } }, "400": { "description": "VALIDATION_ERROR", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "VALIDATION_ERROR", "message": "The request is not valid. See `fields` for what to correct.", "requestId": "9f1c7b2e-…" } } } } }, "401": { "description": "AUTHENTICATION_REQUIRED · INVALID_API_KEY", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "AUTHENTICATION_REQUIRED", "message": "This endpoint requires an API key.", "requestId": "9f1c7b2e-…" } } } } }, "409": { "description": "CONFLICT", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "CONFLICT", "message": "The resource is not in a state that allows this operation.", "requestId": "9f1c7b2e-…" } } } } }, "429": { "description": "RATE_LIMITED", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" }, "retry-after": { "description": "Whole seconds to wait before retrying.", "required": true, "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Retry after the interval in `Retry-After`.", "requestId": "9f1c7b2e-…" } } } } }, "500": { "description": "INTERNAL_ERROR", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Something went wrong on our side.", "requestId": "9f1c7b2e-…" } } } } }, "502": { "description": "SERVICE_RESPONSE_INVALID", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "SERVICE_RESPONSE_INVALID", "message": "The upstream service returned an unexpected response.", "requestId": "9f1c7b2e-…" } } } } }, "503": { "description": "SERVICE_UNAVAILABLE", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "The service is temporarily unavailable. Try again shortly.", "requestId": "9f1c7b2e-…" } } } } } }, "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "name", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "country_code", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "pool", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "schema": { "default": 1, "type": "integer", "minimum": 1, "maximum": 10000 }, "example": 1 }, { "name": "pageSize", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 }, "example": 50 } ] } }, "/v1/otp/services/{service}": { "get": { "tags": [ "Catalog" ], "operationId": "getOtpService", "summary": "Find a service", "description": "Returns the offers for a service across countries and pools — one row per offer, each with the `serviceId` you send to [POST /v1/otp/activations](/openapi/otp/activations/createOtpActivation). The path segment addresses either **one offer**, by the `serviceId` a catalogue response published (`ALPHA-372-alibaba`) — matched exactly, and a 404 when no such offer is sellable to you — or **any service by name**, as free text (`viber`, `alibaba`) matched case-insensitively against a service name or slug. A name that matches nothing is an empty `data` array with `meta.total` 0, not a 404: no result is a result. Offers with no numbers in stock are omitted either way, so a sold-out offer id 404s.", "responses": { "200": { "description": "Success.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "serviceId": { "type": "string", "description": "Send this as `serviceId` to POST /v1/otp/activations to rent a number from this offer." }, "name": { "type": "string" }, "slug": { "type": "string" }, "price": { "type": "object", "properties": { "amount": { "type": "number", "example": 1.0025 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "example": "EUR" } }, "required": [ "amount", "currency" ], "additionalProperties": false }, "availableCount": { "type": "number" }, "country": { "type": "object", "properties": { "countryCode": { "type": "string" }, "name": { "type": "string" }, "flag": { "type": "string" } }, "required": [ "countryCode" ], "additionalProperties": false } }, "additionalProperties": false } }, "meta": { "type": "object", "properties": { "page": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "example": 1 }, "pageSize": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "example": 50 }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "example": 137 }, "totalPages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "example": 3 }, "hasNext": { "type": "boolean", "example": true } }, "required": [ "page", "pageSize", "hasNext" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false }, "example": { "data": [ { "serviceId": "ALPHA-225-adidas", "name": "adidas", "slug": "adidas", "price": { "amount": 4.707863, "currency": "EUR" }, "availableCount": 1069, "country": { "countryCode": "CI_225", "name": "Ivory Coast", "flag": "https://flagcdn.com/48x36/ci.png" } } ], "meta": { "page": 1, "pageSize": 50, "total": 125, "totalPages": 3, "hasNext": true } } } } }, "400": { "description": "VALIDATION_ERROR", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "VALIDATION_ERROR", "message": "The request is not valid. See `fields` for what to correct.", "requestId": "9f1c7b2e-…" } } } } }, "401": { "description": "AUTHENTICATION_REQUIRED · INVALID_API_KEY", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "AUTHENTICATION_REQUIRED", "message": "This endpoint requires an API key.", "requestId": "9f1c7b2e-…" } } } } }, "404": { "description": "NOT_FOUND", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "No such resource.", "requestId": "9f1c7b2e-…" } } } } }, "409": { "description": "CONFLICT", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "CONFLICT", "message": "The resource is not in a state that allows this operation.", "requestId": "9f1c7b2e-…" } } } } }, "429": { "description": "RATE_LIMITED", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" }, "retry-after": { "description": "Whole seconds to wait before retrying.", "required": true, "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Retry after the interval in `Retry-After`.", "requestId": "9f1c7b2e-…" } } } } }, "500": { "description": "INTERNAL_ERROR", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Something went wrong on our side.", "requestId": "9f1c7b2e-…" } } } } }, "502": { "description": "SERVICE_RESPONSE_INVALID", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "SERVICE_RESPONSE_INVALID", "message": "The upstream service returned an unexpected response.", "requestId": "9f1c7b2e-…" } } } } }, "503": { "description": "SERVICE_UNAVAILABLE", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "The service is temporarily unavailable. Try again shortly.", "requestId": "9f1c7b2e-…" } } } } } }, "parameters": [ { "name": "service", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "A service name, slug, or any substring of one (`viber`, `alibaba`, `openai`), matched case-insensitively — or one offer’s `serviceId` exactly as a catalogue response published it (`ALPHA-372-alibaba`), which addresses that single offer and 404s when it is not sellable to you." }, "example": "viber" }, { "name": "page", "in": "query", "required": false, "schema": { "default": 1, "type": "integer", "minimum": 1, "maximum": 10000 }, "example": 1 }, { "name": "pageSize", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 }, "example": 50 } ] } } }, "components": { "securitySchemes": { "KeyId": { "type": "apiKey", "in": "header", "name": "x-key-id", "description": "Your API key id." }, "ApiSecret": { "type": "apiKey", "in": "header", "name": "x-api-secret", "description": "Your API key secret." } }, "headers": { "RequestId": { "description": "Correlation id for this request. Quote it when contacting support.", "schema": { "type": "string" } }, "CacheControlNoStore": { "description": "Always `no-store, private`. This body may carry order, eSIM or activation material — an activation code is a bearer credential — so it must not be written to any cache, proxy or log, yours included.", "schema": { "type": "string", "enum": [ "no-store, private" ] } }, "CacheControlPrivate": { "description": "Always `private, max-age=300`. Catalogue data: your own client may reuse it for five minutes. `private`, never `public` — prices resolve per account, so a shared cache must not serve one account's body to another. Paired with `Vary: x-key-id`. Error responses on this route are `no-store`.", "schema": { "type": "string", "enum": [ "private, max-age=300" ] } } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "VALIDATION_ERROR", "AUTHENTICATION_REQUIRED", "INVALID_API_KEY", "NOT_FOUND", "CONFLICT", "CANCELLATION_NOT_AVAILABLE_YET", "REACTIVATION_UNAVAILABLE", "INSUFFICIENT_BALANCE", "PRODUCT_UNAVAILABLE", "RATE_LIMITED", "SERVICE_RESPONSE_INVALID", "SERVICE_UNAVAILABLE", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "fields": { "type": "array", "items": { "type": "string" }, "description": "Request-validation failures only: the field paths at fault, never their values." } } } } } } } }