{ "openapi": "3.1.0", "info": { "title": "SIMUB API", "version": "1.3.0", "description": "SIMUB reseller API for SMS and call activations, phone rentals and temporary mail activations. The modern /api/v1 contract uses an Authorization: ApiKey header; the legacy SMS-Activate compatible endpoints remain available." }, "servers": [ { "url": "https://api.simub.com", "description": "Public SMS activation API" }, { "url": "https://simub.com", "description": "SIMUB web API" } ], "components": { "securitySchemes": { "apiKeyQuery": { "type": "apiKey", "name": "api_key", "in": "query" }, "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "Format: ApiKey {your_token}" } }, "parameters": { "apiKey": { "name": "api_key", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Client API key." }, "action": { "name": "action", "in": "query", "required": true, "schema": { "type": "string", "example": "getBalance", "default": "getBalance" }, "description": "SMSHub-compatible action name. The generated example uses getBalance; replace it with the action you need." }, "rentalService": { "name": "service", "in": "query", "required": true, "schema": { "type": "string", "example": "tg" }, "description": "SIMUB service code, for example tg for Telegram." }, "rentalCountry": { "name": "country", "in": "query", "required": true, "schema": { "type": "string", "example": "0" }, "description": "Country code returned by getOffers. ISO code and country ID are also accepted." }, "rentalDuration": { "name": "duration", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1, "maximum": 8760, "example": 24 }, "description": "Rental duration in hours. Use a duration returned by getOffers." }, "rentalId": { "name": "id", "in": "query", "required": true, "schema": { "type": "integer", "example": 12540 }, "description": "SIMUB rental request ID." } }, "schemas": { "MailPriceRests": { "type": "object", "properties": { "status": { "type": "integer", "example": 1 }, "data": { "type": "object", "example": { "tg": { "gmail.com": { "price": 0.12, "count": 42 } } } } } }, "MailActivation": { "type": "object", "properties": { "status": { "type": "integer", "example": 1 }, "mail": { "type": "string", "example": "user@gmail.com" }, "mailId": { "type": "integer", "example": 123456 } } }, "ErrorJson": { "type": "object", "properties": { "status": { "type": "integer", "example": 0 }, "error": { "type": "string", "example": "Insufficient balance" } } }, "V1Error": { "type": "object", "required": [ "title", "details", "errors" ], "properties": { "title": { "type": "string", "example": "UNPROCESSABLE_ENTITY" }, "details": { "type": "string", "example": "One or more parameters are invalid." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } } }, "V1Otp": { "type": "object", "properties": { "id": { "type": "string", "example": "123456" }, "smsCode": { "type": [ "string", "null" ], "example": "742913" }, "smsText": { "type": [ "string", "null" ], "example": "Your verification code is 742913" }, "receivedAt": { "type": [ "string", "null" ], "format": "date-time" }, "type": { "type": "string", "enum": [ "sms", "call" ] }, "phoneFrom": { "type": "string", "example": "Telegram" }, "service": { "type": "string", "example": "tg" } } }, "V1Activation": { "type": "object", "required": [ "id", "status", "phone", "service", "country", "price", "createdAt", "expiredAt", "verificationType", "subtype", "otpList" ], "properties": { "id": { "type": "integer", "example": 123456789 }, "status": { "type": "integer", "enum": [ 1, 2, 3, 6, 8, 10 ], "example": 1 }, "phone": { "type": "string", "example": "447700900123" }, "service": { "type": "string", "minLength": 2, "maxLength": 4, "example": "tg" }, "country": { "type": "integer", "minimum": 0, "maximum": 999, "example": 16 }, "countryPhoneCode": { "type": [ "integer", "null" ], "example": 44 }, "operator": { "type": "string", "example": "vodafone" }, "price": { "type": "number", "format": "float", "example": 0.48 }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiredAt": { "type": [ "string", "null" ], "format": "date-time" }, "verificationType": { "type": "string", "enum": [ "sms", "call" ] }, "subtype": { "type": "integer", "enum": [ 1, 2 ], "description": "1 = activation, 2 = rental" }, "otpList": { "type": "array", "items": { "$ref": "#/components/schemas/V1Otp" } } } }, "V1BuyActivation": { "type": "object", "required": [ "service", "country", "amount" ], "properties": { "service": { "type": "string", "minLength": 2, "maxLength": 4, "example": "tg" }, "country": { "type": "integer", "minimum": 0, "maximum": 999, "example": 16 }, "amount": { "type": "integer", "minimum": 1, "maximum": 10, "example": 1 }, "operator": { "type": "string", "default": "any", "example": "vodafone" }, "maxPrice": { "type": "number", "format": "float", "example": 0.55 }, "fixedPrice": { "type": "boolean", "default": false, "description": "Purchase strictly at maxPrice. maxPrice is required when this flag is true." }, "duration": { "type": "integer", "minimum": 1, "maximum": 8760, "description": "Rental duration in hours." }, "verificationType": { "type": "string", "enum": [ "sms", "call" ], "default": "sms" }, "resellerUserId": { "type": "string", "maxLength": 36, "description": "Optional downstream customer identifier. SIMUB namespaces it per authenticated API client before forwarding it upstream." } } }, "V1EmailActivation": { "type": "object", "required": [ "id", "site", "email", "status", "value", "cost", "currency", "date", "message", "domain" ], "properties": { "id": { "type": "integer", "example": 78432, "description": "SIMUB email activation ID." }, "site": { "type": "string", "example": "telegram.com" }, "email": { "type": "string", "format": "email", "example": "simub78432@gmail.com" }, "status": { "type": "string", "enum": [ "WAIT", "CANCEL", "SUCCESS" ] }, "value": { "type": [ "string", "null" ], "example": "742913" }, "cost": { "type": "number", "format": "float", "example": 0.31, "description": "SIMUB customer price." }, "currency": { "type": "integer", "example": 840, "description": "ISO 4217 numeric currency code." }, "date": { "type": [ "string", "null" ], "format": "date-time" }, "message": { "type": [ "string", "null" ], "example": "Your verification code is 742913." }, "domain": { "type": "string", "example": "gmail.com" } } }, "V1EmailDomain": { "type": "object", "required": [ "name", "cost", "count" ], "properties": { "name": { "type": "string", "example": "gmail.com" }, "cost": { "type": "number", "format": "float", "example": 0.31, "description": "SIMUB customer price." }, "count": { "type": "integer", "minimum": 0, "example": 42 } } }, "V1BuyEmail": { "type": "object", "required": [ "site", "domain" ], "properties": { "site": { "type": "string", "maxLength": 2048, "example": "telegram.com", "description": "Website hostname or URL for which the email is needed." }, "domain": { "type": "string", "maxLength": 253, "example": "gmail.com" } } }, "V1BuyEmailBatch": { "allOf": [ { "$ref": "#/components/schemas/V1BuyEmail" }, { "type": "object", "required": [ "count" ], "properties": { "count": { "type": "integer", "minimum": 1, "maximum": 10, "example": 3 }, "service": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 4, "example": "tg", "description": "Optional HeroSMS service code." } } } ] }, "V1Pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "size": { "type": "integer" }, "sort": { "type": "object" }, "total": { "type": "integer" }, "hasMore": { "type": "boolean" }, "search": { "type": [ "string", "null" ] }, "filters": { "type": "object" } } } } }, "security": [ { "apiKeyQuery": [] } ], "paths": { "/stubs/handler_api.php": { "get": { "tags": [ "SMS activations" ], "summary": "SMSHub-compatible action endpoint", "description": "Use this endpoint with the action query parameter. It supports getBalance, getNumber, getNumberV2, getStatus, setStatus, getPrices, getPricesV2, getPricesV3, getCountries, getServices, getActiveActivations and getNumbersStats.", "parameters": [ { "$ref": "#/components/parameters/action" }, { "name": "service", "in": "query", "schema": { "type": "string", "example": "tg" }, "description": "Service code, for example tg for Telegram." }, { "name": "country", "in": "query", "schema": { "type": "string", "example": "0" }, "description": "Country code." }, { "name": "id", "in": "query", "schema": { "type": "string", "example": "123456" }, "description": "Activation ID for getStatus or setStatus." }, { "name": "status", "in": "query", "schema": { "type": "integer", "enum": [ 1, 3, 6, 8 ] }, "description": "Status for setStatus: 1 ready, 3 retry, 6 complete, 8 cancel." }, { "name": "maxPrice", "in": "query", "schema": { "type": "number", "example": 0.5 }, "description": "Maximum accepted client price." } ], "responses": { "200": { "description": "Expected SMSHub-compatible plain text or JSON response.", "content": { "text/plain": { "examples": { "balance": { "summary": "getBalance", "value": "ACCESS_BALANCE:12.34" }, "number": { "summary": "getNumber", "value": "ACCESS_NUMBER:123456:447700900123" }, "wait": { "summary": "getStatus waiting", "value": "STATUS_WAIT_CODE" }, "code": { "summary": "getStatus success", "value": "STATUS_OK:12345" }, "cancel": { "summary": "setStatus cancel", "value": "ACCESS_CANCEL" }, "error": { "summary": "Error", "value": "BAD_KEY" } } }, "application/json": { "examples": { "numberV2": { "summary": "getNumberV2", "value": { "activationId": "123456", "phoneNumber": "447700900123", "activationCost": 0.12, "countryCode": "0", "canGetAnotherSms": true } }, "prices": { "summary": "getPrices", "value": { "0": { "tg": { "cost": 0.12, "count": 42 } } } } } } } } } } }, "/api/mail/getActivation": { "get": { "tags": [ "Mail activations" ], "summary": "Buy temporary mail activation", "parameters": [ { "name": "service", "in": "query", "required": true, "schema": { "type": "string", "example": "tg" } }, { "name": "domain", "in": "query", "required": true, "schema": { "type": "string", "example": "gmail.com" } }, { "name": "alias", "in": "query", "schema": { "type": "integer", "enum": [ 0, 1 ] } } ], "responses": { "200": { "description": "Mail activation result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MailActivation" }, "examples": { "success": { "value": { "status": 1, "mail": "user@gmail.com", "mailId": 123456 } }, "error": { "value": { "status": 0, "error": "No mails yet" } } } } } } } } }, "/api/mail/getCode": { "get": { "tags": [ "Mail activations" ], "summary": "Get received mail code", "parameters": [ { "name": "mailId", "in": "query", "required": true, "schema": { "type": "integer", "example": 123456 } } ], "responses": { "200": { "description": "Mail code response.", "content": { "application/json": { "examples": { "success": { "value": { "status": 1, "code": "12345" } }, "wait": { "value": { "status": 0, "error": "Code has not been received yet, please try again later" } } } } } } } } }, "/api/mail/getPriceRests": { "get": { "tags": [ "Mail activations" ], "summary": "Get temporary mail offers with prices and counts", "parameters": [ { "name": "service", "in": "query", "schema": { "type": "string", "example": "tg" } }, { "name": "domain", "in": "query", "schema": { "type": "string", "example": "gmail.com" } } ], "responses": { "200": { "description": "Available mail offers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MailPriceRests" }, "examples": { "success": { "value": { "status": 1, "data": { "tg": { "gmail.com": { "price": 0.12, "count": 42 } } } } } } } } } } } }, "/api/mail/getPrices": { "get": { "tags": [ "Mail activations" ], "summary": "Get temporary mail prices", "parameters": [ { "name": "service", "in": "query", "schema": { "type": "string", "example": "tg" } }, { "name": "domain", "in": "query", "schema": { "type": "string", "example": "gmail.com" } } ], "responses": { "200": { "description": "Price list.", "content": { "application/json": { "examples": { "success": { "value": { "status": 1, "prices": [ { "service": "tg", "domain": "gmail.com", "price": 0.12 } ] } } } } } } } } }, "/api/mail/getRests": { "get": { "tags": [ "Mail activations" ], "summary": "Get temporary mail stock counts", "parameters": [ { "name": "service", "in": "query", "required": false, "schema": { "type": "string", "example": "tg" }, "description": "Optional service code." }, { "name": "domain", "in": "query", "required": false, "schema": { "type": "string", "example": "gmail.com" }, "description": "Optional mail domain." } ], "responses": { "200": { "description": "Available mail stock counts.", "content": { "application/json": { "examples": { "success": { "value": { "status": 1, "rests": { "tg": { "gmail.com": 42 } } } }, "unavailable": { "value": { "status": 0, "error": "Mail activations are temporarily unavailable", "rests": [] } } } } } } } } }, "/api/mail/getStatus": { "get": { "tags": [ "Mail activations" ], "summary": "Get temporary mail activation status", "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "integer", "example": 123456 }, "description": "Mail activation ID." } ], "responses": { "200": { "description": "Mail activation status.", "content": { "application/json": { "examples": { "success": { "value": { "status": 1, "data": { "status": 1, "status_description": "Waiting code", "available_to_get_next_code": false, "last_code": null } } }, "error": { "value": { "status": 0, "error": "No activation found with such id" } } } } } } } } }, "/api/mail/setStatus": { "get": { "tags": [ "Mail activations" ], "summary": "Update temporary mail activation status", "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "integer", "example": 123456 }, "description": "Mail activation ID." }, { "name": "status", "in": "query", "required": true, "schema": { "type": "integer", "example": 6 }, "description": "Status: OK or wait next code, depending on activation state." } ], "responses": { "200": { "description": "Mail status update result.", "content": { "application/json": { "examples": { "success": { "value": { "status": 1, "message": "Activation updated" } }, "waitNext": { "value": { "status": 1, "message": "Wait for next code" } }, "error": { "value": { "status": 0, "error": "Bad status param" } } } } } } } } }, "/api/mail/requestRefund": { "get": { "tags": [ "Mail activations" ], "summary": "Cancel and refund a provider mail activation", "description": "Cancels an active provider purchase and returns its price to the authenticated account after provider confirmation.", "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "integer", "example": 123456 }, "description": "Mail activation ID." } ], "responses": { "200": { "description": "Refund response.", "content": { "text/plain": { "examples": { "success": { "value": "SUCCESS" } } }, "application/json": { "examples": { "error": { "value": { "status": 0, "error": "Bad activation status" } } } } } } } } }, "/api/sms/{action}": { "get": { "tags": [ "SMS activations" ], "summary": "SMS action endpoint", "description": "Alternative REST-style URL for the same SMSHub-compatible actions handled by /stubs/handler_api.php. The path segment is copied to the action parameter internally.", "parameters": [ { "name": "action", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "getBalance", "getNumber", "getNumberV2", "getNumberV3", "getStatus", "getStatusV2", "setStatus", "getPrices", "getPricesV2", "getPricesV3", "getCountries", "getOperators", "getServices", "getServicesList", "getFullOptPhonePrices", "free_phones", "2faReturn", "reject", "returnMoneyActivation" ] }, "description": "SMS API action name." }, { "name": "service", "in": "query", "schema": { "type": "string", "example": "tg" }, "description": "Service code, for example tg for Telegram." }, { "name": "country", "in": "query", "schema": { "type": "string", "example": "0" }, "description": "Country code." }, { "name": "id", "in": "query", "schema": { "type": "string", "example": "123456" }, "description": "Activation ID for getStatus or setStatus." }, { "name": "status", "in": "query", "schema": { "type": "integer", "enum": [ 1, 3, 6, 8 ] }, "description": "Status for setStatus: 1 ready, 3 retry, 6 complete, 8 cancel." }, { "name": "maxPrice", "in": "query", "schema": { "type": "number", "example": 0.5 }, "description": "Maximum accepted client price." } ], "responses": { "200": { "description": "Expected SMSHub-compatible plain text or JSON response.", "content": { "text/plain": { "examples": { "balance": { "summary": "getBalance", "value": "ACCESS_BALANCE:12.34" }, "number": { "summary": "getNumber", "value": "ACCESS_NUMBER:123456:447700900123" }, "wait": { "summary": "getStatus waiting", "value": "STATUS_WAIT_CODE" }, "code": { "summary": "getStatus success", "value": "STATUS_OK:12345" }, "cancel": { "summary": "setStatus cancel", "value": "ACCESS_CANCEL" }, "error": { "summary": "Error", "value": "BAD_KEY" } } }, "application/json": { "examples": { "numberV2": { "summary": "getNumberV2", "value": { "activationId": "123456", "phoneNumber": "447700900123", "activationCost": 0.12, "countryCode": "0", "canGetAnotherSms": true } }, "prices": { "summary": "getPrices", "value": { "0": { "tg": { "cost": 0.12, "count": 42 } } } } } } } } } }, "post": { "tags": [ "SMS activations" ], "summary": "SMS action endpoint", "description": "POST alias for /api/sms/{action}. Accepts the same query/form parameters as the GET endpoint.", "parameters": [ { "name": "action", "in": "path", "required": true, "schema": { "type": "string" }, "description": "SMS API action name." } ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "service": { "type": "string", "example": "tg" }, "country": { "type": "string", "example": "0" }, "id": { "type": "string", "example": "123456" }, "status": { "type": "integer", "enum": [ 1, 3, 6, 8 ] }, "maxPrice": { "type": "number", "example": 0.5 } } } }, "application/json": { "schema": { "type": "object", "properties": { "service": { "type": "string", "example": "tg" }, "country": { "type": "string", "example": "0" }, "id": { "type": "string", "example": "123456" }, "status": { "type": "integer", "enum": [ 1, 3, 6, 8 ] }, "maxPrice": { "type": "number", "example": 0.5 } } } } } }, "responses": { "200": { "description": "Expected SMSHub-compatible plain text or JSON response.", "content": { "text/plain": { "examples": { "balance": { "summary": "getBalance", "value": "ACCESS_BALANCE:12.34" }, "number": { "summary": "getNumber", "value": "ACCESS_NUMBER:123456:447700900123" }, "wait": { "summary": "getStatus waiting", "value": "STATUS_WAIT_CODE" }, "code": { "summary": "getStatus success", "value": "STATUS_OK:12345" }, "cancel": { "summary": "setStatus cancel", "value": "ACCESS_CANCEL" }, "error": { "summary": "Error", "value": "BAD_KEY" } } }, "application/json": { "examples": { "numberV2": { "summary": "getNumberV2", "value": { "activationId": "123456", "phoneNumber": "447700900123", "activationCost": 0.12, "countryCode": "0", "canGetAnotherSms": true } }, "prices": { "summary": "getPrices", "value": { "0": { "tg": { "cost": 0.12, "count": 42 } } } } } } } } } } }, "/api/sms/getBalance": { "get": { "tags": [ "Balance" ], "summary": "Get balance", "description": "REST-style alias for action=getBalance on /stubs/handler_api.php.", "parameters": [], "responses": { "200": { "description": "Current client balance.", "content": { "text/plain": { "examples": { "success": { "value": "ACCESS_BALANCE:12.34" }, "badKey": { "value": "BAD_KEY" } } } } } } }, "post": { "tags": [ "Balance" ], "summary": "Get balance", "description": "POST alias for getBalance. Accepts the same query/form parameters as GET.", "parameters": [], "responses": { "200": { "description": "Current client balance.", "content": { "text/plain": { "examples": { "success": { "value": "ACCESS_BALANCE:12.34" }, "badKey": { "value": "BAD_KEY" } } } } } } } }, "/api/sms/getNumber": { "get": { "tags": [ "SMS activations" ], "summary": "Get phone number", "description": "REST-style alias for action=getNumber on /stubs/handler_api.php.", "parameters": [ { "name": "service", "in": "query", "required": true, "schema": { "type": "string", "example": "tg" }, "description": "Service code, for example tg for Telegram." }, { "name": "country", "in": "query", "required": true, "schema": { "type": "string", "example": "0" }, "description": "Country code." }, { "name": "maxPrice", "in": "query", "required": false, "schema": { "type": "number", "example": 0.5 }, "description": "Maximum accepted client price." }, { "name": "phoneException", "in": "query", "required": false, "schema": { "type": "string", "example": "7918,7900111" }, "description": "Optional blocked phone prefixes, comma-separated." } ], "responses": { "200": { "description": "Phone activation reservation result.", "content": { "text/plain": { "examples": { "success": { "value": "ACCESS_NUMBER:123456:447700900123" }, "noNumbers": { "value": "NO_NUMBERS" }, "noBalance": { "value": "NO_BALANCE" }, "badService": { "value": "BAD_SERVICE" } } } } } } }, "post": { "tags": [ "SMS activations" ], "summary": "Get phone number", "description": "POST alias for getNumber. Accepts the same query/form parameters as GET.", "parameters": [ { "name": "service", "in": "query", "required": true, "schema": { "type": "string", "example": "tg" }, "description": "Service code, for example tg for Telegram." }, { "name": "country", "in": "query", "required": true, "schema": { "type": "string", "example": "0" }, "description": "Country code." }, { "name": "maxPrice", "in": "query", "required": false, "schema": { "type": "number", "example": 0.5 }, "description": "Maximum accepted client price." }, { "name": "phoneException", "in": "query", "required": false, "schema": { "type": "string", "example": "7918,7900111" }, "description": "Optional blocked phone prefixes, comma-separated." } ], "responses": { "200": { "description": "Phone activation reservation result.", "content": { "text/plain": { "examples": { "success": { "value": "ACCESS_NUMBER:123456:447700900123" }, "noNumbers": { "value": "NO_NUMBERS" }, "noBalance": { "value": "NO_BALANCE" }, "badService": { "value": "BAD_SERVICE" } } } } } } } }, "/api/sms/getPrimeNumber": { "get": { "tags": [ "SMS activations" ], "summary": "Get prime phone number", "description": "REST-style alias for action=getPrimeNumber on /stubs/handler_api.php.", "parameters": [ { "name": "service", "in": "query", "required": true, "schema": { "type": "string", "example": "tg" }, "description": "Service code, for example tg for Telegram." }, { "name": "country", "in": "query", "required": true, "schema": { "type": "string", "example": "0" }, "description": "Country code." }, { "name": "maxPrice", "in": "query", "required": false, "schema": { "type": "number", "example": 0.5 }, "description": "Maximum accepted client price." }, { "name": "phoneException", "in": "query", "required": false, "schema": { "type": "string", "example": "7918,7900111" }, "description": "Optional blocked phone prefixes, comma-separated." } ], "responses": { "200": { "description": "Prime phone activation reservation result.", "content": { "text/plain": { "examples": { "success": { "value": "ACCESS_NUMBER:123456:447700900123" }, "noNumbers": { "value": "NO_NUMBERS" }, "noBalance": { "value": "NO_BALANCE" } } } } } } }, "post": { "tags": [ "SMS activations" ], "summary": "Get prime phone number", "description": "POST alias for getPrimeNumber. Accepts the same query/form parameters as GET.", "parameters": [ { "name": "service", "in": "query", "required": true, "schema": { "type": "string", "example": "tg" }, "description": "Service code, for example tg for Telegram." }, { "name": "country", "in": "query", "required": true, "schema": { "type": "string", "example": "0" }, "description": "Country code." }, { "name": "maxPrice", "in": "query", "required": false, "schema": { "type": "number", "example": 0.5 }, "description": "Maximum accepted client price." }, { "name": "phoneException", "in": "query", "required": false, "schema": { "type": "string", "example": "7918,7900111" }, "description": "Optional blocked phone prefixes, comma-separated." } ], "responses": { "200": { "description": "Prime phone activation reservation result.", "content": { "text/plain": { "examples": { "success": { "value": "ACCESS_NUMBER:123456:447700900123" }, "noNumbers": { "value": "NO_NUMBERS" }, "noBalance": { "value": "NO_BALANCE" } } } } } } } }, "/api/sms/getNumberV2": { "get": { "tags": [ "SMS activations" ], "summary": "Get phone number v2", "description": "REST-style alias for action=getNumberV2 on /stubs/handler_api.php.", "parameters": [ { "name": "service", "in": "query", "required": true, "schema": { "type": "string", "example": "tg" }, "description": "Service code, for example tg for Telegram." }, { "name": "country", "in": "query", "required": true, "schema": { "type": "string", "example": "0" }, "description": "Country code." }, { "name": "maxPrice", "in": "query", "required": false, "schema": { "type": "number", "example": 0.5 }, "description": "Maximum accepted client price." }, { "name": "phoneException", "in": "query", "required": false, "schema": { "type": "string", "example": "7918,7900111" }, "description": "Optional blocked phone prefixes, comma-separated." } ], "responses": { "200": { "description": "JSON phone activation reservation result.", "content": { "application/json": { "examples": { "success": { "value": { "activationId": "123456", "phoneNumber": "447700900123", "activationCost": 0.12, "countryCode": "0", "canGetAnotherSms": true } }, "error": { "value": { "status": "ERROR", "error": "NO_NUMBERS" } } } } } } } }, "post": { "tags": [ "SMS activations" ], "summary": "Get phone number v2", "description": "POST alias for getNumberV2. Accepts the same query/form parameters as GET.", "parameters": [ { "name": "service", "in": "query", "required": true, "schema": { "type": "string", "example": "tg" }, "description": "Service code, for example tg for Telegram." }, { "name": "country", "in": "query", "required": true, "schema": { "type": "string", "example": "0" }, "description": "Country code." }, { "name": "maxPrice", "in": "query", "required": false, "schema": { "type": "number", "example": 0.5 }, "description": "Maximum accepted client price." }, { "name": "phoneException", "in": "query", "required": false, "schema": { "type": "string", "example": "7918,7900111" }, "description": "Optional blocked phone prefixes, comma-separated." } ], "responses": { "200": { "description": "JSON phone activation reservation result.", "content": { "application/json": { "examples": { "success": { "value": { "activationId": "123456", "phoneNumber": "447700900123", "activationCost": 0.12, "countryCode": "0", "canGetAnotherSms": true } }, "error": { "value": { "status": "ERROR", "error": "NO_NUMBERS" } } } } } } } } }, "/api/sms/getNumberV3": { "get": { "tags": [ "SMS activations" ], "summary": "Get phone number v3", "description": "REST-style alias for action=getNumberV3 on /stubs/handler_api.php.", "parameters": [ { "name": "service", "in": "query", "required": true, "schema": { "type": "string", "example": "tg" }, "description": "Service code, for example tg for Telegram." }, { "name": "country", "in": "query", "required": true, "schema": { "type": "string", "example": "0" }, "description": "Country code." }, { "name": "maxPrice", "in": "query", "required": false, "schema": { "type": "number", "example": 0.5 }, "description": "Maximum accepted client price." }, { "name": "phoneException", "in": "query", "required": false, "schema": { "type": "string", "example": "7918,7900111" }, "description": "Optional blocked phone prefixes, comma-separated." } ], "responses": { "200": { "description": "JSON phone activation reservation result.", "content": { "application/json": { "examples": { "success": { "value": { "activationId": "123456", "phoneNumber": "447700900123", "activationCost": 0.12, "countryCode": "0", "serviceCode": "tg" } }, "error": { "value": { "status": "ERROR", "error": "NO_NUMBERS" } } } } } } } }, "post": { "tags": [ "SMS activations" ], "summary": "Get phone number v3", "description": "POST alias for getNumberV3. Accepts the same query/form parameters as GET.", "parameters": [ { "name": "service", "in": "query", "required": true, "schema": { "type": "string", "example": "tg" }, "description": "Service code, for example tg for Telegram." }, { "name": "country", "in": "query", "required": true, "schema": { "type": "string", "example": "0" }, "description": "Country code." }, { "name": "maxPrice", "in": "query", "required": false, "schema": { "type": "number", "example": 0.5 }, "description": "Maximum accepted client price." }, { "name": "phoneException", "in": "query", "required": false, "schema": { "type": "string", "example": "7918,7900111" }, "description": "Optional blocked phone prefixes, comma-separated." } ], "responses": { "200": { "description": "JSON phone activation reservation result.", "content": { "application/json": { "examples": { "success": { "value": { "activationId": "123456", "phoneNumber": "447700900123", "activationCost": 0.12, "countryCode": "0", "serviceCode": "tg" } }, "error": { "value": { "status": "ERROR", "error": "NO_NUMBERS" } } } } } } } } }, "/api/sms/getStatus": { "get": { "tags": [ "SMS activations" ], "summary": "Get SMS status/code", "description": "REST-style alias for action=getStatus on /stubs/handler_api.php.", "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "string", "example": "123456" }, "description": "Activation ID." } ], "responses": { "200": { "description": "SMS activation status.", "content": { "text/plain": { "examples": { "wait": { "value": "STATUS_WAIT_CODE" }, "retry": { "value": "STATUS_WAIT_RESEND" }, "success": { "value": "STATUS_OK:12345" }, "cancel": { "value": "STATUS_CANCEL" }, "missing": { "value": "NO_ACTIVATION" } } } } } } }, "post": { "tags": [ "SMS activations" ], "summary": "Get SMS status/code", "description": "POST alias for getStatus. Accepts the same query/form parameters as GET.", "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "string", "example": "123456" }, "description": "Activation ID." } ], "responses": { "200": { "description": "SMS activation status.", "content": { "text/plain": { "examples": { "wait": { "value": "STATUS_WAIT_CODE" }, "retry": { "value": "STATUS_WAIT_RESEND" }, "success": { "value": "STATUS_OK:12345" }, "cancel": { "value": "STATUS_CANCEL" }, "missing": { "value": "NO_ACTIVATION" } } } } } } } }, "/api/sms/getStatusV2": { "get": { "tags": [ "SMS activations" ], "summary": "Get SMS status/code v2", "description": "REST-style alias for action=getStatusV2 on /stubs/handler_api.php.", "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "string", "example": "123456" }, "description": "Activation ID." } ], "responses": { "200": { "description": "SMS activation status as JSON.", "content": { "application/json": { "examples": { "wait": { "value": { "status": "STATUS_WAIT_CODE", "smsCode": null, "smsText": null } }, "success": { "value": { "status": "STATUS_OK", "smsCode": "12345", "smsText": "Your code is 12345" } } } } } } } }, "post": { "tags": [ "SMS activations" ], "summary": "Get SMS status/code v2", "description": "POST alias for getStatusV2. Accepts the same query/form parameters as GET.", "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "string", "example": "123456" }, "description": "Activation ID." } ], "responses": { "200": { "description": "SMS activation status as JSON.", "content": { "application/json": { "examples": { "wait": { "value": { "status": "STATUS_WAIT_CODE", "smsCode": null, "smsText": null } }, "success": { "value": { "status": "STATUS_OK", "smsCode": "12345", "smsText": "Your code is 12345" } } } } } } } } }, "/api/sms/setStatus": { "get": { "tags": [ "SMS activations" ], "summary": "Set activation status", "description": "REST-style alias for action=setStatus on /stubs/handler_api.php.", "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "string", "example": "123456" }, "description": "Activation ID." }, { "name": "status", "in": "query", "required": true, "schema": { "type": "integer", "enum": [ 1, 3, 6, 8 ] }, "description": "1 ready, 3 retry, 6 complete, 8 cancel." } ], "responses": { "200": { "description": "Activation status update result.", "content": { "text/plain": { "examples": { "ready": { "value": "ACCESS_READY" }, "retry": { "value": "ACCESS_RETRY_GET" }, "complete": { "value": "ACCESS_ACTIVATION" }, "cancel": { "value": "ACCESS_CANCEL" }, "badStatus": { "value": "BAD_STATUS" } } } } } } }, "post": { "tags": [ "SMS activations" ], "summary": "Set activation status", "description": "POST alias for setStatus. Accepts the same query/form parameters as GET.", "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "string", "example": "123456" }, "description": "Activation ID." }, { "name": "status", "in": "query", "required": true, "schema": { "type": "integer", "enum": [ 1, 3, 6, 8 ] }, "description": "1 ready, 3 retry, 6 complete, 8 cancel." } ], "responses": { "200": { "description": "Activation status update result.", "content": { "text/plain": { "examples": { "ready": { "value": "ACCESS_READY" }, "retry": { "value": "ACCESS_RETRY_GET" }, "complete": { "value": "ACCESS_ACTIVATION" }, "cancel": { "value": "ACCESS_CANCEL" }, "badStatus": { "value": "BAD_STATUS" } } } } } } } }, "/api/sms/getPrices": { "get": { "tags": [ "SMS activations" ], "summary": "Get prices", "description": "REST-style alias for action=getPrices on /stubs/handler_api.php.", "parameters": [ { "name": "service", "in": "query", "required": false, "schema": { "type": "string", "example": "tg" }, "description": "Optional service code." }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "example": "0" }, "description": "Optional country code." } ], "responses": { "200": { "description": "Prices by country and service.", "content": { "application/json": { "examples": { "success": { "value": { "0": { "tg": { "cost": 0.12, "count": 42 } } } } } } } } } }, "post": { "tags": [ "SMS activations" ], "summary": "Get prices", "description": "POST alias for getPrices. Accepts the same query/form parameters as GET.", "parameters": [ { "name": "service", "in": "query", "required": false, "schema": { "type": "string", "example": "tg" }, "description": "Optional service code." }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "example": "0" }, "description": "Optional country code." } ], "responses": { "200": { "description": "Prices by country and service.", "content": { "application/json": { "examples": { "success": { "value": { "0": { "tg": { "cost": 0.12, "count": 42 } } } } } } } } } } }, "/api/sms/getPricesV2": { "get": { "tags": [ "SMS activations" ], "summary": "Get prices v2", "description": "REST-style alias for action=getPricesV2 on /stubs/handler_api.php.", "parameters": [ { "name": "service", "in": "query", "required": false, "schema": { "type": "string", "example": "tg" }, "description": "Optional service code." }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "example": "0" }, "description": "Optional country code." } ], "responses": { "200": { "description": "Detailed prices by country and service.", "content": { "application/json": { "examples": { "success": { "value": { "tg": { "0": { "cost": 0.12, "count": 42 } } } } } } } } } }, "post": { "tags": [ "SMS activations" ], "summary": "Get prices v2", "description": "POST alias for getPricesV2. Accepts the same query/form parameters as GET.", "parameters": [ { "name": "service", "in": "query", "required": false, "schema": { "type": "string", "example": "tg" }, "description": "Optional service code." }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "example": "0" }, "description": "Optional country code." } ], "responses": { "200": { "description": "Detailed prices by country and service.", "content": { "application/json": { "examples": { "success": { "value": { "tg": { "0": { "cost": 0.12, "count": 42 } } } } } } } } } } }, "/api/sms/getPricesV3": { "get": { "tags": [ "SMS activations" ], "summary": "Get prices v3", "description": "REST-style alias for action=getPricesV3 on /stubs/handler_api.php.", "parameters": [ { "name": "service", "in": "query", "required": false, "schema": { "type": "string", "example": "tg" }, "description": "Optional service code." }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "example": "0" }, "description": "Optional country code." } ], "responses": { "200": { "description": "Optimized prices by country and service.", "content": { "application/json": { "examples": { "success": { "value": { "tg": { "0": { "cost": 0.12, "count": 42, "retail_price": 0.12 } } } } } } } } } }, "post": { "tags": [ "SMS activations" ], "summary": "Get prices v3", "description": "POST alias for getPricesV3. Accepts the same query/form parameters as GET.", "parameters": [ { "name": "service", "in": "query", "required": false, "schema": { "type": "string", "example": "tg" }, "description": "Optional service code." }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "example": "0" }, "description": "Optional country code." } ], "responses": { "200": { "description": "Optimized prices by country and service.", "content": { "application/json": { "examples": { "success": { "value": { "tg": { "0": { "cost": 0.12, "count": 42, "retail_price": 0.12 } } } } } } } } } } }, "/api/sms/getCountries": { "get": { "tags": [ "Reference" ], "summary": "Get countries", "description": "REST-style alias for action=getCountries on /stubs/handler_api.php.", "parameters": [], "responses": { "200": { "description": "Supported countries.", "content": { "application/json": { "examples": { "success": { "value": { "0": "Russia", "1": "Ukraine", "187": "United States" } } } } } } } }, "post": { "tags": [ "Reference" ], "summary": "Get countries", "description": "POST alias for getCountries. Accepts the same query/form parameters as GET.", "parameters": [], "responses": { "200": { "description": "Supported countries.", "content": { "application/json": { "examples": { "success": { "value": { "0": "Russia", "1": "Ukraine", "187": "United States" } } } } } } } } }, "/api/sms/getOperators": { "get": { "tags": [ "Reference" ], "summary": "Get operators", "description": "REST-style alias for action=getOperators on /stubs/handler_api.php.", "parameters": [ { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "example": "0" }, "description": "Optional country code." } ], "responses": { "200": { "description": "Supported operators.", "content": { "application/json": { "examples": { "success": { "value": { "any": "Any operator" } } } } } } } }, "post": { "tags": [ "Reference" ], "summary": "Get operators", "description": "POST alias for getOperators. Accepts the same query/form parameters as GET.", "parameters": [ { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "example": "0" }, "description": "Optional country code." } ], "responses": { "200": { "description": "Supported operators.", "content": { "application/json": { "examples": { "success": { "value": { "any": "Any operator" } } } } } } } } }, "/api/sms/getServices": { "get": { "tags": [ "Reference" ], "summary": "Get services", "description": "REST-style alias for action=getServices on /stubs/handler_api.php.", "parameters": [], "responses": { "200": { "description": "Supported services.", "content": { "application/json": { "examples": { "success": { "value": { "tg": "Telegram", "wa": "WhatsApp", "go": "Google" } } } } } } } }, "post": { "tags": [ "Reference" ], "summary": "Get services", "description": "POST alias for getServices. Accepts the same query/form parameters as GET.", "parameters": [], "responses": { "200": { "description": "Supported services.", "content": { "application/json": { "examples": { "success": { "value": { "tg": "Telegram", "wa": "WhatsApp", "go": "Google" } } } } } } } } }, "/api/sms/getServicesList": { "get": { "tags": [ "Reference" ], "summary": "Get services list", "description": "REST-style alias for action=getServicesList on /stubs/handler_api.php.", "parameters": [], "responses": { "200": { "description": "Supported services list.", "content": { "application/json": { "examples": { "success": { "value": [ { "code": "tg", "name": "Telegram" }, { "code": "wa", "name": "WhatsApp" } ] } } } } } } }, "post": { "tags": [ "Reference" ], "summary": "Get services list", "description": "POST alias for getServicesList. Accepts the same query/form parameters as GET.", "parameters": [], "responses": { "200": { "description": "Supported services list.", "content": { "application/json": { "examples": { "success": { "value": [ { "code": "tg", "name": "Telegram" }, { "code": "wa", "name": "WhatsApp" } ] } } } } } } } }, "/api/sms/getFullOptPhonePrices": { "get": { "tags": [ "Reference" ], "summary": "Get full wholesale phone prices", "description": "REST-style alias for action=getFullOptPhonePrices on /stubs/handler_api.php.", "parameters": [ { "name": "service", "in": "query", "required": false, "schema": { "type": "string", "example": "tg" }, "description": "Optional service code." }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "example": "0" }, "description": "Optional country code." } ], "responses": { "200": { "description": "Full wholesale phone prices.", "content": { "application/json": { "examples": { "success": { "value": { "tg": { "0": { "cost": 0.12, "count": 42 } } } } } } } } } }, "post": { "tags": [ "Reference" ], "summary": "Get full wholesale phone prices", "description": "POST alias for getFullOptPhonePrices. Accepts the same query/form parameters as GET.", "parameters": [ { "name": "service", "in": "query", "required": false, "schema": { "type": "string", "example": "tg" }, "description": "Optional service code." }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "example": "0" }, "description": "Optional country code." } ], "responses": { "200": { "description": "Full wholesale phone prices.", "content": { "application/json": { "examples": { "success": { "value": { "tg": { "0": { "cost": 0.12, "count": 42 } } } } } } } } } } }, "/api/sms/2faReturn": { "get": { "tags": [ "SMS activations" ], "summary": "2FA return action", "description": "REST-style alias for action=2faReturn on /stubs/handler_api.php.", "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "string", "example": "123456" }, "description": "Activation ID." } ], "responses": { "200": { "description": "2FA return result.", "content": { "text/plain": { "examples": { "success": { "value": "SUCCESS" }, "error": { "value": "NO_ACTIVATION" } } }, "application/json": { "examples": { "success": { "value": { "status": 1 } } } } } } } }, "post": { "tags": [ "SMS activations" ], "summary": "2FA return action", "description": "POST alias for 2faReturn. Accepts the same query/form parameters as GET.", "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "string", "example": "123456" }, "description": "Activation ID." } ], "responses": { "200": { "description": "2FA return result.", "content": { "text/plain": { "examples": { "success": { "value": "SUCCESS" }, "error": { "value": "NO_ACTIVATION" } } }, "application/json": { "examples": { "success": { "value": { "status": 1 } } } } } } } } }, "/api/sms/reject": { "get": { "tags": [ "SMS activations" ], "summary": "Reject activation", "description": "REST-style alias for action=reject on /stubs/handler_api.php.", "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "string", "example": "123456" }, "description": "Activation ID." } ], "responses": { "200": { "description": "Reject result.", "content": { "text/plain": { "examples": { "success": { "value": "ACCESS_CANCEL" }, "error": { "value": "NO_ACTIVATION" } } } } } } }, "post": { "tags": [ "SMS activations" ], "summary": "Reject activation", "description": "POST alias for reject. Accepts the same query/form parameters as GET.", "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "string", "example": "123456" }, "description": "Activation ID." } ], "responses": { "200": { "description": "Reject result.", "content": { "text/plain": { "examples": { "success": { "value": "ACCESS_CANCEL" }, "error": { "value": "NO_ACTIVATION" } } } } } } } }, "/api/sms/returnMoneyActivation": { "get": { "tags": [ "SMS activations" ], "summary": "Request activation refund", "description": "REST-style alias for action=returnMoneyActivation on /stubs/handler_api.php.", "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "string", "example": "123456" }, "description": "Activation ID." }, { "name": "reason", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional refund reason." } ], "responses": { "200": { "description": "Refund result.", "content": { "text/plain": { "examples": { "success": { "value": "SUCCESS" }, "error": { "value": "BAD_STATUS" } } } } } } }, "post": { "tags": [ "SMS activations" ], "summary": "Request activation refund", "description": "POST alias for returnMoneyActivation. Accepts the same query/form parameters as GET.", "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "string", "example": "123456" }, "description": "Activation ID." }, { "name": "reason", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional refund reason." } ], "responses": { "200": { "description": "Refund result.", "content": { "text/plain": { "examples": { "success": { "value": "SUCCESS" }, "error": { "value": "BAD_STATUS" } } } } } } } }, "/api/rent/getOffers": { "get": { "tags": [ "Phone rentals" ], "summary": "Get phone rental offers", "description": "Returns SIMUB retail prices and availability without exposing the upstream Provider. Optional filters: country, duration and max_price.", "parameters": [ { "$ref": "#/components/parameters/rentalService" }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "example": "0" } }, { "name": "duration", "in": "query", "required": false, "schema": { "type": "integer", "example": 24 } }, { "name": "max_price", "in": "query", "required": false, "schema": { "type": "number", "format": "float", "example": 2.5 }, "description": "Maximum accepted SIMUB retail price. maxPrice is accepted as an alias." } ], "responses": { "200": { "description": "Available rental offers.", "content": { "application/json": { "example": { "status": 1, "service": "tg", "offers": [ { "country": "0", "country_id": 1, "country_name": "Russia", "country_iso": "RU", "duration": 24, "count": 12, "price": 1.37 } ] } } } }, "403": { "description": "Invalid API key." } } } }, "/api/rent/getNumber": { "get": { "tags": [ "Phone rentals" ], "summary": "Rent a phone number", "description": "Purchases the cheapest matching Provider offer at or below max_price. GET and POST are accepted. The user balance is reserved before the Provider call and automatically refunded if the purchase fails.", "parameters": [ { "$ref": "#/components/parameters/rentalService" }, { "$ref": "#/components/parameters/rentalCountry" }, { "$ref": "#/components/parameters/rentalDuration" }, { "name": "max_price", "in": "query", "required": false, "schema": { "type": "number", "format": "float", "example": 2.5 }, "description": "Maximum accepted SIMUB price. maxPrice is accepted as an alias." } ], "responses": { "201": { "description": "Rental created.", "content": { "application/json": { "example": { "status": 1, "request_id": 12540, "number": "15551234567", "service": "tg", "country": "0", "duration": 24, "price": 1.37, "available_to": "2026-08-23T20:00:00+00:00" } } } }, "409": { "description": "No matching rental is available." }, "422": { "description": "Insufficient balance or rejected purchase." }, "503": { "description": "Provider temporarily unavailable." } } } }, "/api/rent/getStatus": { "get": { "tags": [ "Phone rentals" ], "summary": "Get rental status and SMS", "description": "Synchronizes the rental with its Provider and returns all received messages. getSms and getAllSms are aliases.", "parameters": [ { "$ref": "#/components/parameters/rentalId" } ], "responses": { "200": { "description": "Rental status and messages.", "content": { "application/json": { "example": { "status": 1, "data": { "request_id": 12540, "number": "15551234567", "status": "active", "service": "tg", "country": "0", "country_name": "Russia", "duration": 24, "price": 1.37, "available_to": "2026-08-23T20:00:00+00:00", "sms": [ { "sender": "Telegram", "code": "12345", "message": "Your Telegram code is 12345", "time": "2026-08-22T20:10:00+00:00" } ] } } } } }, "404": { "description": "Rental not found or owned by another user." }, "503": { "description": "Provider messages temporarily unavailable." } } } }, "/api/rent/getSms": { "$ref": "#/paths/~1api~1rent~1getStatus" }, "/api/rent/getAllSms": { "$ref": "#/paths/~1api~1rent~1getStatus" }, "/api/rent/getAllRequests": { "get": { "tags": [ "Phone rentals" ], "summary": "List phone rentals", "description": "Returns the authenticated API user's latest 100 rentals. Upstream Provider data is never exposed.", "parameters": [], "responses": { "200": { "description": "Rental list.", "content": { "application/json": { "example": { "status": 1, "data": [ { "request_id": 12540, "number": "15551234567", "status": "active", "service": "tg", "country": "0", "duration": 24, "price": 1.37, "sms": [] } ] } } } } } } }, "/api/rent/setStatus": { "get": { "tags": [ "Phone rentals" ], "summary": "Cancel or finish a rental", "description": "Use cancel during the first 20 minutes while no SMS has been received, or finish/close to terminate an active rental. GET and POST are accepted.", "parameters": [ { "$ref": "#/components/parameters/rentalId" }, { "name": "status", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "cancel", "finish", "close" ], "example": "finish" } } ], "responses": { "200": { "description": "Status updated.", "content": { "application/json": { "example": { "status": 1, "request_id": 12540, "rental_status": "finished" } } } }, "422": { "description": "The requested transition is not allowed." }, "503": { "description": "Provider temporarily unavailable." } } } }, "/api/v1/emails": { "get": { "tags": [ "Email activations v1" ], "summary": "Get email activations", "security": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "size", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "sort[id]", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } }, { "name": "search", "in": "query", "schema": { "type": "string", "maxLength": 253 } }, { "name": "status[id][]", "in": "query", "description": "Optional Hero-compatible status identifiers.", "schema": { "type": "array", "maxItems": 7, "items": { "type": "integer", "minimum": 1, "maximum": 7 } } }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Email activations owned by the authenticated user.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/V1EmailActivation" } }, "meta": { "$ref": "#/components/schemas/V1Pagination" } } } } } }, "401": { "description": "Invalid API key." }, "422": { "description": "Invalid query parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Error" } } } } } }, "post": { "tags": [ "Email activations v1" ], "summary": "Purchase one email activation", "description": "Purchases an email from HeroSMS inventory at the displayed SIMUB price.", "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BuyEmail" } } } }, "responses": { "201": { "description": "Email activation purchased.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/V1EmailActivation" } } } } } }, "402": { "description": "Insufficient SIMUB balance." }, "409": { "description": "A previous provider operation is unresolved." }, "422": { "description": "Invalid or unavailable email offer." }, "503": { "description": "Provider result is unavailable or ambiguous. Do not retry until reconciled." } } } }, "/api/v1/emails/batch": { "post": { "tags": [ "Email activations v1" ], "summary": "Purchase a batch of email activations", "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BuyEmailBatch" } } } }, "responses": { "201": { "description": "Email activation batch purchased.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/V1EmailActivation" } }, "meta": { "type": "object", "properties": { "info": { "type": "string", "example": "Email activation successful" }, "count": { "type": "integer", "example": 3 } } } } } } } }, "402": { "description": "Insufficient SIMUB balance." }, "409": { "description": "A previous provider operation is unresolved." }, "422": { "description": "Invalid or unavailable email offer." }, "503": { "description": "Provider result is unavailable or ambiguous." } } } }, "/api/v1/emails/domains": { "get": { "tags": [ "Email activations v1" ], "summary": "Get available email domains", "description": "Returns HeroSMS availability with SIMUB customer prices; provider credentials and wholesale prices are never exposed.", "security": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "site", "in": "query", "schema": { "type": "string", "maxLength": 2048, "example": "telegram.com" } } ], "responses": { "200": { "description": "Available domains sorted by SIMUB price.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/V1EmailDomain" } } } } } } }, "401": { "description": "Invalid API key." }, "422": { "description": "Invalid site." }, "503": { "description": "Provider temporarily unavailable." } } } }, "/api/v1/emails/{emailId}": { "get": { "tags": [ "Email activations v1" ], "summary": "Get and refresh an email activation", "security": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "emailId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "SIMUB email activation ID." } ], "responses": { "200": { "description": "Refreshed activation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/V1EmailActivation" } } } } } }, "404": { "description": "Email activation not found or not owned by this user." }, "503": { "description": "Provider temporarily unavailable." } } }, "delete": { "tags": [ "Email activations v1" ], "summary": "Cancel an unused email activation", "description": "Cancels at HeroSMS and refunds the SIMUB customer exactly once.", "security": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "emailId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "204": { "description": "Email activation cancelled and refunded, or already cancelled." }, "404": { "description": "Email activation not found or not owned by this user." }, "422": { "description": "The activation already received a code and cannot be cancelled." }, "503": { "description": "Cancellation result is ambiguous. Do not retry until reconciled." } } } }, "/api/v1/emails/{emailId}/reorder": { "post": { "tags": [ "Email activations v1" ], "summary": "Reorder an email activation", "description": "Asks HeroSMS for a replacement while retaining the same SIMUB activation ID and without a second customer charge.", "security": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "emailId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Reordered email activation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/V1EmailActivation" } } } } } }, "404": { "description": "Email activation not found or not owned by this user." }, "422": { "description": "A cancelled email cannot be reordered." }, "503": { "description": "Reorder result is ambiguous. Do not retry until reconciled." } } } }, "/api/v1/activations": { "get": { "tags": [ "Activations v1" ], "summary": "Get active activations", "security": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "size", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "search", "in": "query", "schema": { "type": "string" } }, { "name": "verificationType", "in": "query", "schema": { "type": "string", "enum": [ "sms", "call" ] } } ], "responses": { "200": { "description": "Active activations with their OTP lists.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/V1Activation" } }, "meta": { "$ref": "#/components/schemas/V1Pagination" } } } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Error" } } } } } }, "post": { "tags": [ "Activations v1" ], "summary": "Purchase one or more activations", "description": "Hero-style activation purchase. SIMUB uses HeroSMS as its sole phone inventory source and keeps provider credentials private.", "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BuyActivation" } } } }, "responses": { "200": { "description": "Purchased activations.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/V1Activation" } } } } } } }, "402": { "description": "Insufficient SIMUB balance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Error" } } } }, "404": { "description": "No matching activation is available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Error" } } } }, "422": { "description": "Invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Error" } } } } } } }, "/api/v1/activations/history": { "get": { "tags": [ "Activations v1" ], "summary": "Get activation history", "security": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "services", "in": "query", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "countries", "in": "query", "schema": { "type": "array", "items": { "type": "integer" } } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "size", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "search", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "History rows, totals and pagination metadata." }, "401": { "description": "Invalid API key." }, "422": { "description": "Invalid date or filter." } } } }, "/api/v1/activations/offers/{verificationType}": { "get": { "tags": [ "Activations v1" ], "summary": "Get activation offers", "security": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "verificationType", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "sms", "call" ] } }, { "name": "services", "in": "query", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "countries", "in": "query", "schema": { "type": "array", "items": { "type": "integer" } } } ], "responses": { "200": { "description": "Offers grouped by service and country, with price-to-quantity maps." }, "401": { "description": "Invalid API key." } } } }, "/api/v1/activations/stats": { "get": { "tags": [ "Activations v1" ], "summary": "Get current user activation statistics", "security": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "date", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Counts and success percentages grouped by country and service." }, "401": { "description": "Invalid API key." } } } }, "/api/v1/activations/{activationId}": { "delete": { "tags": [ "Activations v1" ], "summary": "Cancel an unused activation and refund its reservation", "security": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "activationId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Cancelled." }, "404": { "description": "Activation not found." }, "422": { "description": "The activation cannot be cancelled." } } } }, "/api/v1/activations/{activationId}/finish": { "post": { "tags": [ "Activations v1" ], "summary": "Complete an activation", "security": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "activationId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Completed." }, "404": { "description": "Activation not found." }, "422": { "description": "The activation cannot be completed." } } } }, "/api/v1/activations/{activationId}/replace": { "post": { "tags": [ "Activations v1" ], "summary": "Replace an activation number", "description": "Requests a replacement from HeroSMS and keeps the public SIMUB activation ID. Replacement is refused after an OTP has been received.", "security": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "activationId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Activation containing the replacement number." }, "404": { "description": "Activation not found." }, "409": { "description": "Another lifecycle operation is running." }, "422": { "description": "The activation cannot be replaced." }, "502": { "description": "HeroSMS is temporarily unavailable." } } } }, "/api/v1/activations/{activationId}/reactivate/options": { "get": { "tags": [ "Activations v1" ], "summary": "Get reactivation options", "description": "Returns the durations and final SIMUB prices available for reactivating a completed HeroSMS activation.", "security": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "activationId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Reactivation options.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "options" ], "properties": { "options": { "type": "array", "items": { "type": "object", "properties": { "duration": { "type": "object", "properties": { "value": { "type": "integer" }, "unit": { "type": "string", "enum": [ "minute", "hour" ] } } }, "price": { "type": "number", "format": "float" } } } } } } } } } } }, "404": { "description": "Activation not found." }, "422": { "description": "The activation is not eligible." } } } }, "/api/v1/activations/{activationId}/reactivate": { "post": { "tags": [ "Activations v1" ], "summary": "Reactivate a completed number", "description": "Reserves the selected amount on the SIMUB balance and returns a new local activation for the same number.", "security": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "activationId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "duration": { "type": "integer", "minimum": 1, "maximum": 8760, "description": "Duration in hours returned by the options endpoint. The first available hour option is used when omitted." } } } } } }, "responses": { "200": { "description": "New active SIMUB activation." }, "402": { "description": "Insufficient SIMUB balance." }, "404": { "description": "Activation not found." }, "409": { "description": "Another lifecycle operation is unresolved." }, "422": { "description": "The duration or activation is not eligible." }, "503": { "description": "The provider result is ambiguous and must not be retried before reconciliation." } } } }, "/api/v1/activations/{activationId}/prolong/options": { "get": { "tags": [ "Activations v1" ], "summary": "Get prolongation options", "description": "Returns available duration extensions with final SIMUB prices.", "security": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "activationId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Prolongation options in the same shape as the reactivation options response." }, "404": { "description": "Activation not found." }, "425": { "description": "The activation cannot be prolonged yet." }, "422": { "description": "The activation is not eligible." } } } }, "/api/v1/activations/{activationId}/prolong": { "post": { "tags": [ "Activations v1" ], "summary": "Prolong an activation rental", "description": "Charges the quoted SIMUB price and extends the existing activation.", "security": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "activationId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "duration" ], "properties": { "duration": { "type": "integer", "minimum": 1, "maximum": 8760, "description": "Duration in hours returned by the options endpoint." } } } } } }, "responses": { "200": { "description": "Extended activation." }, "402": { "description": "Insufficient SIMUB balance." }, "404": { "description": "Activation not found." }, "409": { "description": "Another lifecycle operation is unresolved." }, "422": { "description": "The requested duration is unavailable." }, "425": { "description": "The activation cannot be prolonged yet." }, "503": { "description": "The provider result is ambiguous and must not be retried before reconciliation." } } } }, "/api/v1/activations/{activationId}/prolong/history": { "get": { "tags": [ "Activations v1" ], "summary": "Get prolongation history", "security": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "activationId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Extension durations, final client prices and creation dates." }, "404": { "description": "Activation not found." } } } }, "/api/v1/activations/favorites/services/{service}/countries/{country}": { "put": { "tags": [ "Activation Favorites v1" ], "summary": "Add or edit a favorite", "security": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "service", "in": "path", "required": true, "schema": { "type": "string", "example": "tg" } }, { "name": "country", "in": "path", "required": true, "schema": { "type": "integer", "example": 0 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "operator" ], "properties": { "operator": { "type": "string", "default": "any" } } } } } }, "responses": { "200": { "description": "Saved favorite." }, "404": { "description": "Service or country not found." }, "422": { "description": "Invalid favorite or the 30-favorite limit was reached." } } }, "delete": { "tags": [ "Activation Favorites v1" ], "summary": "Remove a favorite", "security": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "service", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "country", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Favorite removed or already absent." }, "422": { "description": "Invalid service or country identifier." } } } }, "/api/v1/activations/{activationId}/otp": { "get": { "tags": [ "Activation OTP v1" ], "summary": "Get all received OTP messages", "security": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "activationId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OTP list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/V1Otp" } } } } } } }, "404": { "description": "Activation not found." } } } }, "/api/v1/activations/{activationId}/otp/last": { "get": { "tags": [ "Activation OTP v1" ], "summary": "Get the latest received OTP", "security": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "activationId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Latest OTP.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/V1Otp" } } } } } }, "404": { "description": "Activation or OTP not found." } } } }, "/api/v1/classifiers/operators": { "get": { "tags": [ "Classifiers v1" ], "summary": "Get HeroSMS operators available for a country", "security": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "country", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 0, "maximum": 999 } } ], "responses": { "200": { "description": "Sorted operator codes." }, "401": { "description": "Invalid API key." } } } }, "/api/v1/classifiers/activations/custom-durations": { "get": { "tags": [ "Classifiers v1" ], "summary": "Get custom activation durations", "responses": { "200": { "description": "Service and country duration overrides. An empty object means the standard duration applies." } } } } } }