{ "openapi": "3.1.0", "info": { "title": "VoidMob Public API", "version": "1.0.0", "summary": "SMS verifications, mobile proxies, and webhooks for programmatic use.", "description": "The VoidMob Public API (`/api/v1`) exposes the same surface that powers the\ndashboard - SMS verifications, mobile/GB proxy provisioning, real-time\nbalance, and outbound webhooks - under a stable, programmatic contract.\n\nRunning higher volumes? Custom pricing is available -\n[contact us](https://voidmob.com/contact).\n\n## Conventions\n\n- **Base URL:** `https://dashboard.voidmob.com/api/v1`\n- **Authentication:** Bearer token. Issue keys from\n [Developers - API Keys](https://dashboard.voidmob.com/developers/api-keys).\n Live keys are prefixed `vmk_live_`.\n- **Money:** all monetary values are **USD cents** as integers. The API\n never returns floats for money.\n- **Identifiers:** every public id has a stable prefix (`svc_`, `ver_`,\n `ren_`, `prx_`, `plan_`, `pool_`, `list_`, `whep_`, `esim_`, `prod_`,\n `evt_`). Treat them as opaque.\n- **Envelopes:** every JSON response is either\n `{ \"success\": true, \"data\": ... }` or\n `{ \"success\": false, \"error\": { code, message, docs_url, request_id, details? } }`.\n- **Idempotency:** order-creating and money-moving POST / PATCH / DELETE\n requests require an `Idempotency-Key` header (any string up to 255\n chars) - see each operation's parameters for whether it is required.\n Lighter-weight management calls (webhook-endpoint create/delete,\n auto-renew toggle, dedicated IP rotation) do not. Re-sending the same\n key with the same body replays the original response; a different body\n returns `409 IDEMPOTENCY_CONFLICT`.\n- **Rate limits:** every response carries `X-RateLimit-Limit`,\n `X-RateLimit-Remaining`, and `X-RateLimit-Reset` (unix seconds). 429s\n additionally carry `Retry-After`.\n- **Pricing:** SMS prices drift between catalog and create. Send\n `max_price_cents` to cap how much you authorize; if the lowest\n available price is above that cap, the API returns `409 PRICE_OVER_CAP`\n with both your cap and the current price in the error details. No\n partial state is created. See `verifications` and `rentals`.\n", "contact": { "name": "VoidMob", "url": "https://voidmob.com", "email": "info@voidmob.com" }, "license": { "name": "Proprietary", "url": "https://voidmob.com/terms" }, "x-logo": { "url": "https://voidmob.com/images/logo.png", "altText": "VoidMob" } }, "externalDocs": { "description": "VoidMob - SMS verifications, mobile proxies and eSIM", "url": "https://voidmob.com" }, "servers": [ { "url": "https://dashboard.voidmob.com/api/v1", "description": "Production" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Account", "description": "Authenticated account snapshot and rate-limit visibility." }, { "name": "Services", "description": "Browse the SMS service catalog for a country." }, { "name": "Verifications", "description": "Create, poll, cancel, complete, and reuse SMS verifications." }, { "name": "Rentals", "description": "Create and manage long-term phone number rentals (multi-day, multi-SMS)." }, { "name": "Proxies", "description": "Buy and manage mobile / shared proxy packages and their lists." }, { "name": "Plans", "description": "Browse proxy plans." }, { "name": "Proxy pools", "description": "Reseller-only, mobile/GB proxies only. A pool is a block of prepaid GB at a\nnegotiated per-GB rate, drawn down by the sub-orders you mint for your own\ncustomers (`POST /v1/proxies` with `pool_id`). Pools are not self-serve: one\nis provisioned for your account under a separate reseller agreement, so these\nendpoints return nothing until you have one. Contact support to set one up.\nSMS, dedicated numbers, and eSIM have no pool equivalent - resellers use the\nstandard endpoints with volume pricing applied to the account.\n" }, { "name": "Geo", "description": "Cascading geo data for mobile proxy targeting." }, { "name": "Webhooks", "description": "Outbound event subscriptions." }, { "name": "eSIM", "description": "Purchase and manage eSIM orders, browse the product catalog, and top up data." }, { "name": "System", "description": "Health and asset endpoints." } ], "paths": { "/me": { "get": { "operationId": "getMe", "tags": [ "Account" ], "summary": "Get the authenticated account snapshot", "description": "Returns the caller's user id, wallet balance, per-endpoint-group\nrate-limit ceilings, and account-created timestamp. Cacheable for 5\nseconds with `ETag` / `If-None-Match`.\n", "parameters": [ { "$ref": "#/components/parameters/IfNoneMatch" } ], "responses": { "200": { "description": "Account snapshot.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Me" } } } ] } } } }, "304": { "description": "Not Modified. Body is empty; reuse the cached value." }, "401": { "$ref": "#/components/responses/UNAUTHENTICATED" }, "403": { "$ref": "#/components/responses/IP_NOT_ALLOWED" }, "429": { "$ref": "#/components/responses/RATE_LIMITED" }, "500": { "$ref": "#/components/responses/INTERNAL_ERROR" } } } }, "/health": { "get": { "operationId": "getHealth", "tags": [ "System" ], "security": [], "summary": "Health probe (unauthenticated)", "description": "Reports overall API health, a list of SMS services that have been\ndegraded for over 15 minutes, and recent proxy provisioning latency.\nIP-rate-limited at 10 req/min.\n", "parameters": [ { "$ref": "#/components/parameters/IfNoneMatch" } ], "responses": { "200": { "description": "Current health state.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Health" } } } ] } } } }, "304": { "description": "Not Modified." }, "429": { "$ref": "#/components/responses/RATE_LIMITED" }, "500": { "$ref": "#/components/responses/INTERNAL_ERROR" } } } }, "/icons/{hash}.png": { "get": { "operationId": "getServiceIcon", "tags": [ "System" ], "security": [], "summary": "Fetch an immutable service icon PNG", "description": "Returns the PNG icon referenced by `Service.icon_url`. Files are\ncontent-hashed and `Cache-Control: public, max-age=31536000, immutable` -\ncache aggressively.\n", "parameters": [ { "name": "hash", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^([a-f0-9]{16}|default)$" }, "description": "16-char hex content hash, or the literal `default`." } ], "responses": { "200": { "description": "PNG icon.", "content": { "image/png": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "Unknown icon hash." } } } }, "/services": { "get": { "operationId": "listServices", "tags": [ "Services" ], "summary": "List SMS services for a country", "description": "Returns the SMS service catalog for the requested country with a live\nper-caller quote. Cacheable for 30 seconds via\n`ETag` / `If-None-Match`.\n\nThe `quoted_price_cents` reflects per-caller pricing (account\ndiscounts/overrides). Use it as the safe default for\n`max_price_cents` when creating a verification.\n", "parameters": [ { "$ref": "#/components/parameters/CountryQuery" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Case-insensitive substring filter on `service_name`." }, { "$ref": "#/components/parameters/IfNoneMatch" } ], "responses": { "200": { "description": "Services for the requested country.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ServicesList" } } } ] } } } }, "304": { "description": "Not Modified." }, "401": { "$ref": "#/components/responses/UNAUTHENTICATED" }, "403": { "$ref": "#/components/responses/IP_NOT_ALLOWED" }, "429": { "$ref": "#/components/responses/RATE_LIMITED" }, "500": { "$ref": "#/components/responses/INTERNAL_ERROR" } } } }, "/esim_products": { "get": { "operationId": "listEsimProducts", "tags": [ "eSIM" ], "summary": "List eSIM products (catalog)", "description": "Returns the curated eSIM product catalog with per-caller pricing.\nCacheable for 60 seconds via `ETag` / `If-None-Match`.\n", "parameters": [ { "name": "countries", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated ISO-3166-1 alpha-2 country codes." }, { "name": "region", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "unlimited", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "min_data_gb", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "max_data_gb", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "min_validity_days", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "max_validity_days", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "supports_topup", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "has_5g", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "has_calls", "in": "query", "required": false, "description": "Filter to plans that include a phone number and calls (true) or data-only plans (false).", "schema": { "type": "boolean" } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "price_asc", "price_desc", "data_desc", "validity_desc" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IfNoneMatch" } ], "responses": { "200": { "description": "List of eSIM products.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EsimProductListEnvelope" } } } }, "304": { "description": "Not Modified." }, "401": { "$ref": "#/components/responses/UNAUTHENTICATED" }, "403": { "$ref": "#/components/responses/IP_NOT_ALLOWED" }, "429": { "$ref": "#/components/responses/RATE_LIMITED" }, "500": { "$ref": "#/components/responses/INTERNAL_ERROR" } } } }, "/esim_products/{id}": { "get": { "operationId": "getEsimProduct", "tags": [ "eSIM" ], "summary": "Get an eSIM product by id", "description": "Returns a single eSIM product from the catalog. Hidden products are\ntreated as non-existent. Cacheable for 60 seconds.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^prod_" } } ], "responses": { "200": { "description": "The eSIM product.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EsimProductEnvelope" } } } }, "401": { "$ref": "#/components/responses/UNAUTHENTICATED" }, "404": { "$ref": "#/components/responses/PRODUCT_NOT_FOUND" }, "429": { "$ref": "#/components/responses/RATE_LIMITED" }, "500": { "$ref": "#/components/responses/INTERNAL_ERROR" } } } }, "/esims": { "post": { "operationId": "createEsim", "tags": [ "eSIM" ], "summary": "Purchase an eSIM (or topup with parent_order_id)", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EsimCreateBody" } } } }, "responses": { "201": { "description": "Created. Returns the new eSIM order resource.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EsimEnvelope" } } } }, "202": { "description": "Accepted. eSIM is still provisioning. Poll `GET /esims/{id}` or wait for `esim.created` webhook.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EsimEnvelope" } } } }, "400": { "$ref": "#/components/responses/VALIDATION_ERROR" }, "401": { "$ref": "#/components/responses/UNAUTHENTICATED" }, "402": { "$ref": "#/components/responses/INSUFFICIENT_BALANCE" }, "404": { "description": "Not found. Body discriminates by `error.code`:\n- `PRODUCT_NOT_FOUND` - the `product_id` is unknown or hidden\n- `PARENT_ORDER_NOT_FOUND` - the `parent_order_id` does not exist or belongs to another user\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflicts. Body discriminates by `error.code`:\n- `IDEMPOTENCY_CONFLICT`, `IDEMPOTENCY_REPLAY_IN_FLIGHT`\n- `TOPUP_INCOMPATIBLE`, `PARENT_ORDER_NOT_ACTIVE`\n- `PRICE_OVER_CAP` - current price exceeds `max_price_cents`; see `PriceOverCapError`\n", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ErrorEnvelope" }, { "$ref": "#/components/schemas/PriceOverCapError" } ] } } } }, "429": { "$ref": "#/components/responses/RATE_LIMITED" }, "500": { "$ref": "#/components/responses/INTERNAL_ERROR" }, "502": { "$ref": "#/components/responses/PROVIDER_ERROR" }, "503": { "$ref": "#/components/responses/PRODUCT_UNAVAILABLE" } } }, "get": { "operationId": "listEsims", "tags": [ "eSIM" ], "summary": "List the caller's eSIM orders", "description": "Returns a cursor-paginated list of eSIM orders owned by the\nauthenticated caller. Results are sorted by order id, ascending. Up to\n100 items per page (default 50). Use `next_cursor` from the response to\nfetch the next page.\n", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "processing", "completed", "cancelled", "refunded", "expired" ] }, "description": "Filter by eSIM status." }, { "name": "is_topup", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "`true` to return only topup orders; `false` to return only base orders. Omit to return both." }, { "name": "created_after", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 timestamp. Return orders created at or after this time." }, { "name": "created_before", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 timestamp. Return orders created at or before this time." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Maximum number of results per page." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 64 }, "description": "Opaque pagination cursor from a previous response's `next_cursor`." } ], "responses": { "200": { "description": "Paginated list of eSIM orders.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EsimListEnvelope" } } } }, "401": { "$ref": "#/components/responses/UNAUTHENTICATED" }, "429": { "$ref": "#/components/responses/RATE_LIMITED" }, "500": { "$ref": "#/components/responses/INTERNAL_ERROR" } } } }, "/esims/{id}": { "get": { "operationId": "getEsim", "tags": [ "eSIM" ], "summary": "Get a single eSIM order by id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^esim_" } } ], "responses": { "200": { "description": "The eSIM order.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EsimEnvelope" } } } }, "401": { "$ref": "#/components/responses/UNAUTHENTICATED" }, "404": { "$ref": "#/components/responses/ESIM_NOT_FOUND" }, "429": { "$ref": "#/components/responses/RATE_LIMITED" }, "500": { "$ref": "#/components/responses/INTERNAL_ERROR" } } } }, "/esims/{id}/usage": { "get": { "operationId": "getEsimUsage", "tags": [ "eSIM" ], "summary": "Get live data usage for an eSIM", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^esim_" } } ], "responses": { "200": { "description": "Live usage data for the eSIM.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EsimUsageEnvelope" } } } }, "401": { "$ref": "#/components/responses/UNAUTHENTICATED" }, "404": { "$ref": "#/components/responses/ESIM_NOT_FOUND" }, "410": { "$ref": "#/components/responses/ESIM_GONE" }, "422": { "$ref": "#/components/responses/ESIM_NOT_ACTIVE" }, "429": { "$ref": "#/components/responses/RATE_LIMITED" }, "500": { "$ref": "#/components/responses/INTERNAL_ERROR" }, "502": { "$ref": "#/components/responses/PROVIDER_ERROR" }, "503": { "$ref": "#/components/responses/USAGE_UNAVAILABLE" } } } }, "/esims/{id}/qr.png": { "get": { "operationId": "getEsimQrPng", "tags": [ "eSIM" ], "summary": "Return the eSIM activation QR as a PNG image", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^esim_" } } ], "responses": { "200": { "description": "PNG image of the activation QR code", "content": { "image/png": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/UNAUTHENTICATED" }, "404": { "$ref": "#/components/responses/ESIM_NOT_FOUND" }, "429": { "$ref": "#/components/responses/RATE_LIMITED" }, "500": { "$ref": "#/components/responses/INTERNAL_ERROR" } } } }, "/esims/{id}/topups": { "get": { "operationId": "listEsimTopups", "tags": [ "eSIM" ], "summary": "List available topup products for an eSIM", "description": "Returns topup addon products available for the given eSIM's product\nfamily with compatible country coverage. If no topup is currently\navailable for the eSIM, returns `{ supports_topup: false, topups: [] }`.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^esim_" } } ], "responses": { "200": { "description": "Topup availability and addon list.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EsimTopupListEnvelope" } } } }, "401": { "$ref": "#/components/responses/UNAUTHENTICATED" }, "404": { "$ref": "#/components/responses/ESIM_NOT_FOUND" }, "429": { "$ref": "#/components/responses/RATE_LIMITED" }, "500": { "$ref": "#/components/responses/INTERNAL_ERROR" } } }, "post": { "operationId": "createEsimTopup", "tags": [ "eSIM" ], "summary": "Purchase a topup for an existing eSIM", "description": "Convenience endpoint that forwards to `POST /esims` with\n`parent_order_id` set to this eSIM's id. The path value takes\nprecedence over any `parent_order_id` in the request body.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^esim_" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EsimCreateBody" } } } }, "responses": { "201": { "description": "Topup purchased. Returns the new eSIM topup order.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EsimEnvelope" } } } }, "202": { "description": "Accepted. Topup is still provisioning.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EsimEnvelope" } } } }, "400": { "$ref": "#/components/responses/VALIDATION_ERROR" }, "401": { "$ref": "#/components/responses/UNAUTHENTICATED" }, "402": { "$ref": "#/components/responses/INSUFFICIENT_BALANCE" }, "404": { "$ref": "#/components/responses/PRODUCT_NOT_FOUND" }, "409": { "description": "Conflicts. Body discriminates by `error.code`:\n- `IDEMPOTENCY_CONFLICT`, `IDEMPOTENCY_REPLAY_IN_FLIGHT`\n- `TOPUP_INCOMPATIBLE`, `PARENT_ORDER_NOT_ACTIVE`\n- `PRICE_OVER_CAP` - current price exceeds `max_price_cents`; see `PriceOverCapError`\n", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ErrorEnvelope" }, { "$ref": "#/components/schemas/PriceOverCapError" } ] } } } }, "429": { "$ref": "#/components/responses/RATE_LIMITED" }, "500": { "$ref": "#/components/responses/INTERNAL_ERROR" }, "502": { "$ref": "#/components/responses/PROVIDER_ERROR" }, "503": { "$ref": "#/components/responses/PRODUCT_UNAVAILABLE" } } } }, "/verifications": { "post": { "operationId": "createVerification", "tags": [ "Verifications" ], "summary": "Create a verification", "description": "Rents a phone number for one inbound SMS. Idempotent by\n`Idempotency-Key`.\n\n## Caps\n\nSMS pricing drifts. Set `max_price_cents` to opt into \"always get a\nnumber\" behaviour: any drift up to your cap charges silently and the\nactual amount appears as `charged_price_cents` on the response. Omit\n`max_price_cents` to lock in exactly the price you saw on\n`GET /v1/services`.\n\n## Price over cap\n\nIf the lowest available price is above your `max_price_cents`, the API\nreturns **`409 PRICE_OVER_CAP`** with both values in the error details:\n\n```json\n{\n \"success\": false,\n \"error\": {\n \"code\": \"PRICE_OVER_CAP\",\n \"details\": {\n \"max_price_cents\": 35,\n \"available_price_cents\": 42\n }\n }\n}\n```\n\nNo partial state is created and no funds are touched. Decide locally\nwhether to retry with a higher cap or surface the price to the user.\n", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVerificationRequest" } } } }, "responses": { "201": { "description": "Verification created. `status` is always `waiting_for_code` at this point.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "verification" ], "properties": { "verification": { "$ref": "#/components/schemas/Verification" } } } } } ] } } } }, "400": { "$ref": "#/components/responses/VALIDATION_ERROR" }, "401": { "$ref": "#/components/responses/UNAUTHENTICATED" }, "402": { "$ref": "#/components/responses/INSUFFICIENT_BALANCE" }, "403": { "$ref": "#/components/responses/FORBIDDEN" }, "404": { "$ref": "#/components/responses/SERVICE_NOT_FOUND" }, "409": { "description": "Conflicts. Body discriminates by `error.code`:\n- `IDEMPOTENCY_CONFLICT` - same key, different body\n- `IDEMPOTENCY_REPLAY_IN_FLIGHT` - duplicate while original processes\n- `PRICE_OVER_CAP` - lowest available price exceeds `max_price_cents`; see `PriceOverCapError`\n", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ErrorEnvelope" }, { "$ref": "#/components/schemas/PriceOverCapError" } ] } } } }, "429": { "$ref": "#/components/responses/RATE_LIMITED" }, "500": { "$ref": "#/components/responses/INTERNAL_ERROR" }, "503": { "$ref": "#/components/responses/SERVICE_OUT_OF_STOCK" } } }, "get": { "operationId": "listVerifications", "tags": [ "Verifications" ], "summary": "List the caller's verifications", "description": "Returns a cursor-paginated list of short-term verifications owned by\nthe authenticated caller, newest-first. Up to 100 items per page\n(default 20). Use `next_cursor` from the response to fetch the next\npage. Long-term rentals are not included - use `GET /v1/rentals`.\n", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "waiting_for_code", "code_received", "cancelled", "expired" ] }, "description": "Filter by verification status." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Maximum number of results per page." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 64 }, "description": "Opaque pagination cursor from a previous response's `next_cursor`." } ], "responses": { "200": { "description": "Paginated list of verifications.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationListResponse" } } } }, "400": { "$ref": "#/components/responses/VALIDATION_ERROR" }, "401": { "$ref": "#/components/responses/UNAUTHENTICATED" }, "429": { "$ref": "#/components/responses/RATE_LIMITED" } } } }, "/verifications/{id}": { "get": { "operationId": "getVerification", "tags": [ "Verifications" ], "summary": "Get a verification by id", "description": "Poll the verification's current state. Uses the generous\n`verifications_read` rate-limit bucket - safe to poll every few\nseconds. Prefer webhooks for production use.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/VerificationId" } } ], "responses": { "200": { "description": "Current state of the verification.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "verification" ], "properties": { "verification": { "$ref": "#/components/schemas/Verification" } } } } } ] } } } }, "401": { "$ref": "#/components/responses/UNAUTHENTICATED" }, "404": { "$ref": "#/components/responses/VERIFICATION_NOT_FOUND" }, "429": { "$ref": "#/components/responses/RATE_LIMITED" } } } }, "/verifications/{id}/messages": { "get": { "operationId": "listVerificationMessages", "tags": [ "Verifications" ], "summary": "List all SMS received on a verification", "description": "Returns every SMS the number has received, newest first. The number can\nreceive several distinct codes over its life (the line is auto-reused\nduring the window), so this is the way to retrieve the full set rather\nthan just the latest `code` on the verification resource.\n\nIncludes ambient SMS with no extractable code (`code: null`). Uses the\ngenerous `verifications_read` rate-limit bucket. Capped at the 200 most\nrecent messages.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/VerificationId" } } ], "responses": { "200": { "description": "All messages received on the number, newest first.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "messages" ], "properties": { "messages": { "type": "array", "items": { "$ref": "#/components/schemas/VerificationMessage" } } } } } } ] } } } }, "401": { "$ref": "#/components/responses/UNAUTHENTICATED" }, "404": { "$ref": "#/components/responses/VERIFICATION_NOT_FOUND" }, "429": { "$ref": "#/components/responses/RATE_LIMITED" } } } }, "/verifications/{id}/cancel": { "post": { "operationId": "cancelVerification", "tags": [ "Verifications" ], "summary": "Cancel a pending verification", "description": "Cancels a verification that has not yet received a code. The number is\nreleased and the wallet is refunded atomically in the same database\ntransaction.\n\nCancellation is only valid while `can_cancel: true` on the\nverification. Once a code arrives the call returns\n`409 CANCEL_NOT_ALLOWED`.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/VerificationId" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Verification cancelled; refunded amount included.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "verification" ], "properties": { "verification": { "type": "object", "required": [ "id", "status", "refunded_cents" ], "properties": { "id": { "$ref": "#/components/schemas/VerificationId" }, "status": { "type": "string", "enum": [ "cancelled" ] }, "refunded_cents": { "type": "integer", "description": "Amount returned to the wallet." } } } } } } } ] } } } }, "400": { "$ref": "#/components/responses/VALIDATION_ERROR" }, "401": { "$ref": "#/components/responses/UNAUTHENTICATED" }, "404": { "$ref": "#/components/responses/VERIFICATION_NOT_FOUND" }, "409": { "description": "Idempotency conflict OR the verification can no longer be cancelled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RATE_LIMITED" } } } }, "/verifications/{id}/complete": { "post": { "operationId": "completeVerification", "tags": [ "Verifications" ], "summary": "Mark a verification as done", "description": "Marks a verification as complete and moves it out of the active\ndashboard list into history. Local-only status flip - no refund, no\nexternal call, no balance movement. Use this when your integration\nhas consumed the code and you no longer want the verification taking\nup space in the active view.\n\nValid while the verification is in `waiting_for_code` or\n`code_received` state, or when it has expired without a code. Once\nexplicitly completed (or cancelled), the call returns\n`409 COMPLETE_NOT_ALLOWED`.\n\nCompletion is optional - verifications automatically leave the\nactive list when their rental window expires (~15 min). This\nendpoint just lets bulk callers tidy up sooner.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/VerificationId" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Verification marked complete.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "verification" ], "properties": { "verification": { "type": "object", "required": [ "id", "status" ], "properties": { "id": { "$ref": "#/components/schemas/VerificationId" }, "status": { "type": "string", "enum": [ "code_received" ] } } } } } } } ] } } } }, "400": { "$ref": "#/components/responses/VALIDATION_ERROR" }, "401": { "$ref": "#/components/responses/UNAUTHENTICATED" }, "404": { "$ref": "#/components/responses/VERIFICATION_NOT_FOUND" }, "409": { "description": "Idempotency conflict OR the verification can no longer be completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RATE_LIMITED" } } } }, "/verifications/{id}/reuse": { "post": { "operationId": "reuseVerificationFree", "tags": [ "Verifications" ], "summary": "Free reuse of a verification that already received a code", "description": "Re-arms the same number to receive another SMS while the rental's\nwindow is still open. Free because the original rental still owns the\nnumber.\n\nCallers should check `allow_reuse` on the verification resource before\ncalling. The rental may have transitioned states between your last GET\nand this call - in that case the API returns\n`409 REUSE_NOT_ALLOWED`. Per-rental cooldown is 30 seconds.\n\nReuse is not supported on every catalog service. When unavailable the\nAPI returns `409 NOT_SUPPORTED`; check `allow_reuse` on the verification\nfirst to skip the round trip.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/VerificationId" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Reuse successful; the verification resource is re-armed and ready for a new code.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "verification" ], "properties": { "verification": { "$ref": "#/components/schemas/Verification" } } } } } ] } } } }, "400": { "$ref": "#/components/responses/VALIDATION_ERROR" }, "401": { "$ref": "#/components/responses/UNAUTHENTICATED" }, "404": { "$ref": "#/components/responses/VERIFICATION_NOT_FOUND" }, "409": { "$ref": "#/components/responses/REUSE_NOT_ALLOWED" }, "422": { "$ref": "#/components/responses/NOT_SUPPORTED" }, "429": { "$ref": "#/components/responses/REUSE_RATE_LIMITED" } } } }, "/verifications/{id}/reuse/paid": { "post": { "operationId": "reuseVerificationPaid", "tags": [ "Verifications" ], "summary": "Paid reuse of an expired or completed verification", "description": "Reclaims a number from the available pool by charging a fixed\n`paid_reuse_price_cents` (currently 50 = $0.50). The charge happens\natomically; on any failure (number left the pool, eligibility closed)\nthe wallet is refunded and the call returns `409 REUSE_NOT_ALLOWED`.\n\nYou **must** send `accept_charge_cents` in the body matching the\ncurrent `paid_reuse_price_cents` - this is an explicit consent guard\nagainst accidental charges. Read the value off the verification\nresource instead of hardcoding.\n\nAfter a paid reuse `allow_paid_reuse` flips to `false`; it re-arms once\nthe number reaches the next eligible state transition (the reused rental\nexpires, is confirmed, or receives a message), at which point a further\npaid reuse becomes available again - best-effort.\n\nPer-rental cooldown is 30 seconds. LTR rentals must re-rent through\nthe create endpoint instead.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/VerificationId" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaidReuseRequest" } } } }, "responses": { "200": { "description": "Paid reuse successful. `charged_reuse_cents` reflects what was deducted.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "verification" ], "properties": { "verification": { "$ref": "#/components/schemas/Verification" } } } } } ] } } } }, "400": { "$ref": "#/components/responses/VALIDATION_ERROR" }, "401": { "$ref": "#/components/responses/UNAUTHENTICATED" }, "402": { "$ref": "#/components/responses/INSUFFICIENT_BALANCE" }, "404": { "$ref": "#/components/responses/VERIFICATION_NOT_FOUND" }, "409": { "$ref": "#/components/responses/REUSE_NOT_ALLOWED" }, "422": { "$ref": "#/components/responses/NOT_SUPPORTED" }, "429": { "$ref": "#/components/responses/REUSE_RATE_LIMITED" } } } }, "/rentals": { "post": { "operationId": "createRental", "tags": [ "Rentals" ], "summary": "Create a long-term rental", "description": "Reserves a dedicated phone number for a fixed duration (3, 7, 14, or 30\ndays). All incoming SMS messages are collected and accessible via\n`GET /v1/rentals/{id}`. Idempotent by `Idempotency-Key`.\n\n## Price over cap\n\nLTR pricing can drift. If the lowest available price exceeds your\n`max_price_cents` ceiling at request time, the API returns\n**`409 PRICE_OVER_CAP`** with both values in the error details:\n\n```json\n{\n \"success\": false,\n \"error\": {\n \"code\": \"PRICE_OVER_CAP\",\n \"details\": {\n \"max_price_cents\": 1500,\n \"available_price_cents\": 1750\n }\n }\n}\n```\n\nNo partial state is created and no funds are touched. Decide locally\nwhether to retry with a higher cap or surface the price to the user.\n\n## Duration\n\n`duration` must be one of `3D`, `7D`, `14D`, or `30D`. Only\n`country=\"us\"` is currently supported.\n\n## Auto-renew\n\nSet `auto_renew: true` to automatically charge the same duration at\nexpiry. Toggle at any time via `POST /v1/rentals/{id}/auto_renew`.\n", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RentalCreateRequest" } } } }, "responses": { "201": { "description": "Rental created. `status` is `active` immediately.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Rental" } } } ] } } } }, "400": { "$ref": "#/components/responses/VALIDATION_ERROR" }, "401": { "$ref": "#/components/responses/UNAUTHENTICATED" }, "402": { "$ref": "#/components/responses/INSUFFICIENT_BALANCE" }, "403": { "$ref": "#/components/responses/FORBIDDEN" }, "404": { "description": "Not found. Body discriminates by `error.code`:\n- `SERVICE_NOT_FOUND` - unknown service id\n- `LTR_NOT_AVAILABLE` - service does not offer the requested duration\n- `WEBHOOK_ENDPOINT_NOT_FOUND` - `webhook_endpoint_id` is unknown or belongs to another user\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflicts. Body discriminates by `error.code`:\n- `IDEMPOTENCY_CONFLICT` - same key, different body\n- `IDEMPOTENCY_REPLAY_IN_FLIGHT` - duplicate while original processes\n- `PRICE_OVER_CAP` - lowest available price exceeds `max_price_cents`; see `PriceOverCapError`\n", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ErrorEnvelope" }, { "$ref": "#/components/schemas/PriceOverCapError" } ] } } } }, "429": { "$ref": "#/components/responses/RATE_LIMITED" }, "500": { "$ref": "#/components/responses/INTERNAL_ERROR" }, "502": { "$ref": "#/components/responses/PROVIDER_ERROR" }, "503": { "$ref": "#/components/responses/SERVICE_OUT_OF_STOCK" }, "504": { "$ref": "#/components/responses/PROVIDER_TIMEOUT" } } }, "get": { "operationId": "listRentals", "tags": [ "Rentals" ], "summary": "List the caller's long-term rentals", "description": "Returns a cursor-paginated list of long-term rentals owned by the\nauthenticated caller. Results are sorted newest-first. Up to 100 items\nper page (default 20). Use `next_cursor` from the response to fetch\nthe next page.\n", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "expired", "cancelled" ] }, "description": "Filter by rental status." }, { "name": "duration", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "3D", "7D", "14D", "30D" ] }, "description": "Filter by duration." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Maximum number of results per page." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 64 }, "description": "Opaque pagination cursor from a previous response's `next_cursor`." } ], "responses": { "200": { "description": "Paginated list of rentals.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RentalListResponse" } } } }, "400": { "$ref": "#/components/responses/VALIDATION_ERROR" }, "401": { "$ref": "#/components/responses/UNAUTHENTICATED" }, "429": { "$ref": "#/components/responses/RATE_LIMITED" } } } }, "/rentals/{id}": { "get": { "operationId": "getRental", "tags": [ "Rentals" ], "summary": "Get a long-term rental by id", "description": "Returns the full rental resource including all received messages. Poll\nevery few seconds during active rentals; prefer webhooks for production\nuse.\n\nUse the `messages_limit` and `messages_before` query parameters to page\nthrough older messages when there are many.\n", "parameters": [ { "$ref": "#/components/parameters/RentalId" }, { "name": "messages_limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Maximum number of messages to include." }, { "name": "messages_before", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 64 }, "description": "Opaque message cursor. Returns messages older than this id." } ], "responses": { "200": { "description": "Current state of the rental including messages.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Rental" } } } ] } } } }, "401": { "$ref": "#/components/responses/UNAUTHENTICATED" }, "404": { "$ref": "#/components/responses/NOT_FOUND" }, "429": { "$ref": "#/components/responses/RATE_LIMITED" } } }, "delete": { "operationId": "cancelRental", "tags": [ "Rentals" ], "summary": "Cancel a long-term rental", "description": "Cancels an active rental and issues a wallet refund. Cancellation is\nonly available within the first hour after creation (`can_cancel:\ntrue`). Once the cancel window has passed or the rental is no longer\nactive, the call returns `409 CANCEL_NOT_ALLOWED`.\n\n`Idempotency-Key` is required: a network retry on a successful cancel\nreplays the cached `200` instead of returning `CANCEL_NOT_ALLOWED`\nagainst the now-cancelled rental. Reusing the same key for a different\nrental returns `409 IDEMPOTENCY_CONFLICT`.\n\nOn success the rental's `status` transitions to `cancelled` and a\n`rental.cancelled` webhook event is dispatched.\n", "parameters": [ { "$ref": "#/components/parameters/RentalId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Rental cancelled.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Rental" } } } ] } } } }, "400": { "$ref": "#/components/responses/VALIDATION_ERROR" }, "401": { "$ref": "#/components/responses/UNAUTHENTICATED" }, "404": { "$ref": "#/components/responses/NOT_FOUND" }, "409": { "description": "Conflict. Body discriminates by `error.code`:\n- `CANCEL_NOT_ALLOWED` - rental is past the cancel window or already terminal\n- `IDEMPOTENCY_CONFLICT` - same `Idempotency-Key` reused with a different rental id\n- `IDEMPOTENCY_REPLAY_IN_FLIGHT` - original cancel call is still processing; retry after `Retry-After`\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RATE_LIMITED" }, "500": { "$ref": "#/components/responses/INTERNAL_ERROR" } } } }, "/rentals/{id}/re_rent": { "post": { "operationId": "reRentRental", "tags": [ "Rentals" ], "summary": "Re-rent an expired LTR number", "description": "Purchases a fresh rental period on the same phone number at the current\nre-rent price. Only call when `re_rent_available: true` on the rental\nresource.\n\nNo request body. `Idempotency-Key` is optional but recommended to guard\nagainst network retries triggering a double charge.\n\n### 410 semantics\n\nA `410 RE_RENT_NOT_AVAILABLE` response means the number has been permanently\nreleased. **Stop retrying**; `re_rent_available`\nwill be `false` on subsequent fetches. Offer the user a fresh rental via\n`POST /v1/rentals` instead.\n", "parameters": [ { "$ref": "#/components/parameters/RentalId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Re-rent succeeded. Returns the updated rental resource with the new\n`expires_at` and `paid_until`. `status` transitions back to `active`.\n", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Rental" } } } ] } } } }, "401": { "$ref": "#/components/responses/UNAUTHENTICATED" }, "402": { "$ref": "#/components/responses/INSUFFICIENT_BALANCE" }, "404": { "$ref": "#/components/responses/NOT_FOUND" }, "410": { "description": "The number is no longer available for re-rent - it has been\nreleased. `error.code` is `RE_RENT_NOT_AVAILABLE`. Stop retrying\nand offer a fresh rental instead.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RATE_LIMITED" }, "500": { "$ref": "#/components/responses/INTERNAL_ERROR" }, "502": { "$ref": "#/components/responses/PROVIDER_ERROR" } } } }, "/rentals/{id}/auto_renew": { "post": { "operationId": "setRentalAutoRenew", "tags": [ "Rentals" ], "summary": "Enable or disable auto-renew on a rental", "description": "Sets the `auto_renew` flag to an explicit state. Unlike a toggle,\ncalling with the same `enabled` value twice is safe (idempotent by\nconstruction). No `Idempotency-Key` header is required.\n\nWhen `enabled: true`, the rental will automatically renew for the same\nduration at expiry. When `enabled: false`, the rental expires normally\nwhen `expires_at` is reached.\n\nReturns `400 VALIDATION_ERROR` if the rental has already expired.\n", "parameters": [ { "$ref": "#/components/parameters/RentalId" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional on this endpoint. The body is an explicit state setter, so\nrepeated calls with the same `enabled` value are no-ops at the\nbackend regardless of this header. Include one if your client\nuniformly tags every mutation - it is accepted but not enforced.\n", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RentalAutoRenewRequest" } } } }, "responses": { "200": { "description": "Auto-renew preference updated. Returns the updated rental.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Rental" } } } ] } } } }, "400": { "$ref": "#/components/responses/VALIDATION_ERROR" }, "401": { "$ref": "#/components/responses/UNAUTHENTICATED" }, "404": { "$ref": "#/components/responses/NOT_FOUND" }, "429": { "$ref": "#/components/responses/RATE_LIMITED" }, "500": { "$ref": "#/components/responses/INTERNAL_ERROR" }, "502": { "$ref": "#/components/responses/PROVIDER_ERROR" } } } }, "/proxy_plans": { "get": { "operationId": "listProxyPlans", "tags": [ "Plans" ], "summary": "List proxy plans", "description": "Returns active proxy plans with per-user quoted pricing. Plans\nwithout a public id are filtered out.\n\nWithout `type`, only mobile/GB (`shared`) plans are returned and the\nresponse has no `next_cursor` (the original response). With `type`,\nStandard dedicated plans can be included, plans come back in a stable\norder, and `next_cursor` pages through them. Premium dedicated plans\nare never listed.\n", "parameters": [ { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "shared", "dedicated_standard", "all" ] }, "description": "Plan types to list. `all` is shared + Standard dedicated." }, { "$ref": "#/components/parameters/CountryQuery" }, { "name": "min_gb", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Filter to plans with at least this many GB included. Any value above 0 excludes dedicated plans." }, { "name": "period", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "daily", "weekly", "monthly" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 } }, { "name": "available", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "With `type`, `true` returns only plans available right now." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "With `type`, the `next_cursor` from the previous page." } ], "responses": { "200": { "description": "List of plans.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "plans" ], "properties": { "plans": { "type": "array", "items": { "$ref": "#/components/schemas/ProxyPlan" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Present only when `type` was passed. Null on the last page." } } } } } ] } } } }, "400": { "$ref": "#/components/responses/VALIDATION_ERROR" }, "401": { "$ref": "#/components/responses/UNAUTHENTICATED" }, "429": { "$ref": "#/components/responses/RATE_LIMITED" }, "500": { "$ref": "#/components/responses/INTERNAL_ERROR" } } } }, "/proxy_plans/{id}": { "get": { "operationId": "getProxyPlan", "tags": [ "Plans" ], "summary": "Get one proxy plan", "description": "One plan - mobile/GB or Standard dedicated - in the same shape as the\nlist, with your quoted price and, for a Standard plan, its current\navailability. Use it to refresh a quote right before buying. Premium,\nretired and unknown plans are not found.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ProxyPlanId" } } ], "responses": { "200": { "description": "The plan.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "plan" ], "properties": { "plan": { "$ref": "#/components/schemas/ProxyPlan" } } } } } ] } } } }, "401": { "$ref": "#/components/responses/UNAUTHENTICATED" }, "404": { "description": "PROXY_PLAN_NOT_FOUND - unknown, retired or Premium plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RATE_LIMITED" } } } }, "/proxies": { "post": { "operationId": "createProxy", "tags": [ "Proxies" ], "summary": "Purchase a proxy package", "description": "Buys a mobile/GB proxy package or a Standard dedicated proxy, either\nby `plan_id` (charged to the wallet) or by `pool_id` (a mobile/GB\nsub-order drawn from a reseller GB pool the caller owns - see the\n`Proxy pools` tag). Provide exactly one of `plan_id` or `pool_id`.\nReturns **`202 Accepted`**. A mobile/GB package comes back\n`status: provisioning` and becomes active within 1-2 minutes. A\nStandard dedicated proxy comes back `active` with its `gateway` when\nthe modem is issued immediately, otherwise `provisioning` (settled\nwithin about 5 minutes). The `proxy.ready` webhook fires when the\norder becomes active; `proxy.provisioning_failed` (with the refund)\nif it cannot be provisioned.\n\nFor a Standard dedicated plan, nothing is charged unless the plan is\nstill available: a sold-out plan returns `503 SERVICE_OUT_OF_STOCK`\nand a price above `max_price_cents` returns `409 PRICE_MISMATCH`,\nboth before any charge. Premium dedicated plans are not available\nover the API.\n\nWallet deduction and refund-on-failure are atomic for a `plan_id`\npurchase. A `pool_id` purchase never touches the wallet - GB is drawn\nfrom the pool's ledger and returned to it if provisioning fails.\n", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProxyRequest" } } } }, "responses": { "202": { "description": "Proxy purchase accepted. Wait for `proxy.ready` or poll `GET /v1/proxies/:id`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "proxy" ], "properties": { "proxy": { "$ref": "#/components/schemas/Proxy" } } } } } ] } } } }, "400": { "$ref": "#/components/responses/VALIDATION_ERROR" }, "401": { "$ref": "#/components/responses/UNAUTHENTICATED" }, "402": { "$ref": "#/components/responses/INSUFFICIENT_BALANCE" }, "404": { "description": "Not found - PROXY_PLAN_NOT_FOUND (`plan_id`) or POOL_NOT_FOUND (`pool_id`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict - IDEMPOTENCY_CONFLICT, IDEMPOTENCY_REPLAY_IN_FLIGHT, PRICE_MISMATCH, PROXY_NOT_READY, POOL_LAPSED, or POOL_INSUFFICIENT_GB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RATE_LIMITED" }, "502": { "$ref": "#/components/responses/PROVISIONING_FAILED" }, "503": { "$ref": "#/components/responses/SERVICE_OUT_OF_STOCK" }, "504": { "$ref": "#/components/responses/PROVIDER_TIMEOUT" } } }, "get": { "operationId": "listProxies", "tags": [ "Proxies" ], "summary": "List the caller's proxy packages", "description": "Returns a cursor-paginated list of proxy packages owned by the\nauthenticated caller. Up to 100 items per page (default 50). Use\n`next_cursor` from the response to fetch the next page.\n\nFilters are AND-combined. `status` is repeatable; the others accept a\nsingle value.\n", "parameters": [ { "name": "status", "in": "query", "required": false, "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "active", "provisioning", "expired", "exhausted", "refunded" ] } }, "description": "Filter by package status. Repeat the param to combine values." }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "shared", "dedicated_standard", "dedicated_premium" ] }, "description": "Filter by package type." }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "minLength": 2, "maxLength": 2 }, "description": "2-letter ISO country code. Matched against dedicated-proxy country only." }, { "name": "pool_id", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ProxyPoolId" }, "description": "Restrict to sub-orders minted from a single GB pool." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Maximum number of results per page." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 64 }, "description": "Opaque pagination cursor from a previous response's `next_cursor`." } ], "responses": { "200": { "description": "Paginated list of proxy packages.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "proxies", "next_cursor" ], "properties": { "proxies": { "type": "array", "items": { "$ref": "#/components/schemas/Proxy" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` in the next request to advance the page. Null on the last page." } } } } } ] } } } }, "400": { "$ref": "#/components/responses/VALIDATION_ERROR" }, "401": { "$ref": "#/components/responses/UNAUTHENTICATED" }, "429": { "$ref": "#/components/responses/RATE_LIMITED" }, "500": { "$ref": "#/components/responses/INTERNAL_ERROR" } } } }, "/proxies/{id}": { "get": { "operationId": "getProxy", "tags": [ "Proxies" ], "summary": "Get a proxy package by id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ProxyId" } } ], "responses": { "200": { "description": "The proxy package, including gateway creds (if provisioned) and all lists.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "proxy" ], "properties": { "proxy": { "$ref": "#/components/schemas/Proxy" } } } } } ] } } } }, "401": { "$ref": "#/components/responses/UNAUTHENTICATED" }, "404": { "$ref": "#/components/responses/PROXY_NOT_FOUND" }, "429": { "$ref": "#/components/responses/RATE_LIMITED" } } } }, "/proxies/{id}/usage": { "get": { "operationId": "getProxyUsage", "tags": [ "Proxies" ], "summary": "Live traffic usage for a proxy package", "description": "Returns daily / weekly / monthly / total / remaining byte counters.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ProxyId" } } ], "responses": { "200": { "description": "Usage counters.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "usage" ], "properties": { "usage": { "$ref": "#/components/schemas/ProxyUsage" } } } } } ] } } } }, "401": { "$ref": "#/components/responses/UNAUTHENTICATED" }, "404": { "$ref": "#/components/responses/PROXY_NOT_FOUND" } } } }, "/proxies/{id}/renew": { "post": { "operationId": "renewProxy", "tags": [ "Proxies" ], "summary": "Re-buy the plan on a package (adds a full plan of GB and one period)", "description": "Adds one full plan allocation of GB on top of whatever is left and\nextends `expires_at` by one plan period (from now if the package had\nalready lapsed). Accepted on `active`, `exhausted`, and `expired`\npackages within 7 days of expiry; the package is `active` afterwards\nand the traffic webhooks are re-armed. Charged at the plan's current\nprice; refunded automatically on failure.\n\nOn a pool-backed sub-order (`proxy.pool_id` set), renew instead\nre-allocates the sub-order's **original** GB and duration from the\npool - not one plan period - at no incremental wallet charge.\n`max_price_cents` is ignored. See the `Proxy pools` tag.\n\nOn a Standard dedicated proxy, renew extends an `active` proxy by one\nterm of its own plan, from the current `expires_at`, at the price it\nwas bought at with your current discount. `max_price_cents` is\nrequired and checked before charging. An expired dedicated proxy\ncannot be renewed (`409 PROXY_EXPIRED`); a Premium one returns\n`422 NOT_SUPPORTED`. `proxy.renewed` fires on success.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ProxyId" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenewProxyRequest" } } } }, "responses": { "200": { "description": "Renewed; new `expires_at` reflected on the proxy. `pool_gb_charged` is present when the order is pool-backed.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "proxy" ], "properties": { "proxy": { "$ref": "#/components/schemas/Proxy" }, "pool_gb_charged": { "type": "integer", "description": "GB drawn from the pool for this renewal. Present only when `proxy.pool_id` is set." } } } } } ] } } } }, "400": { "$ref": "#/components/responses/VALIDATION_ERROR" }, "402": { "$ref": "#/components/responses/INSUFFICIENT_BALANCE" }, "404": { "$ref": "#/components/responses/PROXY_NOT_FOUND" }, "409": { "description": "Conflict - PRICE_MISMATCH (catalog or dedicated), PROXY_EXPIRED / PROXY_NOT_READY, or POOL_LAPSED / POOL_INSUFFICIENT_GB (pool-backed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "$ref": "#/components/responses/NOT_SUPPORTED" }, "502": { "$ref": "#/components/responses/PROVISIONING_FAILED" } } } }, "/proxies/{id}/auto_renew": { "post": { "operationId": "setProxyAutoRenew", "tags": [ "Proxies" ], "summary": "Turn auto-renew on or off for a Standard dedicated proxy", "description": "Sets auto-renew to the given state. With auto-renew on, the proxy is\nrenewed for one more term of its plan about 12 hours before\n`expires_at`, charged to your wallet at the same price a manual renew\nwould charge; `proxy.renewed` fires when it lands. If your balance is\ntoo low it retries until expiry, then the proxy expires and\n`proxy.expired` fires.\n\nSetting the current state again is a no-op, so the call is safe to\nretry and needs no `Idempotency-Key`. Turning auto-renew on requires\nan `active` proxy; turning it off always succeeds. Mobile/GB\npackages and Premium dedicated proxies return `422 NOT_SUPPORTED`.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ProxyId" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "enabled" ], "additionalProperties": false, "properties": { "enabled": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Auto-renew set; see `proxy.auto_renew`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "proxy" ], "properties": { "proxy": { "$ref": "#/components/schemas/Proxy" } } } } } ] } } } }, "400": { "$ref": "#/components/responses/VALIDATION_ERROR" }, "401": { "$ref": "#/components/responses/UNAUTHENTICATED" }, "404": { "$ref": "#/components/responses/PROXY_NOT_FOUND" }, "409": { "description": "Conflict - PROXY_EXPIRED or PROXY_NOT_READY (turning auto-renew on).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "$ref": "#/components/responses/NOT_SUPPORTED" }, "429": { "$ref": "#/components/responses/RATE_LIMITED" } } } }, "/proxies/{id}/topup": { "post": { "operationId": "topupProxy", "tags": [ "Proxies" ], "summary": "Add GB to a proxy package", "description": "Prorated from the plan's per-GB price. Accepted on `active`,\n`exhausted`, and `expired` packages within 7 days of expiry; a\nsuccessful top-up leaves the package `active` and re-arms the\n`proxy.traffic_low` / `proxy.traffic_exhausted` webhooks. Expiry grows\nin proportion to the GB added, from the current expiry or from now if\nthe package had lapsed.\n\nOn a pool-backed sub-order (`proxy.pool_id` set), the GB is drawn from\nthe pool instead of the wallet and `max_price_cents` is ignored. See\nthe `Proxy pools` tag.\n\nDedicated proxies are unmetered and return `422 NOT_SUPPORTED`.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ProxyId" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TopupProxyRequest" } } } }, "responses": { "200": { "description": "GB added; new totals reflected on the proxy. `pool_gb_charged` is present when the order is pool-backed.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "proxy" ], "properties": { "proxy": { "$ref": "#/components/schemas/Proxy" }, "pool_gb_charged": { "type": "integer", "description": "GB drawn from the pool for this top-up. Present only when `proxy.pool_id` is set." } } } } } ] } } } }, "400": { "$ref": "#/components/responses/VALIDATION_ERROR" }, "402": { "$ref": "#/components/responses/INSUFFICIENT_BALANCE" }, "404": { "$ref": "#/components/responses/PROXY_NOT_FOUND" }, "409": { "description": "Conflict - PRICE_MISMATCH (catalog), or POOL_LAPSED / POOL_INSUFFICIENT_GB (pool-backed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "$ref": "#/components/responses/NOT_SUPPORTED" } } } }, "/proxies/{id}/regenerate_password": { "post": { "operationId": "regenerateProxyPassword", "tags": [ "Proxies" ], "summary": "Rotate the package-level gateway password", "description": "Rotates the Flex mode gateway password. The gateway must have been\ninitialized via `POST /v1/proxies/:id/flex_credentials` first;\notherwise this returns `409 PROXY_NOT_READY` with a message pointing\nat that endpoint.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ProxyId" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Rotated. New credentials are on `proxy.gateway`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "proxy" ], "properties": { "proxy": { "$ref": "#/components/schemas/Proxy" } } } } } ] } } } }, "404": { "$ref": "#/components/responses/PROXY_NOT_FOUND" }, "409": { "$ref": "#/components/responses/PROXY_NOT_READY" } } } }, "/proxies/{id}/rotate_ip": { "post": { "operationId": "rotateProxyIp", "tags": [ "Proxies" ], "summary": "Rotate the proxy's exit IP", "description": "Triggers an IP rotation for a dedicated proxy. Each call requests a\nfresh exit IP; the modem typically reflects the new address within a\nfew seconds. Subsequent reads of `GET /v1/proxies/{id}` will show\nthe updated `current_ip` once the rotation lands.\n\nConstraints:\n- Only dedicated proxies support this endpoint. Calling it on a\n shared (gb) proxy returns `422 NOT_SUPPORTED`.\n- The proxy must be `status: active`, else `409 PROXY_NOT_READY`.\n- Hard cooldown of 60 seconds per proxy, independent of the API\n key's rate-limit bucket. Each proxy has its own cooldown bucket -\n rotating proxy A does not block rotating proxy B. Excess calls\n on the same proxy return `429 RATE_LIMITED`.\n\nThis endpoint is not idempotent by design; each successful call\nproduces a different IP. `Idempotency-Key` is not honored.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ProxyId" } } ], "responses": { "200": { "description": "Rotation accepted. `current_ip` is best-effort and may be `null` if the modem hasn't reported the new address yet.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "proxy_id", "rotated_at", "current_ip" ], "properties": { "proxy_id": { "$ref": "#/components/schemas/ProxyId" }, "rotated_at": { "type": "string", "format": "date-time" }, "current_ip": { "type": [ "string", "null" ], "description": "Newly assigned IPv4/IPv6 if known, else null. Poll `GET /v1/proxies/{id}` until populated." } } } } } ] } } } }, "404": { "$ref": "#/components/responses/PROXY_NOT_FOUND" }, "409": { "$ref": "#/components/responses/PROXY_NOT_READY" }, "422": { "$ref": "#/components/responses/NOT_SUPPORTED" }, "429": { "$ref": "#/components/responses/RATE_LIMITED" }, "502": { "$ref": "#/components/responses/PROVIDER_ERROR" } } } }, "/proxies/{id}/flex_credentials": { "post": { "operationId": "getOrCreateFlexCredentials", "tags": [ "Proxies" ], "summary": "Get or create the Flex mode gateway credentials", "description": "Idempotent get-or-create for the package-level gateway used by Flex\nmode. First call provisions the credentials; subsequent calls return\nthe persisted credentials without additional work.\n\nRequires the package to be `status: active` (else `409 PROXY_NOT_READY`).\n\nOnce provisioned, geo / session / rotation are controlled per request\nvia underscore-prefixed username parameters: `_c_`, `_sd_`,\n`_city_`, `_asn_`, `_zip_`, `_s_`, `_ttl_`,\n`_rotm_<0|1|2>`. See the proxies docs reference for the full parameter\nlist and chaining rules.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ProxyId" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Gateway credentials returned on `proxy.gateway`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "proxy" ], "properties": { "proxy": { "$ref": "#/components/schemas/Proxy" } } } } } ] } } } }, "404": { "$ref": "#/components/responses/PROXY_NOT_FOUND" }, "409": { "$ref": "#/components/responses/PROXY_NOT_READY" } } } }, "/proxies/{id}/lists": { "post": { "operationId": "createProxyList", "tags": [ "Proxies" ], "summary": "Create a per-list configuration on a proxy package", "description": "Creates a new geo-targeted list under a package. Geo rules:\n- `country` (single) **xor** `countries` (array of 2-30) is required.\n- `region`, `city`, `isp`, `zip` are only valid with a single `country`.\nViolations return `400 PROXY_GEO_CONFLICT`.\n\nMax 100 lists per package by default (higher per-package limits\navailable on request). The returned `entries[]` and\n`credentials.port` are resolved and persisted before the response is\nreturned.\n\nPass `network` to authenticate the list by source IP instead of\nlogin/password. `credentials` is then `null` and `entries[]` carries a\nbare `host:port`. The whitelist is create-time only and an address can be\nwhitelisted on one list at a time, so a clash returns\n`409 PROXY_NETWORK_UNAVAILABLE` - retry with a different address.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ProxyId" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProxyListRequest" } } } }, "responses": { "201": { "description": "List created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "list" ], "properties": { "list": { "$ref": "#/components/schemas/ProxyList" } } } } } ] } } } }, "400": { "$ref": "#/components/responses/PROXY_GEO_CONFLICT" }, "404": { "$ref": "#/components/responses/PROXY_NOT_FOUND" }, "409": { "description": "Conflict - PROXY_NOT_READY, PROXY_LIST_LIMIT_EXCEEDED, or PROXY_NETWORK_UNAVAILABLE (the requested IP whitelist overlaps an address already in use on another list).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/proxies/{id}/lists/{lid}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ProxyId" } }, { "name": "lid", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ProxyListId" } } ], "get": { "operationId": "getProxyList", "tags": [ "Proxies" ], "summary": "Get a single proxy list", "responses": { "200": { "description": "The proxy list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "list" ], "properties": { "list": { "$ref": "#/components/schemas/ProxyList" } } } } } ] } } } }, "404": { "$ref": "#/components/responses/PROXY_LIST_NOT_FOUND" } } }, "patch": { "operationId": "updateProxyList", "tags": [ "Proxies" ], "summary": "Update a proxy list", "description": "Partial update. Same geo rules as create.\n", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProxyListRequest" } } } }, "responses": { "200": { "description": "Updated list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "list" ], "properties": { "list": { "$ref": "#/components/schemas/ProxyList" } } } } } ] } } } }, "400": { "$ref": "#/components/responses/PROXY_GEO_CONFLICT" }, "404": { "$ref": "#/components/responses/PROXY_LIST_NOT_FOUND" }, "409": { "$ref": "#/components/responses/PROXY_NOT_READY" } } }, "delete": { "operationId": "deleteProxyList", "tags": [ "Proxies" ], "summary": "Delete a proxy list", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "204": { "description": "List deleted. No content." }, "404": { "$ref": "#/components/responses/PROXY_LIST_NOT_FOUND" } } } }, "/proxies/{id}/lists/{lid}/regenerate_password": { "post": { "operationId": "regenerateProxyListPassword", "tags": [ "Proxies" ], "summary": "Rotate per-list credentials", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ProxyId" } }, { "name": "lid", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ProxyListId" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Rotated. New credentials are on `list.credentials`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "list" ], "properties": { "list": { "$ref": "#/components/schemas/ProxyList" } } } } } ] } } } }, "404": { "$ref": "#/components/responses/PROXY_LIST_NOT_FOUND" } } } }, "/proxy_pools": { "get": { "operationId": "listProxyPools", "tags": [ "Proxy pools" ], "summary": "List the caller's GB pools", "responses": { "200": { "description": "Pools owned by the caller.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "pools" ], "properties": { "pools": { "type": "array", "items": { "$ref": "#/components/schemas/ProxyPool" } } } } } } ] } } } }, "401": { "$ref": "#/components/responses/UNAUTHENTICATED" }, "429": { "$ref": "#/components/responses/RATE_LIMITED" } } } }, "/proxy_pools/{id}": { "get": { "operationId": "getProxyPool", "tags": [ "Proxy pools" ], "summary": "Get a GB pool", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ProxyPoolId" } } ], "responses": { "200": { "description": "The pool.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "pool" ], "properties": { "pool": { "$ref": "#/components/schemas/ProxyPool" } } } } } ] } } } }, "401": { "$ref": "#/components/responses/UNAUTHENTICATED" }, "404": { "$ref": "#/components/responses/POOL_NOT_FOUND" }, "429": { "$ref": "#/components/responses/RATE_LIMITED" } } } }, "/proxy_pools/{id}/extend": { "post": { "operationId": "extendProxyPool", "tags": [ "Proxy pools" ], "summary": "Extend a GB pool at its current rate (self-serve)", "description": "Adds `gb` at the pool's current `price_per_gb_cents` and pushes\n`valid_until` forward by `self_extend.adds_days` (from now if the pool\nhad lapsed). Charged to the wallet. Refused when self-serve extension\nis disabled or `gb` is under `self_extend.min_gb`. Works on a lapsed\npool - this is how a reseller reactivates one.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ProxyPoolId" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtendProxyPoolRequest" } } } }, "responses": { "200": { "description": "Extended.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "pool", "charged_price_cents" ], "properties": { "pool": { "$ref": "#/components/schemas/ProxyPool" }, "charged_price_cents": { "type": "integer" } } } } } ] } } } }, "400": { "$ref": "#/components/responses/POOL_MIN_EXTEND" }, "401": { "$ref": "#/components/responses/UNAUTHENTICATED" }, "402": { "$ref": "#/components/responses/INSUFFICIENT_BALANCE" }, "403": { "$ref": "#/components/responses/POOL_SELF_EXTEND_DISABLED" }, "404": { "$ref": "#/components/responses/POOL_NOT_FOUND" }, "409": { "$ref": "#/components/responses/PRICE_MISMATCH" }, "429": { "$ref": "#/components/responses/RATE_LIMITED" } } } }, "/webhook_endpoints": { "post": { "operationId": "createWebhookEndpoint", "tags": [ "Webhooks" ], "summary": "Register a webhook subscription", "description": "Registers an HTTPS URL to receive event deliveries. The response\nincludes the HMAC-SHA256 `signing_secret` **once** - store it securely;\nit cannot be retrieved again. Use it to verify the\n`X-VoidMob-Signature` header on every inbound delivery.\n\n`event_types` accepts the literal `\"*\"` for all events, or any subset\nof the typed enum. Max 20 endpoints per user.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookEndpointRequest" } } } }, "responses": { "201": { "description": "Endpoint registered. `signing_secret` is included exactly once.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "endpoint" ], "properties": { "endpoint": { "$ref": "#/components/schemas/WebhookEndpointCreated" } } } } } ] } } } }, "400": { "$ref": "#/components/responses/VALIDATION_ERROR" }, "401": { "$ref": "#/components/responses/UNAUTHENTICATED" }, "429": { "$ref": "#/components/responses/RATE_LIMITED" } } }, "get": { "operationId": "listWebhookEndpoints", "tags": [ "Webhooks" ], "summary": "List the caller's webhook endpoints", "responses": { "200": { "description": "Endpoints owned by the authenticated user.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "endpoints" ], "properties": { "endpoints": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" } } } } } } ] } } } }, "401": { "$ref": "#/components/responses/UNAUTHENTICATED" } } } }, "/webhook_endpoints/{id}": { "delete": { "operationId": "deleteWebhookEndpoint", "tags": [ "Webhooks" ], "summary": "Delete a webhook endpoint", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/WebhookEndpointId" } } ], "responses": { "204": { "description": "Endpoint deleted. No content." }, "404": { "$ref": "#/components/responses/WEBHOOK_ENDPOINT_NOT_FOUND" } } } }, "/geo": { "get": { "operationId": "listGeo", "tags": [ "Geo" ], "summary": "Cascading geo data for mobile proxy targeting", "description": "Hierarchical geo lookup:\n\n- No params - countries with `available_nodes`\n- `?country=X` - regions in that country\n- `?country=X®ion=Y` - cities in that region\n- `?country=X®ion=Y&city=Z` - ISPs in that city\n\nResponse is public-cacheable for 5 minutes.\n", "parameters": [ { "$ref": "#/components/parameters/CountryQuery" }, { "name": "region", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "city", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "One of countries, regions, cities, or ISPs depending on the parameters.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "oneOf": [ { "type": "object", "required": [ "countries" ], "properties": { "countries": { "type": "array", "items": { "$ref": "#/components/schemas/GeoCountry" } } } }, { "type": "object", "required": [ "regions" ], "properties": { "regions": { "type": "array", "items": { "$ref": "#/components/schemas/GeoNode" } } } }, { "type": "object", "required": [ "cities" ], "properties": { "cities": { "type": "array", "items": { "$ref": "#/components/schemas/GeoNode" } } } }, { "type": "object", "required": [ "isps" ], "properties": { "isps": { "type": "array", "items": { "$ref": "#/components/schemas/GeoNode" } } } } ] } } } ] } } } }, "401": { "$ref": "#/components/responses/UNAUTHENTICATED" }, "429": { "$ref": "#/components/responses/RATE_LIMITED" } } } }, "/dedicated/countries": { "get": { "operationId": "listDedicatedCountries", "tags": [ "Dedicated Numbers" ], "summary": "List available dedicated number countries with per-user pricing", "description": "Returns all enabled dedicated number countries with per-user quoted prices.\nThe quoted_price_cents reflects any active category discounts for your account.\n", "responses": { "200": { "description": "List of available dedicated number countries.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "country", "name", "quoted_price_cents", "base_price_cents", "in_stock" ], "properties": { "country": { "type": "string", "description": "Lowercase ISO-2 country code.", "example": "de" }, "name": { "type": "string", "description": "Human-readable country name.", "example": "Germany" }, "quoted_price_cents": { "type": "integer", "description": "Per-user price in cents (after any account discounts).", "example": 3499 }, "base_price_cents": { "type": "integer", "description": "Retail base price in cents before any discounts.", "example": 3599 }, "in_stock": { "type": "boolean", "description": "Whether this country has inventory available right now.", "example": true } } } } } } ] } } } }, "401": { "$ref": "#/components/responses/UNAUTHENTICATED" }, "429": { "$ref": "#/components/responses/RATE_LIMITED" } } } }, "/dedicated/numbers": { "get": { "operationId": "listDedicatedNumbers", "tags": [ "Dedicated Numbers" ], "summary": "List the caller's dedicated numbers", "description": "Returns all dedicated numbers owned by the authenticated user, including\nnumbers purchased via the dashboard or the legacy US-only endpoint.\nPaginated via keyset cursor on `id` (descending). Pass the returned\n`next_cursor` as the `cursor` query parameter to fetch the next page.\n", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "active", "expired" ] }, "description": "Filter by status. `active` includes `message_received` numbers." }, { "name": "country", "in": "query", "schema": { "type": "string", "minLength": 2, "maxLength": 2 }, "description": "Filter by lowercase ISO-2 country code (e.g. \"de\")." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Maximum number of results per page (1-100, default 20)." }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 64 }, "description": "Opaque cursor returned by a previous call to paginate to the next page." } ], "responses": { "200": { "description": "Paginated list of the caller's dedicated numbers.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "has_more", "next_cursor", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "type": "object", "required": [ "id", "status", "phone_number", "country", "country_name", "billing_period", "quoted_price_cents", "charged_price_cents", "next_renewal_price_cents", "auto_renew", "created_at", "paid_until", "expires_at", "messages" ], "properties": { "id": { "type": "string", "description": "Dedicated number id prefixed `ded_`.", "example": "ded_abc123" }, "display_id": { "type": [ "string", "null" ], "description": "Human-readable display id.", "example": "DED1" }, "status": { "type": "string", "enum": [ "active", "expired" ] }, "phone_number": { "type": "string", "description": "Full E.164 phone number.", "example": "+4915123456789" }, "country": { "type": "string", "description": "Lowercase ISO-2 country code.", "example": "de" }, "country_name": { "type": "string", "description": "Human-readable country name.", "example": "Germany" }, "billing_period": { "type": "string", "enum": [ "monthly" ] }, "nickname": { "type": [ "string", "null" ], "description": "User-set nickname for this number." }, "quoted_price_cents": { "type": "integer", "description": "Price quoted at purchase time in USD cents.", "example": 3499 }, "charged_price_cents": { "type": "integer", "description": "Price actually charged in USD cents.", "example": 3499 }, "next_renewal_price_cents": { "type": "integer", "description": "Price that will be charged on next renewal in USD cents.", "example": 3499 }, "auto_renew": { "type": "boolean", "description": "Whether this number auto-renews at period end." }, "created_at": { "type": "string", "format": "date-time" }, "paid_until": { "type": "string", "format": "date-time", "description": "Date through which the number is paid." }, "expires_at": { "type": "string", "format": "date-time" }, "messages": { "type": "array", "description": "Always empty in list responses - fetch GET /v1/dedicated/numbers/{id} for messages.", "items": { "type": "object", "required": [ "id", "text", "received_at" ], "properties": { "id": { "type": "string" }, "code": { "type": [ "string", "null" ] }, "text": { "type": "string" }, "received_at": { "type": "string", "format": "date-time" } } } } } } }, "has_more": { "type": "boolean", "description": "Whether there are more results after this page." }, "next_cursor": { "type": [ "string", "null" ], "description": "Cursor to pass as `cursor` to fetch the next page. Null when no more pages." }, "request_id": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/VALIDATION_ERROR" }, "401": { "$ref": "#/components/responses/UNAUTHENTICATED" }, "429": { "$ref": "#/components/responses/RATE_LIMITED" } } }, "post": { "operationId": "createDedicatedNumber", "tags": [ "Dedicated Numbers" ], "summary": "Purchase a dedicated phone number", "description": "Purchase a dedicated phone number for the specified country. Requires an\n`Idempotency-Key` header. If the resolved per-user price exceeds\n`max_price_cents`, the server returns `PRICE_OVER_CAP` (409) without\ntouching your wallet - retry with a fresh key or a higher cap.\n", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Client-generated unique key to make this request idempotent." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "country" ], "additionalProperties": false, "properties": { "country": { "type": "string", "minLength": 2, "maxLength": 2, "description": "Lowercase ISO-2 country code (e.g. \"de\", \"us\", \"ca\").", "example": "de" }, "auto_renew": { "type": "boolean", "default": false, "description": "Automatically renew this number at the end of each billing period." }, "max_price_cents": { "type": "integer", "minimum": 1, "description": "Optional price ceiling in cents. If the resolved per-user price is above\nthis value the request returns PRICE_OVER_CAP (409) without charging.\nDefaults to the quoted price - effectively no cap.\n", "example": 4000 }, "webhook_endpoint_id": { "type": "string", "description": "Deliver `rental.created` to this endpoint instead of the default." } } } } } }, "responses": { "201": { "description": "Dedicated number purchased successfully.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "id", "status", "phone_number", "country", "country_name", "billing_period", "quoted_price_cents", "charged_price_cents", "next_renewal_price_cents", "auto_renew", "created_at", "paid_until", "expires_at", "messages" ], "properties": { "id": { "type": "string", "description": "Dedicated number id prefixed `ded_`.", "example": "ded_abc123" }, "display_id": { "type": [ "string", "null" ], "description": "Human-readable display id.", "example": "DED1" }, "status": { "type": "string", "enum": [ "active", "expired" ] }, "phone_number": { "type": "string", "description": "Full E.164 phone number.", "example": "+4915123456789" }, "country": { "type": "string", "description": "Lowercase ISO-2 country code.", "example": "de" }, "country_name": { "type": "string", "description": "Human-readable country name.", "example": "Germany" }, "billing_period": { "type": "string", "enum": [ "monthly" ] }, "nickname": { "type": [ "string", "null" ], "description": "User-set nickname for this number." }, "quoted_price_cents": { "type": "integer", "description": "Price quoted at purchase time in USD cents.", "example": 3499 }, "charged_price_cents": { "type": "integer", "description": "Price actually charged in USD cents.", "example": 3499 }, "next_renewal_price_cents": { "type": "integer", "description": "Price that will be charged on next renewal in USD cents.", "example": 3499 }, "auto_renew": { "type": "boolean", "description": "Whether this number auto-renews at period end." }, "created_at": { "type": "string", "format": "date-time" }, "paid_until": { "type": "string", "format": "date-time", "description": "Date through which the number is paid." }, "expires_at": { "type": "string", "format": "date-time" }, "messages": { "type": "array", "description": "SMS messages received on this number.", "items": { "type": "object", "required": [ "id", "text", "received_at" ], "properties": { "id": { "type": "string" }, "code": { "type": [ "string", "null" ] }, "text": { "type": "string" }, "received_at": { "type": "string", "format": "date-time" } } } } } } } } ] } } } }, "400": { "$ref": "#/components/responses/VALIDATION_ERROR" }, "401": { "$ref": "#/components/responses/UNAUTHENTICATED" }, "402": { "$ref": "#/components/responses/INSUFFICIENT_BALANCE" }, "404": { "$ref": "#/components/responses/DEDICATED_NOT_AVAILABLE" }, "409": { "$ref": "#/components/responses/PRICE_OVER_CAP" }, "429": { "$ref": "#/components/responses/RATE_LIMITED" }, "502": { "$ref": "#/components/responses/PROVIDER_ERROR" }, "503": { "$ref": "#/components/responses/SERVICE_OUT_OF_STOCK" }, "504": { "$ref": "#/components/responses/PROVIDER_TIMEOUT" } } } }, "/dedicated/numbers/{id}": { "get": { "operationId": "getDedicatedNumber", "tags": [ "Dedicated Numbers" ], "summary": "Get a dedicated number with its messages", "description": "Returns a single dedicated number owned by the authenticated user, including\npaginated SMS messages received on the number. Use `messages_before` and\n`messages_limit` to page through message history (newest-first fetch, returned\nin ascending order).\n", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Dedicated number id prefixed `ded_`.", "example": "ded_abc123" }, { "name": "messages_limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Maximum number of messages to return (1-100, default 50)." }, { "name": "messages_before", "in": "query", "schema": { "type": "string", "maxLength": 64 }, "description": "Cursor for paging older messages. Pass a `msg_` value to retrieve messages before that id." } ], "responses": { "200": { "description": "Dedicated number detail with inline messages.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "id", "status", "phone_number", "country", "country_name", "billing_period", "quoted_price_cents", "charged_price_cents", "next_renewal_price_cents", "auto_renew", "created_at", "paid_until", "expires_at", "messages" ], "properties": { "id": { "type": "string", "description": "Dedicated number id prefixed `ded_`.", "example": "ded_abc123" }, "display_id": { "type": [ "string", "null" ], "description": "Human-readable display id.", "example": "DED1" }, "status": { "type": "string", "enum": [ "active", "expired" ] }, "phone_number": { "type": "string", "description": "Full E.164 phone number.", "example": "+4915123456789" }, "country": { "type": "string", "description": "Lowercase ISO-2 country code.", "example": "de" }, "country_name": { "type": "string", "description": "Human-readable country name.", "example": "Germany" }, "billing_period": { "type": "string", "enum": [ "monthly" ] }, "nickname": { "type": [ "string", "null" ], "description": "User-set nickname for this number." }, "quoted_price_cents": { "type": "integer", "description": "Price quoted at purchase time in USD cents.", "example": 3499 }, "charged_price_cents": { "type": "integer", "description": "Price actually charged in USD cents.", "example": 3499 }, "next_renewal_price_cents": { "type": "integer", "description": "Price that will be charged on next renewal in USD cents.", "example": 3499 }, "auto_renew": { "type": "boolean", "description": "Whether this number auto-renews at period end." }, "created_at": { "type": "string", "format": "date-time" }, "paid_until": { "type": "string", "format": "date-time", "description": "Date through which the number is paid." }, "expires_at": { "type": "string", "format": "date-time" }, "messages": { "type": "array", "description": "SMS messages received on this number, in ascending order. Paginate with messages_before cursor.", "items": { "type": "object", "required": [ "id", "text", "received_at" ], "properties": { "id": { "type": "string", "description": "Message id prefixed `msg_`." }, "code": { "type": [ "string", "null" ], "description": "Parsed OTP/verification code, if detected." }, "text": { "type": "string", "description": "Full message text." }, "received_at": { "type": "string", "format": "date-time" } } } } } } } } ] } } } }, "400": { "$ref": "#/components/responses/VALIDATION_ERROR" }, "401": { "$ref": "#/components/responses/UNAUTHENTICATED" }, "404": { "$ref": "#/components/responses/NOT_FOUND" }, "429": { "$ref": "#/components/responses/RATE_LIMITED" } } } }, "/dedicated/numbers/{id}/auto_renew": { "post": { "operationId": "toggleDedicatedNumberAutoRenew", "tags": [ "Dedicated Numbers" ], "summary": "Toggle auto-renew for a dedicated number", "description": "Sets auto-renew to the specified state for a dedicated number owned by the\nauthenticated user. Unlike a flip toggle, this is idempotent - calling with\nthe same `enabled` value twice is safe.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Dedicated number id prefixed `ded_`.", "example": "ded_abc123" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "enabled" ], "additionalProperties": false, "properties": { "enabled": { "type": "boolean", "description": "Set to `true` to enable auto-renew, `false` to disable." } } } } } }, "responses": { "200": { "description": "Auto-renew state updated. Returns the updated dedicated number.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "id", "status", "phone_number", "country", "country_name", "billing_period", "quoted_price_cents", "charged_price_cents", "next_renewal_price_cents", "auto_renew", "created_at", "paid_until", "expires_at", "messages" ], "properties": { "id": { "type": "string", "description": "Dedicated number id prefixed `ded_`.", "example": "ded_abc123" }, "display_id": { "type": [ "string", "null" ], "description": "Human-readable display id.", "example": "DED1" }, "status": { "type": "string", "enum": [ "active", "expired" ] }, "phone_number": { "type": "string", "description": "Full E.164 phone number.", "example": "+4915123456789" }, "country": { "type": "string", "description": "Lowercase ISO-2 country code.", "example": "de" }, "country_name": { "type": "string", "description": "Human-readable country name.", "example": "Germany" }, "billing_period": { "type": "string", "enum": [ "monthly" ] }, "nickname": { "type": [ "string", "null" ], "description": "User-set nickname for this number." }, "quoted_price_cents": { "type": "integer", "description": "Price quoted at purchase time in USD cents.", "example": 3499 }, "charged_price_cents": { "type": "integer", "description": "Price actually charged in USD cents.", "example": 3499 }, "next_renewal_price_cents": { "type": "integer", "description": "Price that will be charged on next renewal in USD cents.", "example": 3499 }, "auto_renew": { "type": "boolean", "description": "Whether this number auto-renews at period end." }, "created_at": { "type": "string", "format": "date-time" }, "paid_until": { "type": "string", "format": "date-time", "description": "Date through which the number is paid." }, "expires_at": { "type": "string", "format": "date-time" }, "messages": { "type": "array", "description": "Always empty in this response.", "items": { "type": "object", "required": [ "id", "text", "received_at" ], "properties": { "id": { "type": "string" }, "code": { "type": [ "string", "null" ] }, "text": { "type": "string" }, "received_at": { "type": "string", "format": "date-time" } } } } } } } } ] } } } }, "400": { "$ref": "#/components/responses/VALIDATION_ERROR" }, "401": { "$ref": "#/components/responses/UNAUTHENTICATED" }, "404": { "$ref": "#/components/responses/NOT_FOUND" }, "429": { "$ref": "#/components/responses/RATE_LIMITED" }, "502": { "$ref": "#/components/responses/PROVIDER_ERROR" }, "503": { "$ref": "#/components/responses/SERVICE_UNAVAILABLE" } } } } }, "webhooks": { "verification.created": { "post": { "summary": "Fired when a verification is created via the API.", "description": "## Signature\n\nEvery delivery includes `X-VoidMob-Signature: t=,v1=`.\nCompute `v1 = HMAC-SHA256(secret, \"${t}.${raw_body}\")` and compare in\nconstant time. Reject if `t` is more than 5 minutes from now to\nprevent replay.\n\n## Retries\n\nFailed deliveries (non-2xx, timeout, network) are retried with\nexponential backoff for ~24 hours. After 30 consecutive failures the\nendpoint is auto-disabled; re-enable it from the developer portal.\n", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationEvent" } } } }, "responses": { "2XX": { "description": "Acknowledged. Any 2xx is accepted; body is ignored." } } } }, "verification.code_received": { "post": { "summary": "Fired when an SMS code lands on a verification.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationEvent" } } } }, "responses": { "2XX": { "description": "Acknowledged." } } } }, "verification.cancelled": { "post": { "summary": "Fired when a verification is cancelled via the API or auto-refunded because no SMS arrived in the window (refund included on payload).", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationEvent" } } } }, "responses": { "2XX": { "description": "Acknowledged." } } } }, "verification.completed": { "post": { "summary": "Fired when a verification is explicitly marked complete via POST /verifications/{id}/complete.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationEvent" } } } }, "responses": { "2XX": { "description": "Acknowledged." } } } }, "verification.expired": { "post": { "summary": "Fired when a verification's window closes with no SMS and no automatic refund (non-refundable services and rare exceptions; the usual no-SMS outcome is verification.cancelled with a refund).", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationEvent" } } } }, "responses": { "2XX": { "description": "Acknowledged." } } } }, "verification.failed": { "post": { "summary": "Fired when a verification terminally fails after creation. Reserved - not emitted in the current release.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationEvent" } } } }, "responses": { "2XX": { "description": "Acknowledged." } } } }, "rental.created": { "post": { "summary": "Fired when a long-term rental is created via the API.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RentalEvent" } } } }, "responses": { "2XX": { "description": "Acknowledged." } } } }, "rental.message_received": { "post": { "summary": "Fired once for every new SMS on an API-bought rental or dedicated number, with or without a detected code. A coded message fires this first, then rental.code_received.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RentalMessageEvent" } } } }, "responses": { "2XX": { "description": "Acknowledged." } } } }, "rental.code_received": { "post": { "summary": "Fired when a new SMS with a detected code arrives on an API-bought rental or dedicated number.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RentalEvent" } } } }, "responses": { "2XX": { "description": "Acknowledged." } } } }, "rental.renewed": { "post": { "summary": "Fired when a rental successfully auto-renews.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RentalEvent" } } } }, "responses": { "2XX": { "description": "Acknowledged." } } } }, "rental.expired": { "post": { "summary": "Fired when a rental expires without renewal.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RentalEvent" } } } }, "responses": { "2XX": { "description": "Acknowledged." } } } }, "rental.cancelled": { "post": { "summary": "Fired when a rental is cancelled.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RentalEvent" } } } }, "responses": { "2XX": { "description": "Acknowledged." } } } }, "rental.auto_renew_disabled": { "post": { "summary": "Fired when auto-renew is disabled on a rental (e.g. due to insufficient balance at renewal time).", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RentalEvent" } } } }, "responses": { "2XX": { "description": "Acknowledged." } } } }, "proxy.ready": { "post": { "summary": "Fired when a provisioning proxy package becomes active.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProxyEvent" } } } }, "responses": { "2XX": { "description": "Acknowledged." } } } }, "proxy.provisioning_failed": { "post": { "summary": "Fired when a proxy package fails to provision and the user is refunded.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProxyLifecycleEvent" } } } }, "responses": { "2XX": { "description": "Acknowledged." } } } }, "proxy.expired": { "post": { "summary": "Fired when a proxy package's duration ends.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProxyLifecycleEvent" } } } }, "responses": { "2XX": { "description": "Acknowledged." } } } }, "proxy.traffic_low": { "post": { "summary": "Fired once per allocation when usage crosses 90% (10% remaining); a top-up or renew re-arms it.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProxyLifecycleEvent" } } } }, "responses": { "2XX": { "description": "Acknowledged." } } } }, "proxy.traffic_exhausted": { "post": { "summary": "Fired when remaining traffic reaches zero.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProxyLifecycleEvent" } } } }, "responses": { "2XX": { "description": "Acknowledged." } } } }, "proxy.renewed": { "post": { "summary": "Fired after a successful `POST /v1/proxies/:id/renew`.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProxyEvent" } } } }, "responses": { "2XX": { "description": "Acknowledged." } } } }, "proxy_pool.low": { "post": { "summary": "Fired once when a pool's remaining_gb drops to or below its low-GB threshold; a successful extension re-arms it.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProxyPoolEvent" } } } }, "responses": { "2XX": { "description": "Acknowledged." } } } }, "proxy_pool.expiring": { "post": { "summary": "Fired once, 3 days before a pool's valid_until.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProxyPoolEvent" } } } }, "responses": { "2XX": { "description": "Acknowledged." } } } }, "proxy_pool.extended": { "post": { "summary": "Fired after a successful `POST /v1/proxy_pools/:id/extend`, self-serve or admin-initiated.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProxyPoolEvent" } } } }, "responses": { "2XX": { "description": "Acknowledged." } } } }, "esim.created": { "post": { "summary": "Fired when an eSIM order is successfully created and provisioned.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EsimEvent" } } } }, "responses": { "2XX": { "description": "Acknowledged. Any 2xx is accepted; body is ignored." } } } }, "esim.provisioning_failed": { "post": { "summary": "Fired when an eSIM order fails to provision and the user is refunded.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EsimEvent" } } } }, "responses": { "2XX": { "description": "Acknowledged." } } } }, "esim.topup_added": { "post": { "summary": "Fired when a topup is successfully provisioned on an existing eSIM.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EsimEvent" } } } }, "responses": { "2XX": { "description": "Acknowledged." } } } }, "esim.expired": { "post": { "summary": "Fired when an eSIM's validity period ends.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EsimEvent" } } } }, "responses": { "2XX": { "description": "Acknowledged." } } } }, "esim.cancelled": { "post": { "summary": "Fired when an eSIM order is cancelled.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EsimEvent" } } } }, "responses": { "2XX": { "description": "Acknowledged." } } } }, "esim.refunded": { "post": { "summary": "Fired when an eSIM order is refunded.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EsimEvent" } } } }, "responses": { "2XX": { "description": "Acknowledged." } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "vmk_live_*", "description": "Issue keys from the developer portal. Send as\n`Authorization: Bearer vmk_live_xxxxxxxx`. Optional per-key IP\nallowlist is enforced server-side.\n" } }, "schemas": { "SuccessEnvelope": { "type": "object", "required": [ "success", "data" ], "additionalProperties": false, "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "additionalProperties": true } } }, "ServiceId": { "type": "string", "pattern": "^svc_[A-Za-z0-9_]+$", "description": "Opaque public service identifier.", "example": "svc_telegram" }, "VerificationId": { "type": "string", "pattern": "^ver_[A-Za-z0-9_-]{1,64}$", "description": "Opaque verification (SMS rental) identifier.", "example": "ver_01HXYZ123ABC" }, "ProxyId": { "type": "string", "pattern": "^prx_[A-Za-z0-9_-]+$", "description": "Opaque proxy package identifier.", "example": "prx_8f6a1b2c" }, "ProxyListId": { "type": "string", "pattern": "^list_[A-Za-z0-9_-]+$", "description": "Identifier for a per-list configuration inside a proxy package.", "example": "list_01HXYZ123ABC" }, "ProxyPlanId": { "type": "string", "pattern": "^plan_[A-Z0-9]+$", "description": "Public plan identifier.", "example": "plan_RESI100" }, "ProxyPoolId": { "type": "string", "pattern": "^pool_[0-9a-f-]{36}$", "description": "Opaque reseller GB pool identifier.", "example": "pool_3f2b9d3a-1c4e-4a3b-9f0e-6c1d2b3a4f5e" }, "WebhookEndpointId": { "type": "string", "pattern": "^whep_[A-Za-z0-9_-]+$", "description": "Webhook endpoint identifier.", "example": "whep_01HXYZ123ABC" }, "RentalId": { "type": "string", "pattern": "^ren_[A-Za-z0-9_-]+$", "description": "Opaque long-term rental identifier.", "example": "ren_01HXYZ123ABC" }, "RequestId": { "type": "string", "description": "Server-assigned identifier for a single request.", "example": "req_01HXYZ123456789ABCDEFG" }, "Balance": { "type": "object", "required": [ "amount_cents", "currency", "formatted" ], "additionalProperties": false, "properties": { "amount_cents": { "type": "integer", "description": "Wallet balance in USD cents. May be negative momentarily during refunds.", "example": 1250 }, "currency": { "type": "string", "enum": [ "USD" ] }, "formatted": { "type": "string", "description": "Pre-formatted dollar amount, suitable for direct display.", "example": "$12.50" } } }, "RateLimit": { "type": "object", "required": [ "limit", "window_seconds" ], "additionalProperties": false, "properties": { "limit": { "type": "integer", "example": 60 }, "window_seconds": { "type": "integer", "example": 60 } } }, "Me": { "type": "object", "required": [ "id", "balance", "rate_limits", "created_at" ], "additionalProperties": false, "properties": { "id": { "type": "string", "description": "The authenticated user's opaque id." }, "balance": { "$ref": "#/components/schemas/Balance" }, "rate_limits": { "type": "object", "description": "Per-endpoint-group ceilings for this caller. Keys are the\nendpoint groups returned by the rate limiter:\n`verifications`, `verifications_read`, `services`, `account`,\n`proxies`, `reads`.\n", "additionalProperties": { "$ref": "#/components/schemas/RateLimit" } }, "created_at": { "type": "string", "format": "date-time" } } }, "DegradedService": { "type": "object", "required": [ "id", "name", "country", "since" ], "additionalProperties": false, "properties": { "id": { "$ref": "#/components/schemas/ServiceId" }, "name": { "type": "string", "example": "Telegram" }, "country": { "type": "string", "example": "us" }, "since": { "type": "string", "format": "date-time", "description": "Earliest ISO timestamp at which the degradation was observed." } } }, "ProxyProvisioning": { "type": "object", "required": [ "status", "recent_median_seconds", "recent_p95_seconds" ], "additionalProperties": false, "properties": { "status": { "type": "string", "enum": [ "operational", "degraded" ] }, "recent_median_seconds": { "type": "integer", "description": "Median provisioning latency (seconds) over the last 15 minutes of API-originated orders." }, "recent_p95_seconds": { "type": "integer" } } }, "Health": { "type": "object", "required": [ "status", "degraded_services", "proxy_provisioning" ], "additionalProperties": false, "properties": { "status": { "type": "string", "enum": [ "operational", "degraded" ] }, "degraded_services": { "type": "array", "items": { "$ref": "#/components/schemas/DegradedService" } }, "proxy_provisioning": { "$ref": "#/components/schemas/ProxyProvisioning" } } }, "Service": { "type": "object", "required": [ "id", "name", "icon_url", "quoted_price_cents", "base_price_cents", "discount_source", "price_ceiling_cents", "available" ], "additionalProperties": false, "properties": { "id": { "$ref": "#/components/schemas/ServiceId" }, "name": { "type": "string", "example": "Telegram" }, "icon_url": { "type": "string", "description": "Path to an immutable PNG icon (cache forever).", "example": "/api/v1/icons/a1b2c3d4e5f60718.png" }, "quoted_price_cents": { "type": "integer", "description": "Live per-caller quote. This is what will be charged if the quote\nstill holds at create time. Differs from `base_price_cents` when\nthe caller has a category discount or per-service override.\n", "example": 35 }, "base_price_cents": { "type": "integer", "description": "Retail price before any per-user discounts.", "example": 40 }, "discount_source": { "type": "string", "enum": [ "regular", "category", "override" ], "description": "Attribution for the current quote." }, "price_ceiling_cents": { "type": "integer", "description": "Upper bound on how far `quoted_price_cents` can drift under current\nmarket conditions. Set `max_price_cents` up to this value to absorb\nnormal market drift without seeing `409 PRICE_OVER_CAP`.\n", "example": 50 }, "available": { "type": "boolean", "description": "Whether stock is currently available. Unavailable services are still returned so a UI can grey them out." }, "ltr_3d_price_cents": { "type": "integer", "description": "Per-user quoted price for a 3-day long-term rental of this service.\n`0` means the duration is not available for this service.\n", "example": 1500 }, "ltr_7d_price_cents": { "type": "integer", "description": "Per-user quoted price for a 7-day long-term rental of this service.\n`0` means the duration is not available for this service.\n", "example": 2500 }, "ltr_14d_price_cents": { "type": "integer", "description": "Per-user quoted price for a 14-day long-term rental of this service.\n`0` means the duration is not available for this service.\n", "example": 4000 }, "ltr_30d_price_cents": { "type": "integer", "description": "Per-user quoted price for a 30-day long-term rental of this service.\n`0` means the duration is not available for this service.\n", "example": 7500 } } }, "ServicesList": { "type": "object", "required": [ "country", "services", "fetched_at" ], "additionalProperties": false, "properties": { "country": { "type": "string", "example": "us" }, "services": { "type": "array", "items": { "$ref": "#/components/schemas/Service" } }, "fetched_at": { "type": "string", "format": "date-time" } } }, "VerificationStatus": { "type": "string", "description": "`waiting_for_code` - number is live (up to 15 minutes, see `expires_at`), no SMS yet. `code_received` - at least one SMS arrived. `cancelled` - the price was refunded, either because you cancelled or because the window closed with no SMS (automatic refund). `expired` - the window closed with no SMS and no automatic refund (services marked non-refundable, or rare cases where the refund could not be applied automatically). `failed` is reserved and not emitted.", "enum": [ "waiting_for_code", "code_received", "cancelled", "expired", "failed" ] }, "Verification": { "type": "object", "required": [ "id", "status", "phone_number", "service_name", "charged_price_cents", "expires_at", "can_cancel", "created_at", "reuse_counter", "allow_reuse", "allow_paid_reuse", "paid_reuse_price_cents" ], "additionalProperties": false, "properties": { "id": { "$ref": "#/components/schemas/VerificationId" }, "display_id": { "type": [ "string", "null" ], "description": "Human-readable order identifier for display in dashboards and\nreceipts (e.g. `SMS7K4P2N`). Null for legacy rentals created before\nthis field was introduced.\n", "example": "SMS7K4P2N" }, "status": { "$ref": "#/components/schemas/VerificationStatus" }, "phone_number": { "type": "string", "description": "E.164 phone number (with leading +).", "example": "+15551234567" }, "service_id": { "oneOf": [ { "$ref": "#/components/schemas/ServiceId" }, { "type": "null" } ], "description": "Public service id. Null only for legacy rentals where the cache row was retired." }, "service_name": { "type": "string", "example": "Telegram" }, "charged_price_cents": { "type": "integer", "description": "Actual amount deducted from the wallet for this verification." }, "pricing_source": { "type": "string", "enum": [ "regular", "category", "override", "promo" ], "description": "Attribution for the charged price. Omitted for legacy rentals. \"promo\" means a redeemed service-discount code priced this purchase." }, "expires_at": { "type": "string", "format": "date-time" }, "can_cancel": { "type": "boolean", "description": "Whether the rental is currently cancellable. Becomes false once a code arrives or the cancel window closes." }, "created_at": { "type": "string", "format": "date-time" }, "code": { "type": "string", "description": "The received SMS code. Present only when `status = code_received`.", "example": "123456" }, "code_received_at": { "type": "string", "format": "date-time", "description": "When the code arrived. Present only when `status = code_received`." }, "reuse_counter": { "type": "integer", "description": "Number of user-initiated reuses (free or paid) on this number. Starts at 0. Automatic reuses are not counted.", "example": 0 }, "allow_reuse": { "type": "boolean", "description": "Free reuse is currently available." }, "allow_paid_reuse": { "type": "boolean", "description": "Paid reuse is currently available. STR rentals only." }, "paid_reuse_price_cents": { "type": "integer", "description": "Fixed price for one paid reuse.", "example": 50 }, "charged_reuse_cents": { "type": "integer", "description": "Set on the response of a successful POST /reuse/paid. Not present otherwise." }, "refunded_cents": { "type": "integer", "description": "Set on the response of a successful POST /cancel. Not present otherwise." } } }, "VerificationListResponse": { "type": "object", "required": [ "success", "data", "has_more", "next_cursor", "request_id" ], "additionalProperties": false, "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Verification" }, "description": "Page of verification resources, newest-first." }, "has_more": { "type": "boolean", "description": "Whether additional pages exist beyond this one." }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` in the next request to advance the page. Null on the last page.", "example": "MTc0OTQ3Njk3NTo0ZUxyakp0Y3Znci1oZG0zV2JoQ28" }, "request_id": { "$ref": "#/components/schemas/RequestId" } } }, "VerificationMessage": { "type": "object", "required": [ "code", "text", "received_at" ], "additionalProperties": false, "properties": { "code": { "type": [ "string", "null" ], "description": "Parsed OTP code, or null for ambient SMS with no extractable code.", "example": "123456" }, "text": { "type": "string", "description": "Full SMS body as received.", "example": "Your code is 123456" }, "received_at": { "type": "string", "format": "date-time" } } }, "CreateVerificationRequest": { "type": "object", "required": [ "service_id" ], "additionalProperties": false, "properties": { "service_id": { "$ref": "#/components/schemas/ServiceId" }, "country": { "type": "string", "pattern": "^[a-z]{2}$", "default": "us" }, "max_price_cents": { "type": "integer", "minimum": 1, "maximum": 1000000, "description": "Optional ceiling. If omitted, the API caps at the current\n`quoted_price_cents` reported by `GET /v1/services`. Setting this\nabove the quote opts into \"always get a number\" mode - price drift\nwithin the cap charges the new market price; drift above the cap\nreturns `409 PRICE_OVER_CAP` with the current available price in\nthe error details so callers can decide whether to retry with a\nhigher cap.\n" }, "webhook_endpoint_id": { "allOf": [ { "$ref": "#/components/schemas/WebhookEndpointId" } ], "description": "If set, scope this verification's webhook events to this endpoint only." } } }, "PaidReuseRequest": { "type": "object", "required": [ "accept_charge_cents" ], "additionalProperties": false, "properties": { "accept_charge_cents": { "type": "integer", "description": "Must equal the current `paid_reuse_price_cents` from the\nverification resource. Explicit consent guard against accidental\ncharges from misrouted requests.\n", "example": 50 } } }, "PriceOverCapError": { "type": "object", "required": [ "success", "error" ], "additionalProperties": false, "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message", "docs_url", "request_id", "details" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "PRICE_OVER_CAP" ] }, "message": { "type": "string" }, "docs_url": { "type": "string" }, "request_id": { "type": "string" }, "details": { "type": "object", "required": [ "max_price_cents", "available_price_cents" ], "additionalProperties": true, "properties": { "max_price_cents": { "type": "integer", "minimum": 1, "description": "The cap the caller authorized on this request." }, "available_price_cents": { "type": "integer", "minimum": 1, "description": "Lowest currently available price. Fluctuates with demand and stock." } } } } } } }, "RentalStatus": { "type": "string", "enum": [ "active", "expired", "cancelled" ] }, "RentalMessage": { "type": "object", "required": [ "id", "text", "received_at" ], "additionalProperties": false, "properties": { "id": { "type": "string", "description": "Opaque message identifier (prefixed `msg_`).", "example": "msg_01HXYZ123ABC" }, "code": { "type": [ "string", "null" ], "description": "Extracted numeric code, if any. Null when the SMS is informational.", "example": "123456" }, "text": { "type": "string", "description": "Full raw SMS text.", "example": "Your verification code is 123456." }, "received_at": { "type": "string", "format": "date-time" } } }, "RentalWebhookMessage": { "type": "object", "description": "The new SMS that triggered a `rental.message_received` event.", "required": [ "id", "text", "code", "sender", "received_at" ], "additionalProperties": false, "properties": { "id": { "type": "string", "description": "Opaque message identifier (prefixed `msg_`). Matches the entry in `data.rental.messages`.", "example": "msg_01HXYZ789GHI" }, "text": { "type": "string", "description": "Full raw SMS text.", "example": "Your account was accessed from a new device." }, "code": { "type": [ "string", "null" ], "description": "Detected OTP / verification code, or null when none was found.", "example": null }, "sender": { "type": [ "string", "null" ], "description": "Sender name or number when known, otherwise null.", "example": null }, "received_at": { "type": "string", "format": "date-time" } } }, "Rental": { "type": "object", "required": [ "id", "status", "phone_number", "service_id", "service_name", "country", "duration", "rental_type", "charged_price_cents", "auto_renew", "next_renewal_price_cents", "re_rent_available", "re_rent_price_cents", "re_rent_blocked_at", "created_at", "paid_until", "expires_at", "can_cancel", "messages" ], "additionalProperties": false, "properties": { "id": { "$ref": "#/components/schemas/RentalId" }, "display_id": { "type": [ "string", "null" ], "description": "Human-readable order identifier for display in dashboards and\nreceipts (e.g. `SMS7K4P2N`). Null for legacy rows.\n", "example": "SMS7K4P2N" }, "status": { "$ref": "#/components/schemas/RentalStatus" }, "phone_number": { "type": "string", "description": "E.164 phone number (with leading +).", "example": "+15551234567" }, "service_id": { "oneOf": [ { "$ref": "#/components/schemas/ServiceId" }, { "type": "null" } ], "description": "Public service id from the catalog. Null only for legacy rows\nwhere the catalog entry was retired.\n" }, "service_name": { "type": "string", "description": "Human-readable service name.", "example": "Telegram" }, "country": { "type": "string", "pattern": "^[a-z]{2}$", "description": "ISO-3166-1 alpha-2, lowercased.", "example": "us" }, "duration": { "type": "string", "enum": [ "3D", "7D", "14D", "30D" ], "description": "Rental period.\n", "example": "7D" }, "rental_type": { "type": "string", "enum": [ "rental" ], "description": "Always `rental` for long-term rentals." }, "charged_price_cents": { "type": "integer", "description": "Actual amount deducted from the wallet.", "example": 2500 }, "pricing_source": { "type": "string", "enum": [ "regular", "category", "override", "promo" ], "description": "Attribution for the charged price. Omitted for legacy rows. \"promo\" means a redeemed service-discount code priced this purchase." }, "auto_renew": { "type": "boolean", "description": "Whether the rental will automatically renew at expiry.", "example": false }, "next_renewal_price_cents": { "type": "integer", "description": "Estimated cost of the next auto-renewal at current pricing.", "example": 2500 }, "re_rent_available": { "type": "boolean", "description": "Whether this rental is eligible for re-rent on the same number after\nit expires. `true` only when the rental is `expired` and the number\nhas not yet been released. `false` for all non-expired rentals and\nfor expired rentals that are no longer eligible.\n", "example": true }, "re_rent_price_cents": { "type": [ "integer", "null" ], "description": "Current re-rent price in USD cents. Non-null only when\n`re_rent_available` is `true`. Null for all other states.\n", "example": 2500 }, "re_rent_blocked_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601 timestamp at which the number was permanently released.\nNon-null means re-rent will never become available for\nthis rental. Null when still eligible (or for non-expired rentals).\n" }, "created_at": { "type": "string", "format": "date-time" }, "paid_until": { "type": "string", "format": "date-time", "description": "Timestamp through which the number is paid." }, "expires_at": { "type": "string", "format": "date-time", "description": "Timestamp at which the rental expires (same as `paid_until` for standard rentals)." }, "can_cancel": { "type": "boolean", "description": "Whether the rental is currently cancellable. True only within the\nfirst hour after creation and only for non-dedicated rentals that\nhave not been flagged.\n" }, "cancel_window_expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp at which the cancel window closes. Null for dedicated\n28-day numbers (which cannot be cancelled).\n" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/RentalMessage" }, "description": "SMS messages received on this number, sorted oldest-first." } } }, "RentalCreateRequest": { "type": "object", "required": [ "service_id", "duration" ], "additionalProperties": false, "properties": { "service_id": { "$ref": "#/components/schemas/ServiceId", "description": "Service to rent a number for. Use a catalog service id from\n`GET /v1/services`.\n" }, "duration": { "type": "string", "enum": [ "3D", "7D", "14D", "30D" ], "description": "Rental period. Must be one of `3D`/`7D`/`14D`/`30D`.\n" }, "country": { "type": "string", "pattern": "^[a-z]{2}$", "default": "us", "description": "ISO-3166-1 alpha-2, lowercased. Only `us` is supported." }, "auto_renew": { "type": "boolean", "default": false, "description": "Automatically renew the rental for the same duration at expiry." }, "max_price_cents": { "type": "integer", "minimum": 1, "maximum": 1000000, "description": "Optional price ceiling. Drift within the cap charges silently;\ndrift above the cap returns `409 PRICE_OVER_CAP` with the current\navailable price in the error details so callers can decide whether\nto retry with a higher cap. Omit to require an exact match to the\ncurrent catalog price.\n" }, "webhook_endpoint_id": { "allOf": [ { "$ref": "#/components/schemas/WebhookEndpointId" } ], "description": "If set, scopes the create-time `rental.created` delivery to this\nendpoint only. Later rental events (`code_received`, `renewed`,\n`expired`, `cancelled`, `auto_renew_disabled`) still fan out to\nevery enabled endpoint whose `event_types` match.\n" } } }, "RentalListResponse": { "type": "object", "required": [ "success", "data", "has_more", "next_cursor", "request_id" ], "additionalProperties": false, "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Rental" }, "description": "Page of rental resources, newest-first." }, "has_more": { "type": "boolean", "description": "Whether additional pages exist beyond this one." }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` in the next request to advance the page. Null on the last page.", "example": "01HXYZ123ABC" }, "request_id": { "$ref": "#/components/schemas/RequestId" } } }, "RentalAutoRenewRequest": { "type": "object", "required": [ "enabled" ], "additionalProperties": false, "properties": { "enabled": { "type": "boolean", "description": "`true` to enable auto-renew; `false` to disable. Explicit state\n(not a toggle) - calling with the same value twice is safe.\n" } } }, "ProxyStatus": { "type": "string", "enum": [ "provisioning", "active", "expired", "refunded", "exhausted" ] }, "RotationMode": { "type": "string", "enum": [ "instant", "delayed_5s", "no_rotation_on_fail" ] }, "ProxyFormat": { "type": "string", "description": "Saved credential-format preference for the dashboard's list export. API `entries` are always `login:pass@host:port`.", "enum": [ "login_pass_host_port", "host_port_login_pass", "http_url", "socks5_url", "host_port", "login_pass_at_host_port", "json" ] }, "ProxyCredentials": { "type": "object", "required": [ "host", "port", "protocol", "username", "password" ], "additionalProperties": false, "properties": { "host": { "type": "string", "example": "proxy.voidmob.com" }, "port": { "type": "integer", "example": 9901 }, "protocol": { "type": "string", "enum": [ "http" ] }, "username": { "type": "string" }, "password": { "type": "string" } } }, "ProxyGateway": { "type": "object", "required": [ "host", "port", "protocol", "username", "password" ], "additionalProperties": false, "description": "Connection details. For a mobile/GB package this is the\npackage-level Flex gateway: geo, session stickiness, and rotation\nare controlled per request via underscore-prefixed parameters\nappended to `username` (see the proxies docs reference), and\n`username_geo_hint` is present. For an active Standard dedicated\nproxy it is the modem's own connection: `username` is used as-is,\n`port` is the HTTP port and `socks_port` is present.\n", "properties": { "host": { "type": "string", "example": "proxy.voidmob.com" }, "port": { "type": "integer", "example": 10092, "description": "Mobile/GB gateway port, or a dedicated proxy's HTTP port." }, "protocol": { "type": "string", "enum": [ "http" ] }, "username": { "type": "string", "description": "Mobile/GB: base username. Append parameters per request, e.g.\n`_c_US_s_session-1_ttl_5m` for a 5-minute sticky\nUS session. Dedicated: the proxy username, used as-is.\n" }, "password": { "type": "string" }, "username_geo_hint": { "type": "string", "description": "Mobile/GB only. Short hint pointing at the parameter syntax. The docs are authoritative." }, "socks_port": { "type": [ "integer", "null" ], "description": "Dedicated only. SOCKS5 port on the same host with the same credentials; null when the proxy has none." } } }, "ProxyList": { "type": "object", "required": [ "id", "proxy_id", "name", "rotation_period_seconds", "rotation_mode", "format", "credentials", "entries", "network", "activation_note", "created_at" ], "additionalProperties": false, "properties": { "id": { "$ref": "#/components/schemas/ProxyListId" }, "proxy_id": { "$ref": "#/components/schemas/ProxyId" }, "name": { "type": "string", "maxLength": 60 }, "country": { "type": [ "string", "null" ], "pattern": "^[A-Za-z]{2}$" }, "countries": { "type": [ "array", "null" ], "minItems": 2, "maxItems": 30, "items": { "type": "string", "pattern": "^[A-Za-z]{2}$" } }, "region": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "isp": { "type": [ "string", "null" ] }, "zip": { "type": [ "string", "null" ] }, "rotation_period_seconds": { "type": "integer", "minimum": -1, "maximum": 86400 }, "rotation_mode": { "$ref": "#/components/schemas/RotationMode" }, "format": { "$ref": "#/components/schemas/ProxyFormat" }, "credentials": { "oneOf": [ { "$ref": "#/components/schemas/ProxyCredentials" }, { "type": "null" } ], "description": "Gateway credentials. Null for IP-whitelist lists, which authenticate by source IP instead of login/password." }, "entries": { "type": "array", "items": { "type": "string" }, "description": "Ready-to-paste connection strings in `login:pass@host:port` form, regardless of the saved `format` (which applies to the dashboard's list export). For IP-whitelist lists these are bare `host:port` strings. For SOCKS5, use the same host, port and credentials with a `socks5://` scheme." }, "network": { "type": [ "string", "null" ], "description": "Comma-separated IPv4 addresses/subnets whitelisted for this list, or null for login/password lists. Set when the list is created; immutable afterwards - delete and recreate the list to change it." }, "activation_note": { "type": "string", "description": "Operational hint to surface to the end user." }, "created_at": { "type": "string", "format": "date-time" } } }, "Proxy": { "type": "object", "required": [ "id", "status", "data_gb_total", "data_bytes_used", "charged_price_cents", "expires_at", "gateway", "lists", "created_at" ], "additionalProperties": false, "properties": { "id": { "$ref": "#/components/schemas/ProxyId" }, "display_id": { "type": [ "string", "null" ], "description": "Human-facing order reference shown in the dashboard. Quote it in support tickets.", "example": "PRX08781M" }, "status": { "$ref": "#/components/schemas/ProxyStatus" }, "type": { "type": "string", "enum": [ "shared", "dedicated_standard", "dedicated_premium" ], "description": "`shared` is a mobile/GB package; the others are dedicated proxies." }, "country": { "type": [ "string", "null" ], "description": "Lowercase ISO code of a dedicated proxy's location. Null for mobile/GB packages.", "example": "us" }, "carrier": { "type": [ "string", "null" ], "description": "Mobile carrier of a dedicated proxy. Null for mobile/GB packages." }, "plan_id": { "oneOf": [ { "$ref": "#/components/schemas/ProxyPlanId" }, { "type": "null" } ], "description": "The plan used to purchase. Always `null` for a pool-backed sub-order - see `pool_id`." }, "pool_id": { "oneOf": [ { "$ref": "#/components/schemas/ProxyPoolId" }, { "type": "null" } ], "description": "The reseller GB pool this package was minted from, or `null` for a catalog purchase." }, "data_gb_total": { "type": "integer", "example": 100, "description": "Always 0 for dedicated proxies (unmetered)." }, "data_bytes_used": { "type": "integer", "format": "int64", "example": 0 }, "charged_price_cents": { "type": "integer", "description": "What the purchase charged, after any discount. Renewals and top-ups are not included." }, "expires_at": { "type": "string", "format": "date-time" }, "auto_renew": { "type": "boolean", "description": "Whether the proxy renews itself before `expires_at`. Settable on Standard dedicated proxies via `POST /v1/proxies/{id}/auto_renew`." }, "next_renewal_price_cents": { "type": [ "integer", "null" ], "description": "What a renewal (manual or auto-renew) charges right now, with\nyour current discount - pass it as `max_price_cents` to\n`POST /v1/proxies/{id}/renew`. Null when the proxy cannot be\nrenewed over the API at the moment (pool sub-order, Premium\ndedicated, dedicated not active or its plan no longer sold,\npackage past its renewal window).\n" }, "gateway": { "oneOf": [ { "$ref": "#/components/schemas/ProxyGateway" }, { "type": "null" } ], "description": "Connection credentials. Mobile/GB: the Flex gateway, null until\nthe package is active and `POST /v1/proxies/:id/flex_credentials`\nhas been called. Standard dedicated: populated while the proxy\nis active. Always null for Premium dedicated proxies.\n" }, "lists": { "type": "array", "items": { "$ref": "#/components/schemas/ProxyList" } }, "rotation_url": { "oneOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Customer-facing rotation URL for dedicated proxies. A simple GET\nrequest to this URL rotates the exit IP, no auth header needed.\nDesigned for anti-detect browser tools (AdsPower, GoLogin,\nDolphin) that accept a \"rotation URL\" field. Null for shared\n(gb) proxies. The same 60s per-proxy cooldown applies as\n`POST /v1/proxies/:id/rotate_ip`. Regenerable from the\ndashboard if leaked.\n" }, "created_at": { "type": "string", "format": "date-time" } } }, "ProxyUsage": { "type": "object", "required": [ "daily_bytes", "weekly_bytes", "monthly_bytes", "total_bytes", "total_gb_allocated", "remaining_bytes" ], "additionalProperties": false, "properties": { "daily_bytes": { "type": "integer", "format": "int64" }, "weekly_bytes": { "type": "integer", "format": "int64" }, "monthly_bytes": { "type": "integer", "format": "int64" }, "total_bytes": { "type": "integer", "format": "int64", "description": "Lifetime bytes used." }, "total_gb_allocated": { "type": "integer" }, "remaining_bytes": { "type": "integer", "format": "int64" } } }, "ProxyPlan": { "type": "object", "required": [ "id", "name", "type", "data_gb", "duration_days", "period", "quoted_price_cents", "available" ], "additionalProperties": false, "properties": { "id": { "$ref": "#/components/schemas/ProxyPlanId" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "shared", "dedicated_standard" ] }, "country": { "type": [ "string", "null" ] }, "country_name": { "type": [ "string", "null" ] }, "carrier": { "type": [ "string", "null" ], "description": "Standard dedicated plans only. Mobile carrier of the modem." }, "region": { "type": [ "string", "null" ], "description": "Standard dedicated plans only. Region the modem sits in; null if the plan takes any region." }, "data_gb": { "type": [ "integer", "null" ], "description": "Null for dedicated plans (unmetered)." }, "duration_days": { "type": "integer" }, "period": { "type": "string", "enum": [ "daily", "weekly", "monthly" ] }, "quoted_price_cents": { "type": "integer", "description": "Price after your discount - what a purchase charges." }, "available": { "type": "boolean", "description": "Always true for mobile/GB plans. For a Standard dedicated plan,\nwhether its own region has a modem free right now. Refreshes\nevery 10 minutes; a purchase re-checks before charging.\n" } } }, "ProxyPool": { "type": "object", "required": [ "id", "name", "total_gb", "allocated_gb", "remaining_gb", "price_per_gb_cents", "valid_until", "status", "self_extend", "created_at" ], "additionalProperties": false, "properties": { "id": { "$ref": "#/components/schemas/ProxyPoolId" }, "name": { "type": "string" }, "total_gb": { "type": "number", "description": "Lifetime GB purchased, including every extension." }, "allocated_gb": { "type": "number", "description": "GB currently held by live sub-orders." }, "remaining_gb": { "type": "number", "description": "total_gb minus allocated_gb. Includes frozen GB while lapsed." }, "price_per_gb_cents": { "type": "integer", "description": "Current per-GB rate charged on every self-serve extension. Set with you when the pool is provisioned; renegotiated rates apply to later extensions only." }, "valid_until": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "active", "lapsed" ] }, "self_extend": { "type": "object", "required": [ "enabled", "min_gb", "adds_days" ], "additionalProperties": false, "properties": { "enabled": { "type": "boolean", "description": "Whether POST /v1/proxy_pools/{id}/extend is allowed self-serve on this pool." }, "min_gb": { "type": "integer", "description": "Minimum gb accepted per self-serve extension." }, "adds_days": { "type": "integer", "description": "Days added to valid_until per extension." } } }, "created_at": { "type": "string", "format": "date-time" } } }, "CreateProxyRequest": { "oneOf": [ { "$ref": "#/components/schemas/CreateProxyFromPlanRequest" }, { "$ref": "#/components/schemas/CreateProxyFromPoolRequest" } ], "description": "Provide exactly one of `plan_id` (catalog purchase) or `pool_id` (mint from a reseller GB pool)." }, "CreateProxyFromPlanRequest": { "type": "object", "required": [ "plan_id", "max_price_cents" ], "additionalProperties": false, "properties": { "plan_id": { "$ref": "#/components/schemas/ProxyPlanId" }, "max_price_cents": { "type": "integer", "minimum": 0 }, "webhook_endpoint_id": { "$ref": "#/components/schemas/WebhookEndpointId" } } }, "CreateProxyFromPoolRequest": { "type": "object", "required": [ "pool_id", "data_gb", "duration_days" ], "additionalProperties": false, "properties": { "pool_id": { "$ref": "#/components/schemas/ProxyPoolId" }, "data_gb": { "type": "integer", "minimum": 1, "maximum": 10000 }, "duration_days": { "type": "integer", "minimum": 1, "maximum": 365 }, "webhook_endpoint_id": { "$ref": "#/components/schemas/WebhookEndpointId" } } }, "ExtendProxyPoolRequest": { "type": "object", "required": [ "gb", "max_price_cents" ], "additionalProperties": false, "properties": { "gb": { "type": "integer", "minimum": 1 }, "max_price_cents": { "type": "integer", "minimum": 0 } } }, "RenewProxyRequest": { "type": "object", "additionalProperties": false, "properties": { "max_price_cents": { "type": "integer", "minimum": 0, "description": "Required for a catalog (plan-backed) package; ignored for a pool-backed sub-order, where GB is drawn from the pool instead." } } }, "TopupProxyRequest": { "type": "object", "required": [ "additional_gb" ], "additionalProperties": false, "properties": { "additional_gb": { "type": "integer", "minimum": 1, "maximum": 1000 }, "max_price_cents": { "type": "integer", "minimum": 0, "description": "Required for a catalog (plan-backed) package; ignored for a pool-backed sub-order, where GB is drawn from the pool instead." } } }, "CreateProxyListRequest": { "type": "object", "required": [ "name" ], "additionalProperties": false, "description": "Exactly one of `country` or `countries` is required.\n`rotation_period_seconds`, `rotation_mode`, and `format` default when\nomitted.\n", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 60 }, "country": { "type": "string", "pattern": "^[A-Za-z]{2}$", "description": "ISO-3166-1 alpha-2 (either case accepted, echoed back as sent). Mutually exclusive with `countries`." }, "countries": { "type": "array", "minItems": 2, "maxItems": 30, "items": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "description": "Multi-country list. Mutually exclusive with `country`; subfilters (region/city/isp/zip) are not allowed with `countries`." }, "region": { "type": "string", "maxLength": 80 }, "city": { "type": "string", "maxLength": 80 }, "isp": { "type": "string", "maxLength": 80 }, "zip": { "type": "string", "maxLength": 20 }, "rotation_period_seconds": { "type": "integer", "minimum": -1, "maximum": 86400, "default": 0 }, "rotation_mode": { "allOf": [ { "$ref": "#/components/schemas/RotationMode" } ], "default": "instant" }, "format": { "allOf": [ { "$ref": "#/components/schemas/ProxyFormat" } ], "default": "login_pass_host_port" }, "network": { "type": "string", "maxLength": 120, "description": "IP-whitelist authentication. Comma-separated IPv4 addresses and/or /24-/32 subnets (max 5 entries, no spaces). The list then authenticates by source IP and returns `credentials: null`. Set at creation only - it cannot be changed on an existing list. An address can be whitelisted on one list at a time; a clash returns 409 PROXY_NETWORK_UNAVAILABLE." } } }, "UpdateProxyListRequest": { "type": "object", "additionalProperties": false, "description": "Partial update. Same geo rules as create (country xor countries).", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 60 }, "country": { "type": "string", "pattern": "^[a-z]{2}$" }, "countries": { "type": "array", "minItems": 2, "maxItems": 30, "items": { "type": "string", "pattern": "^[a-z]{2}$" } }, "region": { "type": "string", "maxLength": 80 }, "city": { "type": "string", "maxLength": 80 }, "isp": { "type": "string", "maxLength": 80 }, "zip": { "type": "string", "maxLength": 20 }, "rotation_period_seconds": { "type": "integer", "minimum": -1, "maximum": 86400 }, "rotation_mode": { "$ref": "#/components/schemas/RotationMode" }, "format": { "$ref": "#/components/schemas/ProxyFormat" } } }, "GeoNode": { "type": "object", "required": [ "name", "available_nodes" ], "additionalProperties": false, "properties": { "name": { "type": "string" }, "available_nodes": { "type": "integer" } } }, "GeoCountry": { "type": "object", "required": [ "code", "name", "available_nodes" ], "additionalProperties": false, "properties": { "code": { "type": "string", "pattern": "^[a-z]{2}$" }, "name": { "type": "string" }, "available_nodes": { "type": "integer" } } }, "WebhookEventType": { "type": "string", "enum": [ "*", "verification.created", "verification.code_received", "verification.cancelled", "verification.completed", "verification.expired", "verification.failed", "rental.created", "rental.message_received", "rental.code_received", "rental.renewed", "rental.expired", "rental.cancelled", "rental.auto_renew_disabled", "proxy.ready", "proxy.provisioning_failed", "proxy.expired", "proxy.traffic_low", "proxy.traffic_exhausted", "proxy.renewed", "proxy_pool.low", "proxy_pool.expiring", "proxy_pool.extended", "esim.created", "esim.provisioning_failed", "esim.topup_added", "esim.expired", "esim.cancelled", "esim.refunded" ] }, "WebhookEndpoint": { "type": "object", "required": [ "id", "url", "event_types", "enabled", "created_at" ], "additionalProperties": false, "properties": { "id": { "$ref": "#/components/schemas/WebhookEndpointId" }, "url": { "type": "string", "format": "uri" }, "event_types": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEventType" } }, "enabled": { "type": "boolean" }, "consecutive_failures": { "type": "integer" }, "last_success_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_failure_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } }, "WebhookEndpointCreated": { "allOf": [ { "$ref": "#/components/schemas/WebhookEndpoint" }, { "type": "object", "required": [ "signing_secret" ], "properties": { "signing_secret": { "type": "string", "description": "The HMAC-SHA256 signing secret for this endpoint. Returned\n**once** on creation and never again. Store it securely. Used\nto verify the `X-VoidMob-Signature` header on inbound webhook\ndeliveries.\n", "example": "whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" } } } ] }, "CreateWebhookEndpointRequest": { "type": "object", "required": [ "url" ], "additionalProperties": false, "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048 }, "event_types": { "type": "array", "maxItems": 32, "items": { "$ref": "#/components/schemas/WebhookEventType" }, "default": [ "*" ] } } }, "EsimProductFeatures": { "type": "object", "required": [ "has_5g", "has_hotspot", "has_calls", "has_sms", "supports_topup", "phone_number_prefix", "call_minutes", "calls_unlimited", "voice_note" ], "additionalProperties": false, "properties": { "has_5g": { "type": "boolean" }, "has_hotspot": { "type": "boolean" }, "has_calls": { "type": "boolean" }, "has_sms": { "type": "boolean" }, "supports_topup": { "type": "boolean" }, "phone_number_prefix": { "type": [ "string", "null" ], "description": "Dial code and country of the phone number included with the plan, e.g. \"+44 (United Kingdom)\". Null for data-only plans.", "example": "+44 (United Kingdom)" }, "call_minutes": { "type": [ "integer", "null" ], "description": "Included call minutes. Null when calls are unlimited, when the plan has no calls, or when the allowance is not published.", "example": 450 }, "calls_unlimited": { "type": "boolean", "description": "True when the plan includes unlimited calls." }, "voice_note": { "type": [ "string", "null" ], "description": "How the included number and calls work. Null for data-only plans.", "example": "Minutes cover calls to UK numbers. Receiving calls is free. SMS is not included." } } }, "EsimProductNetwork": { "type": "object", "required": [ "country", "name", "has_4g", "has_5g" ], "additionalProperties": false, "properties": { "country": { "type": "string", "description": "ISO-3166-1 alpha-2 country code (uppercase) where the carrier serves this plan.", "example": "GB" }, "name": { "type": "string", "description": "Carrier name.", "example": "Vodafone" }, "has_4g": { "type": "boolean" }, "has_5g": { "type": "boolean" } } }, "EsimProductResource": { "type": "object", "required": [ "id", "title", "countries", "region", "country_count", "routing_location", "data_limit_gb", "data_unlimited", "validity_days", "network_type", "speed", "speed_note", "activation_policy", "networks", "features", "price_cents", "currency" ], "additionalProperties": false, "properties": { "id": { "type": "string", "description": "Public product identifier (prefixed `prod_`).", "example": "prod_abc123" }, "title": { "type": "string", "description": "Plan name as the VoidMob dashboard shows it. Data and validity are not repeated in the name; read them from `data_limit_gb` / `data_unlimited` and `validity_days`.", "example": "Europe" }, "countries": { "type": "array", "items": { "type": "string" }, "description": "ISO-3166-1 alpha-2 country codes (uppercase) covered by this plan.", "example": [ "DE", "FR", "IT" ] }, "region": { "type": [ "string", "null" ], "description": "Regional grouping label, e.g. \"Europe\". Null for single-country plans.", "example": "Europe" }, "country_count": { "type": "integer", "description": "Number of countries covered.", "example": 30 }, "routing_location": { "type": [ "string", "null" ], "description": "Network routing hint for this eSIM (e.g. country where its data egresses). Null when not applicable." }, "data_limit_gb": { "type": [ "number", "null" ], "description": "Data allowance in GB. Plans sold as 1 TB report 1024. Null when `data_unlimited` is true.", "example": 10 }, "data_unlimited": { "type": "boolean", "description": "Whether the plan has an unlimited data allowance.", "example": false }, "validity_days": { "type": "integer", "description": "Plan validity in days from activation.", "example": 30 }, "network_type": { "type": "string", "description": "Network generations the plan uses.", "example": "5G/4G/LTE" }, "speed": { "type": "string", "description": "Speed policy, e.g. \"Unrestricted\", \"Limited\" or \"Total 30 GB at full speed, 2Mbps speed cap afterwards\".", "example": "Unrestricted" }, "speed_note": { "type": [ "string", "null" ], "description": "Plain-language explanation of a capped speed. Null when the speed needs no explanation.", "example": "1GB/day at high speed, then 512 Kbps for the rest of the day" }, "activation_policy": { "type": "string", "description": "When the plan's validity starts.", "example": "Package activates upon first data usage." }, "networks": { "type": "array", "items": { "$ref": "#/components/schemas/EsimProductNetwork" }, "description": "Carrier networks the plan uses, one entry per country and carrier, sorted by country then name. Refreshed about weekly; empty for a plan added since the last refresh, and for top-up packages (a top-up runs on its eSIM's networks)." }, "features": { "$ref": "#/components/schemas/EsimProductFeatures" }, "price_cents": { "type": "integer", "description": "Per-caller listed price in USD cents.", "example": 1500 }, "currency": { "type": "string", "enum": [ "USD" ] } } }, "EsimResource": { "type": "object", "required": [ "id", "status", "product_id", "is_topup", "parent_order_id", "iccid", "activation_code", "qr_code_url", "smdp_address", "data_limit_gb", "data_unlimited", "validity_days", "countries", "routing_location", "charged_price_cents", "currency", "created_at", "completed_at", "expires_at" ], "additionalProperties": false, "properties": { "id": { "type": "string", "description": "Public eSIM order identifier (prefixed `esim_`).", "example": "esim_01HXYZ123ABC" }, "status": { "type": "string", "enum": [ "processing", "completed", "cancelled", "refunded", "expired" ], "description": "Current lifecycle state of the eSIM order." }, "product_id": { "type": [ "string", "null" ], "description": "Public product id this order was placed for (prefixed `prod_`). Null for legacy orders.", "example": "prod_abc123" }, "is_topup": { "type": "boolean", "description": "Whether this order is a data topup on an existing eSIM." }, "parent_order_id": { "type": [ "string", "null" ], "description": "Public id of the parent eSIM order when `is_topup` is true. Null for primary orders.", "example": "esim_01HXYZ000ABC" }, "iccid": { "type": [ "string", "null" ], "description": "ICCID (SIM card identifier). Present on primary completed orders; null for topups and processing orders.", "example": "89012345678901234567" }, "activation_code": { "type": [ "string", "null" ], "description": "SM-DP+ matching ID used by the device to install the profile. Combine\nwith `smdp_address` to form the full LPA URI: `LPA:1$$`.\nThe PNG returned from `qr_code_url` already encodes the full URI for direct\nscanning. Null for topups and processing orders.\n", "example": "K2-2VOZBJ-22QT3D" }, "qr_code_url": { "type": [ "string", "null" ], "description": "URL to a PNG image of the activation QR code. Null for topups and\norders that have not completed. Cache aggressively - this URL is\nstable for the lifetime of the eSIM.\n", "example": "https://dashboard.voidmob.com/api/v1/esims/esim_01HXYZ123ABC/qr.png" }, "smdp_address": { "type": [ "string", "null" ], "description": "SM-DP+ server hostname. Combine with `activation_code` to build the LPA URI for manual activation. Null for topups and processing orders.", "example": "smdp.io" }, "data_limit_gb": { "type": [ "number", "null" ], "description": "Data allowance in GB. Null when `data_unlimited` is true.", "example": 10 }, "data_unlimited": { "type": "boolean", "description": "Whether this plan includes unlimited data." }, "validity_days": { "type": "integer", "description": "Plan validity in days from activation.", "example": 30 }, "countries": { "type": "array", "items": { "type": "string" }, "description": "ISO-3166-1 alpha-2 country codes (uppercase) where the plan is usable.", "example": [ "DE", "FR", "IT" ] }, "routing_location": { "type": [ "string", "null" ], "description": "Network routing hint for this eSIM (e.g. country where its data egresses). Informational only." }, "charged_price_cents": { "type": "integer", "description": "Amount deducted from the wallet for this order in USD cents.", "example": 1500 }, "currency": { "type": "string", "enum": [ "USD" ] }, "created_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the order was placed." }, "completed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601 timestamp when the eSIM was fully provisioned. Null until status is `completed`." }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601 timestamp when the eSIM plan expires. Null until the eSIM is activated." } } }, "EsimCreateBody": { "type": "object", "required": [ "product_id" ], "additionalProperties": false, "properties": { "product_id": { "type": "string", "description": "Public product id (prefixed `prod_`) from the eSIM catalog.", "example": "prod_abc123" }, "max_price_cents": { "type": "integer", "minimum": 0, "description": "Optional price ceiling in USD cents. If the current price exceeds\nthis value the call returns `409 PRICE_OVER_CAP`. Omit to\naccept any price.\n" }, "parent_order_id": { "type": "string", "description": "Public id of the eSIM to top up (prefixed `esim_`). Any order on\nthat eSIM is accepted - a topup id resolves to the base order it\nsits on. Ignored on `POST /esims/{id}/topups` where the path\nparameter takes precedence.\n", "example": "esim_01HXYZ000ABC" }, "webhook_endpoint_id": { "type": "string", "description": "If set, scope this order's webhook events to this endpoint only.\n", "example": "whep_01HXYZ123ABC" } } }, "EsimEnvelope": { "type": "object", "required": [ "success", "data" ], "additionalProperties": false, "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "required": [ "esim" ], "additionalProperties": false, "properties": { "esim": { "$ref": "#/components/schemas/EsimResource" } } } } }, "EsimListEnvelope": { "type": "object", "required": [ "success", "data" ], "additionalProperties": false, "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "required": [ "esims", "next_cursor" ], "additionalProperties": false, "properties": { "esims": { "type": "array", "items": { "$ref": "#/components/schemas/EsimResource" }, "description": "Page of eSIM order resources, newest-first." }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` in the next request to advance the page. Null on the last page.", "example": "01HXYZ123ABC" } } } } }, "EsimProductEnvelope": { "type": "object", "required": [ "success", "data" ], "additionalProperties": false, "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "required": [ "product" ], "additionalProperties": false, "properties": { "product": { "$ref": "#/components/schemas/EsimProductResource" } } } } }, "EsimProductListEnvelope": { "type": "object", "required": [ "success", "data" ], "additionalProperties": false, "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "required": [ "products", "next_cursor" ], "additionalProperties": false, "properties": { "products": { "type": "array", "items": { "$ref": "#/components/schemas/EsimProductResource" }, "description": "Page of eSIM product resources." }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` in the next request to advance the page. Null on the last page.", "example": "01HXYZ123ABC" } } } } }, "EsimUsagePackage": { "type": "object", "required": [ "name", "total_mb", "total_gb", "used_mb", "used_gb", "remaining_mb", "remaining_gb", "percent_used", "activation_date", "expiration_date" ], "additionalProperties": false, "properties": { "name": { "type": "string", "description": "Data package name.", "example": "Europe 10GB" }, "total_mb": { "type": "number", "description": "Total data allocation in megabytes.", "example": 10240 }, "total_gb": { "type": "number", "description": "Total data allocation in gigabytes.", "example": 10 }, "used_mb": { "type": "number", "description": "Data consumed in megabytes.", "example": 1024 }, "used_gb": { "type": "number", "description": "Data consumed in gigabytes.", "example": 1 }, "remaining_mb": { "type": "number", "description": "Remaining data in megabytes.", "example": 9216 }, "remaining_gb": { "type": "number", "description": "Remaining data in gigabytes.", "example": 9 }, "percent_used": { "type": "number", "description": "Percentage of allocation consumed (0-100).", "example": 10 }, "activation_date": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601 timestamp when the package was activated. Null if not yet activated." }, "expiration_date": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601 timestamp when the package expires. Null if not yet activated." } } }, "EsimUsageEnvelope": { "type": "object", "required": [ "success", "data" ], "additionalProperties": false, "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "required": [ "usage" ], "additionalProperties": false, "properties": { "usage": { "type": "object", "required": [ "esim_id", "esim_status", "packages" ], "additionalProperties": false, "properties": { "esim_id": { "type": "string", "description": "Public eSIM order id (prefixed `esim_`).", "example": "esim_01HXYZ123ABC" }, "esim_status": { "type": "string", "enum": [ "processing", "completed", "cancelled", "refunded", "expired" ], "description": "Current status of the eSIM order at time of query." }, "packages": { "type": "array", "items": { "$ref": "#/components/schemas/EsimUsagePackage" }, "description": "Per-bundle usage breakdown. One entry per data bundle on this eSIM (including topups)." } } } } } } }, "EsimTopupListEnvelope": { "type": "object", "required": [ "success", "data" ], "additionalProperties": false, "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "required": [ "supports_topup", "topups" ], "additionalProperties": false, "properties": { "supports_topup": { "type": "boolean", "description": "Whether the parent product's family supports topup add-ons." }, "topups": { "type": "array", "items": { "$ref": "#/components/schemas/EsimProductResource" }, "description": "Available topup products. Empty when `supports_topup` is false." } } } } }, "PublicErrorCode": { "type": "string", "description": "Stable enum of all public error codes. Each code maps to a fixed HTTP status; see the per-response components for status/body shape.", "enum": [ "UNAUTHENTICATED", "IP_NOT_ALLOWED", "FORBIDDEN", "NOT_FOUND", "RATE_LIMITED", "IDEMPOTENCY_CONFLICT", "IDEMPOTENCY_REPLAY_IN_FLIGHT", "VALIDATION_ERROR", "SERVICE_UNAVAILABLE", "SERVICE_NOT_FOUND", "SERVICE_OUT_OF_STOCK", "INSUFFICIENT_BALANCE", "DAILY_SPEND_CAP_EXCEEDED", "VERIFICATION_NOT_FOUND", "WEBHOOK_ENDPOINT_NOT_FOUND", "CANCEL_NOT_ALLOWED", "CANCEL_RATE_LIMITED", "COMPLETE_NOT_ALLOWED", "REUSE_NOT_ALLOWED", "REUSE_RATE_LIMITED", "INTERNAL_ERROR", "PROXY_PLAN_NOT_FOUND", "PROXY_NOT_FOUND", "PROXY_LIST_NOT_FOUND", "PROXY_NOT_READY", "PROXY_EXPIRED", "PROXY_EXHAUSTED", "PROXY_LIST_LIMIT_EXCEEDED", "PROXY_GEO_CONFLICT", "PROXY_NETWORK_UNAVAILABLE", "PROVISIONING_FAILED", "PROVIDER_TIMEOUT", "PRICE_MISMATCH", "POOL_NOT_FOUND", "POOL_LAPSED", "POOL_INSUFFICIENT_GB", "POOL_SELF_EXTEND_DISABLED", "POOL_MIN_EXTEND", "OUT_OF_STOCK_AT_PRICE", "PRICE_OVER_CAP", "BAD_SERVICE", "ALREADY_COMPLETED", "CANCEL_WINDOW_NOT_OPEN", "NOT_SUPPORTED", "PROVIDER_ERROR", "LTR_NOT_AVAILABLE", "RE_RENT_NOT_AVAILABLE", "DEDICATED_NOT_AVAILABLE", "PRODUCT_NOT_FOUND", "ESIM_NOT_FOUND", "PARENT_ORDER_NOT_FOUND", "PARENT_ORDER_NOT_ACTIVE", "TOPUP_INCOMPATIBLE", "PRODUCT_UNAVAILABLE", "USAGE_UNAVAILABLE", "ESIM_GONE", "ESIM_NOT_ACTIVE" ] }, "ErrorEnvelope": { "type": "object", "required": [ "success", "error" ], "additionalProperties": false, "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message", "docs_url", "request_id" ], "additionalProperties": false, "properties": { "code": { "$ref": "#/components/schemas/PublicErrorCode" }, "message": { "type": "string", "description": "User-safe human-readable message. Never leaks internals." }, "docs_url": { "type": "string", "format": "uri", "description": "Link to this error code in the developer docs (dashboard sign-in required)." }, "request_id": { "type": "string", "description": "Server-assigned identifier for this request. Quote in support tickets." }, "details": { "type": "object", "description": "Optional structured payload. Present for PRICE_OVER_CAP (available_price_cents, max_price_cents), VALIDATION_ERROR (issues[]), and PROXY_GEO_CONFLICT (issues[]).", "additionalProperties": true } } } } }, "EventBase": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "additionalProperties": false, "properties": { "id": { "type": "string", "description": "Unique delivery id. Use for deduping on your side.", "example": "evt_01HXYZ123456789ABCDEFG" }, "type": { "$ref": "#/components/schemas/WebhookEventType" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "additionalProperties": true } } }, "VerificationEvent": { "allOf": [ { "$ref": "#/components/schemas/EventBase" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "verification" ], "properties": { "verification": { "$ref": "#/components/schemas/Verification" } } } } } ] }, "ProxyEvent": { "allOf": [ { "$ref": "#/components/schemas/EventBase" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "proxy" ], "properties": { "proxy": { "$ref": "#/components/schemas/Proxy" } } } } } ] }, "ProxyLifecycleEvent": { "allOf": [ { "$ref": "#/components/schemas/EventBase" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "proxy_id" ], "properties": { "proxy_id": { "$ref": "#/components/schemas/ProxyId" }, "display_id": { "type": [ "string", "null" ], "description": "Human-facing order reference shown in the dashboard. Quote it in support tickets." }, "refunded_cents": { "type": "integer", "description": "Present on `proxy.provisioning_failed` - the amount auto-refunded, in USD cents." }, "remaining_bytes": { "type": "integer", "format": "int64", "description": "Present on `proxy.traffic_low` - traffic left when the threshold fired." } } } } } ] }, "ProxyPoolEvent": { "allOf": [ { "$ref": "#/components/schemas/EventBase" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "pool_id", "remaining_gb", "valid_until" ], "properties": { "pool_id": { "$ref": "#/components/schemas/ProxyPoolId" }, "remaining_gb": { "type": "number", "description": "Pool's remaining_gb at the moment this event fired." }, "valid_until": { "type": "string", "format": "date-time" }, "added_gb": { "type": "integer", "description": "Present on `proxy_pool.extended` - GB added by this extension." }, "charged_price_cents": { "type": "integer", "description": "Present on `proxy_pool.extended` - the wallet charge for this extension." } } } } } ] }, "RentalEvent": { "allOf": [ { "$ref": "#/components/schemas/EventBase" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "rental" ], "properties": { "rental": { "$ref": "#/components/schemas/Rental" } } } } } ] }, "RentalMessageEvent": { "allOf": [ { "$ref": "#/components/schemas/EventBase" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "rental", "message" ], "properties": { "rental": { "$ref": "#/components/schemas/Rental" }, "message": { "$ref": "#/components/schemas/RentalWebhookMessage" } } } } } ] }, "EsimEvent": { "allOf": [ { "$ref": "#/components/schemas/EventBase" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "esim" ], "properties": { "esim": { "$ref": "#/components/schemas/EsimResource" } } } } } ] } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current rate-limit window for this endpoint group.", "schema": { "type": "integer", "example": 60 } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current rate-limit window.", "schema": { "type": "integer", "example": 42 } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current rate-limit window resets.", "schema": { "type": "integer", "format": "int64", "example": 1735200000 } }, "Retry-After": { "description": "Number of seconds the client should wait before retrying. Present on\n429 responses and on 409 IDEMPOTENCY_REPLAY_IN_FLIGHT.\n", "schema": { "type": "integer", "example": 5 } }, "ETag": { "description": "Weak entity tag for cacheable GET responses. Use with `If-None-Match` for cheap polling.", "schema": { "type": "string", "example": "W/\"3f8e2b9a01234567\"" } } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "description": "Client-supplied key (any string, up to 255 chars) that scopes idempotent\nreplay for write requests. Required on every POST, PATCH, and DELETE.\nReplays with the same key + same body return the cached response;\nsame key with a different body returns `IDEMPOTENCY_CONFLICT`. Headers\nare case-insensitive; both `Idempotency-Key` and `idempotency-key` work.\n", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255, "example": "7c4f08c2-2a4f-4c8e-a1d2-9c2b9c8f7e10" } }, "IfNoneMatch": { "name": "If-None-Match", "in": "header", "description": "Pass the most recent `ETag` to get `304 Not Modified` when the\nunderlying resource has not changed. Cheap-poll friendly.\n", "required": false, "schema": { "type": "string", "example": "W/\"3f8e2b9a01234567\"" } }, "CountryQuery": { "name": "country", "in": "query", "description": "ISO-3166-1 alpha-2 country code, lowercased. Defaults to `us` for SMS endpoints.", "required": false, "schema": { "type": "string", "pattern": "^[a-z]{2}$", "example": "us" } }, "RentalId": { "name": "id", "in": "path", "required": true, "description": "Long-term rental identifier (`ren_` prefix).", "schema": { "$ref": "#/components/schemas/RentalId" } } }, "responses": { "UNAUTHENTICATED": { "description": "401 - Authentication required.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "UNAUTHENTICATED", "message": "Authentication required.", "docs_url": "https://dashboard.voidmob.com/developers/docs?doc=errors#unauthenticated", "request_id": "req_01HXYZ123456789ABCDEFG" } } } } }, "IP_NOT_ALLOWED": { "description": "403 - Request source IP is not permitted for this key.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "IP_NOT_ALLOWED", "message": "Request source IP is not permitted for this key.", "docs_url": "https://dashboard.voidmob.com/developers/docs?doc=errors#ip_not_allowed", "request_id": "req_01HXYZ123456789ABCDEFG" } } } } }, "FORBIDDEN": { "description": "403 - Your account cannot perform this action.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "FORBIDDEN", "message": "Your account cannot perform this action.", "docs_url": "https://dashboard.voidmob.com/developers/docs?doc=errors#forbidden", "request_id": "req_01HXYZ123456789ABCDEFG" } } } } }, "NOT_FOUND": { "description": "404 - The requested resource was not found.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "NOT_FOUND", "message": "The requested resource was not found.", "docs_url": "https://dashboard.voidmob.com/developers/docs?doc=errors#not_found", "request_id": "req_01HXYZ123456789ABCDEFG" } } } } }, "RATE_LIMITED": { "description": "429 - Rate limit exceeded. Retry after the indicated interval.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry after the indicated interval.", "docs_url": "https://dashboard.voidmob.com/developers/docs?doc=errors#rate_limited", "request_id": "req_01HXYZ123456789ABCDEFG" } } } } }, "IDEMPOTENCY_CONFLICT": { "description": "409 - Idempotency key reused with a different request body.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "IDEMPOTENCY_CONFLICT", "message": "Idempotency key reused with a different request body.", "docs_url": "https://dashboard.voidmob.com/developers/docs?doc=errors#idempotency_conflict", "request_id": "req_01HXYZ123456789ABCDEFG" } } } } }, "IDEMPOTENCY_REPLAY_IN_FLIGHT": { "description": "409 - Original request is still processing. Retry shortly.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "IDEMPOTENCY_REPLAY_IN_FLIGHT", "message": "Original request is still processing. Retry shortly.", "docs_url": "https://dashboard.voidmob.com/developers/docs?doc=errors#idempotency_replay_in_flight", "request_id": "req_01HXYZ123456789ABCDEFG" } } } } }, "VALIDATION_ERROR": { "description": "400 - Request failed validation.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Request failed validation.", "docs_url": "https://dashboard.voidmob.com/developers/docs?doc=errors#validation_error", "request_id": "req_01HXYZ123456789ABCDEFG" } } } } }, "SERVICE_UNAVAILABLE": { "description": "503 - Service is currently unavailable.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "SERVICE_UNAVAILABLE", "message": "Service is currently unavailable.", "docs_url": "https://dashboard.voidmob.com/developers/docs?doc=errors#service_unavailable", "request_id": "req_01HXYZ123456789ABCDEFG" } } } } }, "SERVICE_NOT_FOUND": { "description": "404 - Unknown service id.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "SERVICE_NOT_FOUND", "message": "Unknown service id.", "docs_url": "https://dashboard.voidmob.com/developers/docs?doc=errors#service_not_found", "request_id": "req_01HXYZ123456789ABCDEFG" } } } } }, "SERVICE_OUT_OF_STOCK": { "description": "503 - This service is temporarily unavailable. Please try again shortly.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "SERVICE_OUT_OF_STOCK", "message": "This service is temporarily unavailable. Please try again shortly.", "docs_url": "https://dashboard.voidmob.com/developers/docs?doc=errors#service_out_of_stock", "request_id": "req_01HXYZ123456789ABCDEFG" } } } } }, "INSUFFICIENT_BALANCE": { "description": "402 - Your wallet balance is too low for this purchase.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your wallet balance is too low for this purchase.", "docs_url": "https://dashboard.voidmob.com/developers/docs?doc=errors#insufficient_balance", "request_id": "req_01HXYZ123456789ABCDEFG" } } } } }, "DAILY_SPEND_CAP_EXCEEDED": { "description": "402 - This key has reached its daily spend cap.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "DAILY_SPEND_CAP_EXCEEDED", "message": "This key has reached its daily spend cap.", "docs_url": "https://dashboard.voidmob.com/developers/docs?doc=errors#daily_spend_cap_exceeded", "request_id": "req_01HXYZ123456789ABCDEFG" } } } } }, "VERIFICATION_NOT_FOUND": { "description": "404 - Verification not found.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "VERIFICATION_NOT_FOUND", "message": "Verification not found.", "docs_url": "https://dashboard.voidmob.com/developers/docs?doc=errors#verification_not_found", "request_id": "req_01HXYZ123456789ABCDEFG" } } } } }, "WEBHOOK_ENDPOINT_NOT_FOUND": { "description": "404 - Webhook endpoint not found.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "WEBHOOK_ENDPOINT_NOT_FOUND", "message": "Webhook endpoint not found.", "docs_url": "https://dashboard.voidmob.com/developers/docs?doc=errors#webhook_endpoint_not_found", "request_id": "req_01HXYZ123456789ABCDEFG" } } } } }, "CANCEL_NOT_ALLOWED": { "description": "409 - This verification can no longer be cancelled.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "CANCEL_NOT_ALLOWED", "message": "This verification can no longer be cancelled.", "docs_url": "https://dashboard.voidmob.com/developers/docs?doc=errors#cancel_not_allowed", "request_id": "req_01HXYZ123456789ABCDEFG" } } } } }, "CANCEL_RATE_LIMITED": { "description": "429 - Too many cancellations recently. Try again later.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "CANCEL_RATE_LIMITED", "message": "Too many cancellations recently. Try again later.", "docs_url": "https://dashboard.voidmob.com/developers/docs?doc=errors#cancel_rate_limited", "request_id": "req_01HXYZ123456789ABCDEFG" } } } } }, "COMPLETE_NOT_ALLOWED": { "description": "409 - This verification can no longer be completed - it is already in a terminal state.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "COMPLETE_NOT_ALLOWED", "message": "This verification can no longer be completed - it is already in a terminal state.", "docs_url": "https://dashboard.voidmob.com/developers/docs?doc=errors#complete_not_allowed", "request_id": "req_01HXYZ123456789ABCDEFG" } } } } }, "REUSE_NOT_ALLOWED": { "description": "409 - Reuse is not available for this verification. Check allow_reuse / allow_paid_reuse on the verification before calling.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "REUSE_NOT_ALLOWED", "message": "Reuse is not available for this verification. Check allow_reuse / allow_paid_reuse on the verification before calling.", "docs_url": "https://dashboard.voidmob.com/developers/docs?doc=errors#reuse_not_allowed", "request_id": "req_01HXYZ123456789ABCDEFG" } } } } }, "REUSE_RATE_LIMITED": { "description": "429 - Too many reuse attempts on this verification. Try again shortly.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "REUSE_RATE_LIMITED", "message": "Too many reuse attempts on this verification. Try again shortly.", "docs_url": "https://dashboard.voidmob.com/developers/docs?doc=errors#reuse_rate_limited", "request_id": "req_01HXYZ123456789ABCDEFG" } } } } }, "INTERNAL_ERROR": { "description": "500 - An unexpected error occurred. Please try again.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Please try again.", "docs_url": "https://dashboard.voidmob.com/developers/docs?doc=errors#internal_error", "request_id": "req_01HXYZ123456789ABCDEFG" } } } } }, "PROXY_PLAN_NOT_FOUND": { "description": "404 - Unknown proxy plan id.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "PROXY_PLAN_NOT_FOUND", "message": "Unknown proxy plan id.", "docs_url": "https://dashboard.voidmob.com/developers/docs?doc=errors#proxy_plan_not_found", "request_id": "req_01HXYZ123456789ABCDEFG" } } } } }, "PROXY_NOT_FOUND": { "description": "404 - Proxy not found.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "PROXY_NOT_FOUND", "message": "Proxy not found.", "docs_url": "https://dashboard.voidmob.com/developers/docs?doc=errors#proxy_not_found", "request_id": "req_01HXYZ123456789ABCDEFG" } } } } }, "PROXY_LIST_NOT_FOUND": { "description": "404 - Proxy list not found.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "PROXY_LIST_NOT_FOUND", "message": "Proxy list not found.", "docs_url": "https://dashboard.voidmob.com/developers/docs?doc=errors#proxy_list_not_found", "request_id": "req_01HXYZ123456789ABCDEFG" } } } } }, "PROXY_NOT_READY": { "description": "409 - Proxy is still provisioning. Retry shortly.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "PROXY_NOT_READY", "message": "Proxy is still provisioning. Retry shortly.", "docs_url": "https://dashboard.voidmob.com/developers/docs?doc=errors#proxy_not_ready", "request_id": "req_01HXYZ123456789ABCDEFG" } } } } }, "PROXY_EXPIRED": { "description": "409 - Proxy has expired.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "PROXY_EXPIRED", "message": "Proxy has expired.", "docs_url": "https://dashboard.voidmob.com/developers/docs?doc=errors#proxy_expired", "request_id": "req_01HXYZ123456789ABCDEFG" } } } } }, "PROXY_EXHAUSTED": { "description": "409 - Proxy traffic allocation is exhausted.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "PROXY_EXHAUSTED", "message": "Proxy traffic allocation is exhausted.", "docs_url": "https://dashboard.voidmob.com/developers/docs?doc=errors#proxy_exhausted", "request_id": "req_01HXYZ123456789ABCDEFG" } } } } }, "PROXY_LIST_LIMIT_EXCEEDED": { "description": "409 - Maximum proxy lists per package reached.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "PROXY_LIST_LIMIT_EXCEEDED", "message": "Maximum proxy lists per package reached.", "docs_url": "https://dashboard.voidmob.com/developers/docs?doc=errors#proxy_list_limit_exceeded", "request_id": "req_01HXYZ123456789ABCDEFG" } } } } }, "PROXY_GEO_CONFLICT": { "description": "400 - Geo targeting is invalid - subfilters require a single country.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "PROXY_GEO_CONFLICT", "message": "Geo targeting is invalid - subfilters require a single country.", "docs_url": "https://dashboard.voidmob.com/developers/docs?doc=errors#proxy_geo_conflict", "request_id": "req_01HXYZ123456789ABCDEFG" } } } } }, "PROXY_NETWORK_UNAVAILABLE": { "description": "409 - One or more of these IPs is not available for whitelisting.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "PROXY_NETWORK_UNAVAILABLE", "message": "One or more of these IPs is not available for whitelisting.", "docs_url": "https://dashboard.voidmob.com/developers/docs?doc=errors#proxy_network_unavailable", "request_id": "req_01HXYZ123456789ABCDEFG" } } } } }, "PROVISIONING_FAILED": { "description": "502 - Proxy provisioning failed. Funds have been refunded.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "PROVISIONING_FAILED", "message": "Proxy provisioning failed. Funds have been refunded.", "docs_url": "https://dashboard.voidmob.com/developers/docs?doc=errors#provisioning_failed", "request_id": "req_01HXYZ123456789ABCDEFG" } } } } }, "PROVIDER_TIMEOUT": { "description": "504 - Request timed out. Funds have been refunded.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "PROVIDER_TIMEOUT", "message": "Request timed out. Funds have been refunded.", "docs_url": "https://dashboard.voidmob.com/developers/docs?doc=errors#provider_timeout", "request_id": "req_01HXYZ123456789ABCDEFG" } } } } }, "PRICE_MISMATCH": { "description": "409 - Price exceeds the supplied max_price_cents.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "PRICE_MISMATCH", "message": "Price exceeds the supplied max_price_cents.", "docs_url": "https://dashboard.voidmob.com/developers/docs?doc=errors#price_mismatch", "request_id": "req_01HXYZ123456789ABCDEFG" } } } } }, "POOL_NOT_FOUND": { "description": "404 - Pool not found.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "POOL_NOT_FOUND", "message": "Pool not found.", "docs_url": "https://dashboard.voidmob.com/developers/docs?doc=errors#pool_not_found", "request_id": "req_01HXYZ123456789ABCDEFG" } } } } }, "POOL_LAPSED": { "description": "409 - Pool validity has ended. Extend the pool to continue.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "POOL_LAPSED", "message": "Pool validity has ended. Extend the pool to continue.", "docs_url": "https://dashboard.voidmob.com/developers/docs?doc=errors#pool_lapsed", "request_id": "req_01HXYZ123456789ABCDEFG" } } } } }, "POOL_INSUFFICIENT_GB": { "description": "409 - Not enough GB left in the pool.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "POOL_INSUFFICIENT_GB", "message": "Not enough GB left in the pool.", "docs_url": "https://dashboard.voidmob.com/developers/docs?doc=errors#pool_insufficient_gb", "request_id": "req_01HXYZ123456789ABCDEFG" } } } } }, "POOL_SELF_EXTEND_DISABLED": { "description": "403 - Self-serve extension is not enabled for this pool.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "POOL_SELF_EXTEND_DISABLED", "message": "Self-serve extension is not enabled for this pool.", "docs_url": "https://dashboard.voidmob.com/developers/docs?doc=errors#pool_self_extend_disabled", "request_id": "req_01HXYZ123456789ABCDEFG" } } } } }, "POOL_MIN_EXTEND": { "description": "400 - Extension is below the pool's minimum GB.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "POOL_MIN_EXTEND", "message": "Extension is below the pool's minimum GB.", "docs_url": "https://dashboard.voidmob.com/developers/docs?doc=errors#pool_min_extend", "request_id": "req_01HXYZ123456789ABCDEFG" } } } } }, "OUT_OF_STOCK_AT_PRICE": { "description": "503 - No stock available at or below the supplied max_price_cents.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "OUT_OF_STOCK_AT_PRICE", "message": "No stock available at or below the supplied max_price_cents.", "docs_url": "https://dashboard.voidmob.com/developers/docs?doc=errors#out_of_stock_at_price", "request_id": "req_01HXYZ123456789ABCDEFG" } } } } }, "PRICE_OVER_CAP": { "description": "409 - Current price exceeds the supplied max_price_cents.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "PRICE_OVER_CAP", "message": "Current price exceeds the supplied max_price_cents.", "docs_url": "https://dashboard.voidmob.com/developers/docs?doc=errors#price_over_cap", "request_id": "req_01HXYZ123456789ABCDEFG" } } } } }, "BAD_SERVICE": { "description": "422 - Unknown or unsupported service.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "BAD_SERVICE", "message": "Unknown or unsupported service.", "docs_url": "https://dashboard.voidmob.com/developers/docs?doc=errors#bad_service", "request_id": "req_01HXYZ123456789ABCDEFG" } } } } }, "ALREADY_COMPLETED": { "description": "409 - Verification has already received a code and cannot be cancelled.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "ALREADY_COMPLETED", "message": "Verification has already received a code and cannot be cancelled.", "docs_url": "https://dashboard.voidmob.com/developers/docs?doc=errors#already_completed", "request_id": "req_01HXYZ123456789ABCDEFG" } } } } }, "CANCEL_WINDOW_NOT_OPEN": { "description": "409 - Cancellation is not yet available. Please retry after the cooldown.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "CANCEL_WINDOW_NOT_OPEN", "message": "Cancellation is not yet available. Please retry after the cooldown.", "docs_url": "https://dashboard.voidmob.com/developers/docs?doc=errors#cancel_window_not_open", "request_id": "req_01HXYZ123456789ABCDEFG" } } } } }, "NOT_SUPPORTED": { "description": "422 - This action is not supported.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "NOT_SUPPORTED", "message": "This action is not supported.", "docs_url": "https://dashboard.voidmob.com/developers/docs?doc=errors#not_supported", "request_id": "req_01HXYZ123456789ABCDEFG" } } } } }, "PROVIDER_ERROR": { "description": "502 - Service error. Please retry shortly.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "PROVIDER_ERROR", "message": "Service error. Please retry shortly.", "docs_url": "https://dashboard.voidmob.com/developers/docs?doc=errors#provider_error", "request_id": "req_01HXYZ123456789ABCDEFG" } } } } }, "LTR_NOT_AVAILABLE": { "description": "404 - Long-term rental is not available for this service or duration.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "LTR_NOT_AVAILABLE", "message": "Long-term rental is not available for this service or duration.", "docs_url": "https://dashboard.voidmob.com/developers/docs?doc=errors#ltr_not_available", "request_id": "req_01HXYZ123456789ABCDEFG" } } } } }, "RE_RENT_NOT_AVAILABLE": { "description": "410 - This number is no longer available for re-rent - it has been released. Start a fresh rental instead.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "RE_RENT_NOT_AVAILABLE", "message": "This number is no longer available for re-rent - it has been released. Start a fresh rental instead.", "docs_url": "https://dashboard.voidmob.com/developers/docs?doc=errors#re_rent_not_available", "request_id": "req_01HXYZ123456789ABCDEFG" } } } } }, "DEDICATED_NOT_AVAILABLE": { "description": "404 - Dedicated numbers are not available for this country.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "DEDICATED_NOT_AVAILABLE", "message": "Dedicated numbers are not available for this country.", "docs_url": "https://dashboard.voidmob.com/developers/docs?doc=errors#dedicated_not_available", "request_id": "req_01HXYZ123456789ABCDEFG" } } } } }, "PRODUCT_NOT_FOUND": { "description": "404 - Product not found.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "PRODUCT_NOT_FOUND", "message": "Product not found.", "docs_url": "https://dashboard.voidmob.com/developers/docs?doc=errors#product_not_found", "request_id": "req_01HXYZ123456789ABCDEFG" } } } } }, "ESIM_NOT_FOUND": { "description": "404 - eSIM not found.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "ESIM_NOT_FOUND", "message": "eSIM not found.", "docs_url": "https://dashboard.voidmob.com/developers/docs?doc=errors#esim_not_found", "request_id": "req_01HXYZ123456789ABCDEFG" } } } } }, "PARENT_ORDER_NOT_FOUND": { "description": "404 - Parent eSIM order not found.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "PARENT_ORDER_NOT_FOUND", "message": "Parent eSIM order not found.", "docs_url": "https://dashboard.voidmob.com/developers/docs?doc=errors#parent_order_not_found", "request_id": "req_01HXYZ123456789ABCDEFG" } } } } }, "PARENT_ORDER_NOT_ACTIVE": { "description": "409 - Parent eSIM is not in an active state for topups.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "PARENT_ORDER_NOT_ACTIVE", "message": "Parent eSIM is not in an active state for topups.", "docs_url": "https://dashboard.voidmob.com/developers/docs?doc=errors#parent_order_not_active", "request_id": "req_01HXYZ123456789ABCDEFG" } } } } }, "TOPUP_INCOMPATIBLE": { "description": "409 - This topup is not compatible with the parent eSIM.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "TOPUP_INCOMPATIBLE", "message": "This topup is not compatible with the parent eSIM.", "docs_url": "https://dashboard.voidmob.com/developers/docs?doc=errors#topup_incompatible", "request_id": "req_01HXYZ123456789ABCDEFG" } } } } }, "PRODUCT_UNAVAILABLE": { "description": "503 - Product is temporarily unavailable.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "PRODUCT_UNAVAILABLE", "message": "Product is temporarily unavailable.", "docs_url": "https://dashboard.voidmob.com/developers/docs?doc=errors#product_unavailable", "request_id": "req_01HXYZ123456789ABCDEFG" } } } } }, "USAGE_UNAVAILABLE": { "description": "503 - Usage data is not currently available. Please try again later.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "USAGE_UNAVAILABLE", "message": "Usage data is not currently available. Please try again later.", "docs_url": "https://dashboard.voidmob.com/developers/docs?doc=errors#usage_unavailable", "request_id": "req_01HXYZ123456789ABCDEFG" } } } } }, "ESIM_GONE": { "description": "410 - This eSIM has been cancelled or refunded.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "ESIM_GONE", "message": "This eSIM has been cancelled or refunded.", "docs_url": "https://dashboard.voidmob.com/developers/docs?doc=errors#esim_gone", "request_id": "req_01HXYZ123456789ABCDEFG" } } } } }, "ESIM_NOT_ACTIVE": { "description": "422 - eSIM is not in an active state.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "ESIM_NOT_ACTIVE", "message": "eSIM is not in an active state.", "docs_url": "https://dashboard.voidmob.com/developers/docs?doc=errors#esim_not_active", "request_id": "req_01HXYZ123456789ABCDEFG" } } } } } } } }