{ "openapi": "3.1.0", "info": { "title": "SMSLovers Public API", "version": "1.0.0", "description": "Build SMS verification into your product. Discounted API rates: save 25–50% depending on availability, with a cost and margin floor. The returned quote is authoritative. Funding is 1:1; resends have no customer fee. Documentation: https://smslovers.com/developers/" }, "servers": [ { "url": "https://smslovers.com/api/v1" } ], "paths": { "/webhooks": { "get": { "operationId": "get_webhooks", "summary": "List webhook endpoints and event types", "description": "Lists active/paused endpoints, never signing secrets. Up to five configured endpoints per account.", "tags": [ "webhooks" ], "security": [ { "ApiKey": [] } ], "x-required-scope": "webhooks:read", "parameters": [], "responses": { "200": { "description": "Success. All dates use Unix milliseconds; all EUR amounts use integer cents.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "webhooks": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } }, "events": { "type": "array", "items": { "type": "string", "enum": [ "balance.low", "sms.received", "sms.ended", "sms.review", "deposit.credited" ] } } }, "required": [ "webhooks", "events" ], "additionalProperties": false }, "requestId": { "type": "string", "description": "Request correlation ID." } }, "required": [ "data", "requestId" ], "additionalProperties": false } } } }, "400": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Honor Retry-After (seconds).", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "post_webhooks", "summary": "Create an event receiver", "description": "Also requires account:read for balance.low, sms:read for SMS events, account:read for deposit.credited. URLs are unique per account; retrying creation returns 409, so list endpoints before creating again. Rotate the secret if a creation response was lost. If already below the threshold, one initial low-balance event is queued.", "tags": [ "webhooks" ], "security": [ { "ApiKey": [] } ], "x-required-scope": "webhooks:write", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Endpoint name.", "minLength": 2, "maxLength": 60 }, "events": { "type": "array", "minItems": 1, "maxItems": 5, "uniqueItems": true, "items": { "type": "string", "enum": [ "balance.low", "sms.received", "sms.ended", "sms.review", "deposit.credited" ] } }, "lowBalanceCents": { "type": "integer", "description": "Low-balance threshold in EUR cents. Defaults to 500 (€5).", "minimum": 1, "maximum": 100000 }, "enabled": { "type": "boolean", "default": true }, "url": { "type": "string", "description": "Public HTTPS domain on port 443. No IP literals, credentials, fragments or private DNS destinations.", "format": "uri", "maxLength": 2048 } }, "required": [ "name", "url", "events" ], "additionalProperties": false }, "example": { "name": "My product", "url": "https://api.example.com/webhooks/smslovers", "events": [ "balance.low", "sms.received" ], "lowBalanceCents": 500, "enabled": true } } } }, "responses": { "201": { "description": "Success. All dates use Unix milliseconds; all EUR amounts use integer cents.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "webhook": { "$ref": "#/components/schemas/Webhook" }, "secret": { "type": "string", "description": "Signing secret, shown once. Store privately." } }, "required": [ "webhook", "secret" ], "additionalProperties": false }, "requestId": { "type": "string", "description": "Request correlation ID." } }, "required": [ "data", "requestId" ], "additionalProperties": false } } } }, "400": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Honor Retry-After (seconds).", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhooks/{id}": { "post": { "operationId": "post_webhooks_id", "summary": "Update or pause a webhook", "description": "Partial update. Requires the read scopes for every subscribed event. The URL is immutable: create a new endpoint to change it. Pausing stops queued attempts; an in-flight request may complete.", "tags": [ "webhooks" ], "security": [ { "ApiKey": [] } ], "x-required-scope": "webhooks:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "SMSLovers UUID.", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Endpoint name.", "minLength": 2, "maxLength": 60 }, "events": { "type": "array", "minItems": 1, "maxItems": 5, "uniqueItems": true, "items": { "type": "string", "enum": [ "balance.low", "sms.received", "sms.ended", "sms.review", "deposit.credited" ] } }, "lowBalanceCents": { "type": "integer", "description": "Low-balance threshold in EUR cents. Defaults to 500 (€5).", "minimum": 1, "maximum": 100000 }, "enabled": { "type": "boolean", "default": true } }, "required": [], "additionalProperties": false }, "example": { "enabled": false } } } }, "responses": { "200": { "description": "Success. All dates use Unix milliseconds; all EUR amounts use integer cents.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "webhook": { "$ref": "#/components/schemas/Webhook" } }, "required": [ "webhook" ], "additionalProperties": false }, "requestId": { "type": "string", "description": "Request correlation ID." } }, "required": [ "data", "requestId" ], "additionalProperties": false } } } }, "400": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Honor Retry-After (seconds).", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhooks/{id}/deliveries": { "get": { "operationId": "get_webhooks_id_deliveries", "summary": "Inspect webhook deliveries", "description": "50 entries per page, newest first. Logs contain metadata, never signing secrets, SMS text or raw response bodies. Retained for 30 days.", "tags": [ "webhooks" ], "security": [ { "ApiKey": [] } ], "x-required-scope": "webhooks:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "SMSLovers UUID.", "format": "uuid" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 999999, "default": 0 }, "description": "Zero-based page." } ], "responses": { "200": { "description": "Success. All dates use Unix milliseconds; all EUR amounts use integer cents.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } }, "page": { "type": "integer", "description": "Zero-based page." }, "limit": { "type": "integer", "const": 50 } }, "required": [ "items", "page", "limit" ], "additionalProperties": false }, "requestId": { "type": "string", "description": "Request correlation ID." } }, "required": [ "data", "requestId" ], "additionalProperties": false } } } }, "400": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Honor Retry-After (seconds).", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhooks/{id}/rotate-secret": { "post": { "operationId": "post_webhooks_id_rotate_secret", "summary": "Rotate the signing secret", "description": "Also requires the subscribed event read scopes. Effective immediately for new attempts. An already submitted delivery may use the old secret. Update your verifier and allow a short transition window where appropriate.", "tags": [ "webhooks" ], "security": [ { "ApiKey": [] } ], "x-required-scope": "webhooks:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "SMSLovers UUID.", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "example": {} } } }, "responses": { "200": { "description": "Success. All dates use Unix milliseconds; all EUR amounts use integer cents.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "secret": { "type": "string", "description": "New secret, shown once." } }, "required": [ "secret" ], "additionalProperties": false }, "requestId": { "type": "string", "description": "Request correlation ID." } }, "required": [ "data", "requestId" ], "additionalProperties": false } } } }, "400": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Honor Retry-After (seconds).", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhooks/{id}/test": { "post": { "operationId": "post_webhooks_id_test", "summary": "Queue a signed test event", "description": "Sends webhook.test with a harmless message to this enabled endpoint. HTTP 202 means queued, not delivered. Five tests per hour per account and 30 per minute service-wide.", "tags": [ "webhooks" ], "security": [ { "ApiKey": [] } ], "x-required-scope": "webhooks:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "SMSLovers UUID.", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "example": {} } } }, "responses": { "202": { "description": "Success. All dates use Unix milliseconds; all EUR amounts use integer cents.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "queued": { "type": "boolean" }, "eventId": { "type": "string", "description": "Test event ID." } }, "required": [ "queued", "eventId" ], "additionalProperties": false }, "requestId": { "type": "string", "description": "Request correlation ID." } }, "required": [ "data", "requestId" ], "additionalProperties": false } } } }, "400": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Honor Retry-After (seconds).", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhooks/{id}/retry": { "post": { "operationId": "post_webhooks_id_retry", "summary": "Retry a failed delivery", "description": "Also requires the subscribed event read scopes. Only failed deliveries on an enabled endpoint can be retried. Reuses the same event ID, delivery ID and payload; the signature timestamp is fresh. HTTP 202.", "tags": [ "webhooks" ], "security": [ { "ApiKey": [] } ], "x-required-scope": "webhooks:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "SMSLovers UUID.", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "deliveryId": { "type": "string", "description": "ID from delivery logs." } }, "required": [ "deliveryId" ], "additionalProperties": false }, "example": { "deliveryId": "whd_0123456789abcdef0123456789abcdef" } } } }, "responses": { "202": { "description": "Success. All dates use Unix milliseconds; all EUR amounts use integer cents.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "queued": { "type": "boolean" } }, "required": [ "queued" ], "additionalProperties": false }, "requestId": { "type": "string", "description": "Request correlation ID." } }, "required": [ "data", "requestId" ], "additionalProperties": false } } } }, "400": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Honor Retry-After (seconds).", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhooks/{id}/remove": { "post": { "operationId": "post_webhooks_id_remove", "summary": "Remove a receiver", "description": "Stops queued deliveries and hides the endpoint. An in-flight request may complete. Registering the same URL later generates a new secret.", "tags": [ "webhooks" ], "security": [ { "ApiKey": [] } ], "x-required-scope": "webhooks:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "SMSLovers UUID.", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "example": {} } } }, "responses": { "200": { "description": "Success. All dates use Unix milliseconds; all EUR amounts use integer cents.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ], "additionalProperties": false }, "requestId": { "type": "string", "description": "Request correlation ID." } }, "required": [ "data", "requestId" ], "additionalProperties": false } } } }, "400": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Honor Retry-After (seconds).", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/account": { "get": { "operationId": "get_account", "summary": "Account and balance", "description": "One shared EUR balance across the website, Discord and API. Key caps reset at 00:00 UTC; spentTodayCents counts gross SMS reservations, including subsequently refunded orders.", "tags": [ "account" ], "security": [ { "ApiKey": [] } ], "x-required-scope": "account:read", "parameters": [], "responses": { "200": { "description": "Success. All dates use Unix milliseconds; all EUR amounts use integer cents.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Account" }, "requestId": { "type": "string", "description": "Request correlation ID." } }, "required": [ "data", "requestId" ], "additionalProperties": false } } } }, "400": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Honor Retry-After (seconds).", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/ledger": { "get": { "operationId": "get_ledger", "summary": "Balance ledger", "description": "Newest first. Includes reservations, refunds, confirmed deposits and bonuses.", "tags": [ "ledger" ], "security": [ { "ApiKey": [] } ], "x-required-scope": "account:read", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 999999, "default": 0 }, "description": "Zero-based page." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Results per page." } ], "responses": { "200": { "description": "Success. All dates use Unix milliseconds; all EUR amounts use integer cents.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Ledger" } }, "page": { "type": "integer", "description": "Current page." }, "limit": { "type": "integer", "description": "Page size." }, "nextPage": { "type": [ "integer", "null" ], "description": "Next page, or null at the end." } }, "required": [ "items", "page", "limit", "nextPage" ], "additionalProperties": false }, "requestId": { "type": "string", "description": "Request correlation ID." } }, "required": [ "data", "requestId" ], "additionalProperties": false } } } }, "400": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Honor Retry-After (seconds).", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/countries": { "get": { "operationId": "get_countries", "summary": "Country keys", "description": "Use key exactly as returned, such as US or Germany. Country keys are not universally ISO codes.", "tags": [ "countries" ], "security": [ { "ApiKey": [] } ], "x-required-scope": "sms:read", "parameters": [], "responses": { "200": { "description": "Success. All dates use Unix milliseconds; all EUR amounts use integer cents.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Country" } }, "requestId": { "type": "string", "description": "Request correlation ID." } }, "required": [ "data", "requestId" ], "additionalProperties": false } } } }, "400": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Honor Retry-After (seconds).", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/services": { "get": { "operationId": "get_services", "summary": "Search services", "description": "Alphabetical. Country lists describe coverage, not guaranteed live stock.", "tags": [ "services" ], "security": [ { "ApiKey": [] } ], "x-required-scope": "sms:read", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 999999, "default": 0 }, "description": "Zero-based page." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Results per page." }, { "name": "q", "in": "query", "schema": { "type": "string", "description": "Case-insensitive name search.", "maxLength": 100 } }, { "name": "country", "in": "query", "schema": { "type": "string", "description": "Exact country key, e.g. US." } } ], "responses": { "200": { "description": "Success. All dates use Unix milliseconds; all EUR amounts use integer cents.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Service" } }, "page": { "type": "integer", "description": "Current page." }, "limit": { "type": "integer", "description": "Page size." }, "nextPage": { "type": [ "integer", "null" ], "description": "Next page, or null at the end." }, "total": { "type": "integer", "description": "Number of matching services." } }, "required": [ "items", "page", "limit", "nextPage" ], "additionalProperties": false }, "requestId": { "type": "string", "description": "Request correlation ID." } }, "required": [ "data", "requestId" ], "additionalProperties": false } } } }, "400": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Honor Retry-After (seconds).", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/services/{id}": { "get": { "operationId": "get_services_id", "summary": "Service and supported countries", "description": "", "tags": [ "services" ], "security": [ { "ApiKey": [] } ], "x-required-scope": "sms:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Success. All dates use Unix milliseconds; all EUR amounts use integer cents.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer", "description": "Service ID." }, "name": { "type": "string", "description": "Service name." }, "countries": { "type": "array", "items": { "$ref": "#/components/schemas/Country" } } }, "required": [ "id", "name", "countries" ], "additionalProperties": false }, "requestId": { "type": "string", "description": "Request correlation ID." } }, "required": [ "data", "requestId" ], "additionalProperties": false } } } }, "400": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Honor Retry-After (seconds).", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/quotes": { "post": { "operationId": "post_quotes", "summary": "Get a discounted live quote", "description": "Quotes expire after 60 seconds and belong to this account, API key and API billing channel. Select an options[].id. Standard and Resend choices are returned only when available. available:false means no eligible discounted stock; try another service/country later. Quoting never spends balance.", "tags": [ "quotes" ], "security": [ { "ApiKey": [] } ], "x-required-scope": "sms:write", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "serviceId": { "type": "integer", "description": "ID from /services.", "minimum": 1 }, "country": { "type": "string", "description": "Country key from /countries." } }, "required": [ "serviceId", "country" ], "additionalProperties": false }, "example": { "serviceId": 1, "country": "US" } } } }, "responses": { "200": { "description": "Success. All dates use Unix milliseconds; all EUR amounts use integer cents.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Quote" }, "requestId": { "type": "string", "description": "Request correlation ID." } }, "required": [ "data", "requestId" ], "additionalProperties": false } } } }, "400": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Honor Retry-After (seconds).", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/orders": { "post": { "operationId": "post_orders", "summary": "Buy an SMS number", "description": "Requires Idempotency-Key. Reserves priceCents from your balance once. Retry the exact quoteId with the same key, including after a timeout or quote expiry. Changing the quoteId with the same key returns 409. Five active purchases per account across all channels. reconciling means do not buy a replacement blindly; contact support.", "tags": [ "orders" ], "security": [ { "ApiKey": [] } ], "x-required-scope": "sms:write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "description": "16–80 letters, numbers or hyphens. Generate once and persist for this operation.", "pattern": "^[-a-zA-Z0-9]{16,80}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "quoteId": { "type": "string", "description": "SMSLovers UUID.", "format": "uuid" } }, "required": [ "quoteId" ], "additionalProperties": false }, "example": { "quoteId": "11111111-1111-4111-8111-111111111111" } } } }, "responses": { "201": { "description": "Success. All dates use Unix milliseconds; all EUR amounts use integer cents.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Order" }, "requestId": { "type": "string", "description": "Request correlation ID." } }, "required": [ "data", "requestId" ], "additionalProperties": false } } } }, "400": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Honor Retry-After (seconds).", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "get_orders", "summary": "List your SMS orders", "description": "Includes your website and Discord SMS orders too. status filters the stored lifecycle (not the derived resending/resend_review presentation).", "tags": [ "orders" ], "security": [ { "ApiKey": [] } ], "x-required-scope": "sms:read", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 999999, "default": 0 }, "description": "Zero-based page." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Results per page." }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "purchasing", "waiting", "received", "cancel_requested", "cancelled", "refunded", "unavailable", "reconciling" ] } } ], "responses": { "200": { "description": "Success. All dates use Unix milliseconds; all EUR amounts use integer cents.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } }, "page": { "type": "integer", "description": "Current page." }, "limit": { "type": "integer", "description": "Page size." }, "nextPage": { "type": [ "integer", "null" ], "description": "Next page, or null at the end." } }, "required": [ "items", "page", "limit", "nextPage" ], "additionalProperties": false }, "requestId": { "type": "string", "description": "Request correlation ID." } }, "required": [ "data", "requestId" ], "additionalProperties": false } } } }, "400": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Honor Retry-After (seconds).", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/orders/{id}": { "get": { "operationId": "get_orders_id", "summary": "Get the number, code and history", "description": "Poll every 5–10 seconds. This reads the current state; automatic background checks receive new SMS messages. Stop polling terminal orders. GET never places a new order or requests a resend.", "tags": [ "orders" ], "security": [ { "ApiKey": [] } ], "x-required-scope": "sms:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "SMSLovers UUID.", "format": "uuid" } } ], "responses": { "200": { "description": "Success. All dates use Unix milliseconds; all EUR amounts use integer cents.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Order" }, "requestId": { "type": "string", "description": "Request correlation ID." } }, "required": [ "data", "requestId" ], "additionalProperties": false }, "example": { "data": { "id": "22222222-2222-4222-8222-222222222222", "serviceId": 1, "service": "Google", "country": "US", "priceCents": 30, "retailPriceCents": 50, "discountPercent": 40, "billingSource": "api", "status": "received", "phone": "+15551234567", "code": "012345", "message": "Your code is 012345." }, "requestId": "example-request" } } } }, "400": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Honor Retry-After (seconds).", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/orders/{id}/cancel": { "post": { "operationId": "post_orders_id_cancel", "summary": "Cancel an unused number", "description": "Available one minute after purchase while waiting. A confirmed cancellation or unused-number refund returns exactly the charged amount. Cancellation is naturally idempotent; a used or uncertain order returns 409.", "tags": [ "orders" ], "security": [ { "ApiKey": [] } ], "x-required-scope": "sms:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "SMSLovers UUID.", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "example": {} } } }, "responses": { "200": { "description": "Success. All dates use Unix milliseconds; all EUR amounts use integer cents.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Order" }, "requestId": { "type": "string", "description": "Request correlation ID." } }, "required": [ "data", "requestId" ], "additionalProperties": false } } } }, "400": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Honor Retry-After (seconds).", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/orders/{id}/resend-check": { "post": { "operationId": "post_orders_id_resend_check", "summary": "Check resend availability", "description": "After the first code. A live check may say unavailable even when a Resend option was selected earlier; availability and expiry can change. Does not request a new SMS.", "tags": [ "orders" ], "security": [ { "ApiKey": [] } ], "x-required-scope": "sms:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "SMSLovers UUID.", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "example": {} } } }, "responses": { "200": { "description": "Success. All dates use Unix milliseconds; all EUR amounts use integer cents.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Order" }, "requestId": { "type": "string", "description": "Request correlation ID." } }, "required": [ "data", "requestId" ], "additionalProperties": false } } } }, "400": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Honor Retry-After (seconds).", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/orders/{id}/resend": { "post": { "operationId": "post_orders_id_resend", "summary": "Request another SMS", "description": "Requires Idempotency-Key. Free to the customer; no per-resend balance debit. Request the next code on the service you are verifying, then poll the same order ID. Previous codes remain in messages. Up to 25 resend attempts per number; actual eligibility and expiry vary. For a definitive 409, check availability before choosing a new idempotency key. For a timeout/5xx, retain the original key.", "tags": [ "orders" ], "security": [ { "ApiKey": [] } ], "x-required-scope": "sms:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "SMSLovers UUID.", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "description": "16–80 letters, numbers or hyphens. Generate once and persist for this operation.", "pattern": "^[-a-zA-Z0-9]{16,80}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "example": {} } } }, "responses": { "200": { "description": "Success. All dates use Unix milliseconds; all EUR amounts use integer cents.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Order" }, "requestId": { "type": "string", "description": "Request correlation ID." } }, "required": [ "data", "requestId" ], "additionalProperties": false } } } }, "400": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Honor Retry-After (seconds).", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code and error.message.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "ApiKey": { "type": "http", "scheme": "bearer", "description": "A scoped key created at /dashboard/?tab=api. Keep it on your server." } }, "schemas": { "Webhook": { "type": "object", "properties": { "id": { "type": "string", "description": "SMSLovers UUID.", "format": "uuid" }, "name": { "type": "string", "description": "Endpoint label." }, "url": { "type": "string", "description": "Public HTTPS receiver URL." }, "events": { "type": "array", "items": { "type": "string", "enum": [ "balance.low", "sms.received", "sms.ended", "sms.review", "deposit.credited" ] } }, "lowBalanceCents": { "type": "integer", "description": "Alert threshold in EUR cents." }, "enabled": { "type": "boolean" }, "createdAt": { "type": "integer", "description": "Unix milliseconds." }, "updatedAt": { "type": "integer", "description": "Unix milliseconds." } }, "required": [ "id", "name", "url", "events", "lowBalanceCents", "enabled", "createdAt", "updatedAt" ], "additionalProperties": false }, "WebhookDelivery": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable delivery ID." }, "type": { "type": "string", "description": "Event type." }, "status": { "type": "string", "enum": [ "queued", "delivered", "failed" ] }, "attempts": { "type": "integer", "description": "Attempts made." }, "responseStatus": { "type": [ "integer", "null" ], "description": "Last HTTP status, or null for network failure." }, "lastError": { "type": [ "string", "null" ], "description": "Generic failure information." }, "createdAt": { "type": "integer", "description": "Unix milliseconds." }, "deliveredAt": { "type": [ "integer", "null" ], "description": "Unix milliseconds." }, "nextAttemptAt": { "type": "integer", "description": "Next scheduled attempt, Unix milliseconds." } }, "required": [ "id", "type", "status", "attempts", "responseStatus", "lastError", "createdAt", "deliveredAt", "nextAttemptAt" ], "additionalProperties": false }, "WebhookEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable event ID; use for idempotency." }, "type": { "type": "string", "enum": [ "balance.low", "sms.received", "sms.ended", "sms.review", "deposit.credited", "webhook.test" ] }, "accountId": { "type": "string", "description": "SMSLovers UUID.", "format": "uuid" }, "createdAt": { "type": "integer", "description": "Unix milliseconds." }, "data": { "type": "object", "description": "balance.low: currency, balanceCents, previousBalanceCents, thresholdCents. sms.*: order {id,serviceId,service,country,priceCents,phone,status,expiresAt,resendId?}; sms.received also includes code and message. deposit.credited: deposit {id,method,asset,creditCents,creditedAt,txid?,amount?,amountCents?}, balanceCents. webhook.test: message." } }, "required": [ "id", "type", "accountId", "createdAt", "data" ], "additionalProperties": false }, "Country": { "type": "object", "properties": { "key": { "type": "string", "description": "Exact country key." }, "name": { "type": "string", "description": "Country name." }, "dialCode": { "type": "integer", "description": "Calling prefix; e.g. 1 or 49." } }, "required": [ "key", "name", "dialCode" ], "additionalProperties": false }, "Service": { "type": "object", "properties": { "id": { "type": "integer", "description": "Service ID." }, "name": { "type": "string", "description": "Service name." }, "countries": { "type": "array", "items": { "type": "string", "description": "Country key." } } }, "required": [ "id", "name", "countries" ], "additionalProperties": false }, "Key": { "type": "object", "properties": { "id": { "type": "string", "description": "SMSLovers UUID.", "format": "uuid" }, "name": { "type": "string", "description": "Key label." }, "prefix": { "type": "string", "description": "Non-secret prefix; full key is never returned." }, "scopes": { "type": "array", "items": { "type": "string", "description": "Granted permission." } }, "dailyLimitCents": { "type": "integer", "description": "Daily gross reservation cap." }, "spentTodayCents": { "type": "integer", "description": "Gross reservations since 00:00 UTC, including refunds." }, "createdAt": { "type": "integer", "description": "Unix milliseconds." }, "expiresAt": { "type": "integer", "description": "Unix milliseconds." }, "lastUsedAt": { "type": [ "integer", "null" ], "description": "Unix milliseconds or null." }, "revokedAt": { "type": [ "integer", "null" ], "description": "Unix milliseconds or null." } }, "required": [ "id", "name", "prefix", "scopes", "dailyLimitCents", "spentTodayCents", "createdAt", "expiresAt", "lastUsedAt", "revokedAt" ], "additionalProperties": false }, "Account": { "type": "object", "properties": { "id": { "type": "string", "description": "SMSLovers UUID.", "format": "uuid" }, "username": { "type": "string", "description": "Account username." }, "currency": { "type": "string", "const": "EUR" }, "balanceCents": { "type": "integer", "description": "Available balance." }, "key": { "$ref": "#/components/schemas/Key" } }, "required": [ "id", "username", "currency", "balanceCents", "key" ], "additionalProperties": false }, "Ledger": { "type": "object", "properties": { "id": { "type": "integer", "description": "Ledger entry ID." }, "deltaCents": { "type": "integer", "description": "Signed balance change." }, "balanceAfterCents": { "type": "integer", "description": "Resulting balance." }, "description": { "type": "string", "description": "Entry description." }, "createdAt": { "type": "integer", "description": "Unix milliseconds." } }, "required": [ "id", "deltaCents", "balanceAfterCents", "description", "createdAt" ], "additionalProperties": false }, "QuoteOption": { "type": "object", "properties": { "id": { "type": "string", "description": "SMSLovers UUID.", "format": "uuid" }, "priceCents": { "type": "integer", "description": "Exact API charge in EUR cents." }, "retailPriceCents": { "type": "integer", "description": "Normal price for this choice." }, "discountPercent": { "type": "integer", "description": "Whole percent saving, rounded down; 25–50." }, "resendPreferred": { "type": "boolean" }, "label": { "type": "string", "enum": [ "Standard", "Resend" ] }, "expiresAt": { "type": "integer", "description": "Unix milliseconds." } }, "required": [ "id", "priceCents", "retailPriceCents", "discountPercent", "resendPreferred", "label", "expiresAt" ], "additionalProperties": false }, "Quote": { "type": "object", "required": [ "available", "service", "country" ], "properties": { "available": { "type": "boolean" }, "service": { "type": "string", "description": "Service name." }, "serviceId": { "type": "integer", "description": "Service ID." }, "country": { "type": "string", "description": "Country key." }, "id": { "type": "string", "description": "SMSLovers UUID.", "format": "uuid" }, "priceCents": { "type": "integer", "description": "First option price in EUR cents." }, "retailPriceCents": { "type": "integer", "description": "Normal price." }, "discountPercent": { "type": "integer", "description": "Saving." }, "resendPreferred": { "type": "boolean" }, "label": { "type": "string", "description": "First option label." }, "expiresAt": { "type": "integer", "description": "Unix milliseconds." }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/QuoteOption" } }, "resendPoolAvailable": { "type": "boolean" }, "notice": { "type": "string", "description": "Unavailable rate/stock explanation." }, "resendSelectionNotice": { "type": "string", "description": "Resend availability information." } } }, "Order": { "type": "object", "required": [ "id", "service", "country", "priceCents", "status" ], "properties": { "id": { "type": "string", "description": "SMSLovers UUID.", "format": "uuid" }, "serviceId": { "type": "integer", "description": "Service ID." }, "service": { "type": "string", "description": "Service name." }, "country": { "type": "string", "description": "Country key." }, "priceCents": { "type": "integer", "description": "Exact amount charged; refunds use this amount." }, "billingSource": { "type": "string", "enum": [ "api", "retail" ] }, "retailPriceCents": { "type": "integer", "description": "Normal price, present for API orders." }, "discountPercent": { "type": "integer", "description": "Applied API saving." }, "phone": { "type": [ "string", "null" ], "description": "Full international number." }, "callingCode": { "type": [ "string", "null" ], "description": "Country prefix, including +." }, "nationalNumber": { "type": [ "string", "null" ], "description": "Number without calling prefix." }, "status": { "type": "string", "enum": [ "purchasing", "waiting", "received", "cancel_requested", "cancelled", "refunded", "unavailable", "reconciling", "resending", "resend_review" ] }, "code": { "type": [ "string", "null" ], "description": "Latest code. Preserve leading zeroes." }, "message": { "type": [ "string", "null" ], "description": "Full latest SMS text." }, "createdAt": { "type": "integer", "description": "Unix milliseconds." }, "expiresAt": { "type": [ "integer", "null" ], "description": "Unix milliseconds or null." }, "notice": { "type": [ "string", "null" ], "description": "Review information." }, "resendRequestable": { "type": "boolean" }, "resendAvailable": { "type": "boolean" }, "resendNotice": { "type": [ "string", "null" ], "description": "Resend information." }, "resendPreferred": { "type": "boolean" }, "resendCheckable": { "type": "boolean" }, "activeResend": { "type": [ "object", "null" ], "description": "id, status, createdAt and expiresAt of a pending resend." }, "messages": { "type": "array", "items": { "type": "object", "description": "SMS history entries: optional id, code, message, receivedAt (Unix milliseconds) and resend. Codes are strings." } } } }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable error category." }, "message": { "type": "string", "description": "Human-readable detail." }, "retryAfterSeconds": { "type": "integer", "description": "Only present for rate limits." } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string", "description": "Provide this to support." } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }