{"openapi":"3.0.3","info":{"title":"Tiger SMS Public API","version":"1.0.0","description":"Single dispatcher transport: `GET|POST /stubs/handler_api.php?action=<name>&api_key=<key>&...`. All parameters (GET or POST) are read the same way — send them as the query string either way.\n\nAuth: `api_key` query parameter, a 32-character alphanumeric token from your account. Missing/invalid key → plain-text `BAD_KEY`, HTTP 401, before any action code runs (checked by shared middleware for every action below).\n\nUnknown `action`, or any unexpected server error inside a known action → plain-text `BAD_ACTION`, HTTP 200 (dispatcher never lets an exception escape as a 5xx).\n\nCurrency is USD-only across every new response: ISO numeric `840`, no RUB, no converters. Money values are 4-decimal HALF_UP internally; fields that are historically strings in this API family stay strings (trailing zeros trimmed where the source formatter does so — see per-field notes).\n\nNew behaviour ships behind `api_*` Setting flags, default OFF. While a flag is OFF, that action/parameter/error behaves exactly as if it did not exist (existing actions: byte-identical old response; brand-new actions: plain-text `BAD_ACTION`, HTTP 200, same as any unrecognized action). Flags referenced below are informational — this document describes the TARGET behaviour once a flag is flipped ON.\n\nRate limiting for the heaviest read/write actions (`getNumber`, `getNumberImsi`, `getNumberV2`, `getPricesV3`) is enforced both in the application and, for actions covered by the edge configuration, before PHP. An edge 429 is always plain-text `Too Many Requests` with a `Retry-After` header, regardless of the JSON-envelope flag.\n\nProvider purchase/cost price and real vendor names are never exposed by any action in this document — only the public numeric `provider_id` and SALE price ever appear (getProviders, getPricesV3).\n\nComma-separated lists (our differentiator vs. competitors): `providerIds`/`exceptProviderIds` on the getNumber family accept them unconditionally (pre-existing). Top-level `service`/`country` accept them only on the price-lookup methods (getPrices, getFreePrices, getPricesV2, getPricesV3) and only under flag `api_prices_comma_list_enabled` — see each method's parameters for the exact flag.\n\nThe api_key in every example/parameter default in this document is the placeholder `YOUR_API_KEY` — it never contains a real key."},"servers":[{"url":"https://api.tiger-sms.com","description":"Current tenant API host"}],"tags":[{"name":"v1","description":"V1 response family"},{"name":"v2","description":"V2 response family"},{"name":"v3","description":"V3 response family"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"query","name":"api_key","description":"32-character alphanumeric key from your account. Always use the placeholder YOUR_API_KEY in shared docs/collections — never a real key."}},"schemas":{"ErrorEnvelope":{"type":"object","description":"Shared JSON error envelope for new/V2/V3 actions (docs/api-rebuild/PROMPT.md §7). Legacy plain-text actions and the legacy internal {\"error\":...} shape (getServiceVariationsPrices/getMinFrontPrice/getActivationsInfoByPeriod) do NOT use this.","properties":{"title":{"type":"string","example":"NO_NUMBERS"},"details":{"type":"string","example":"No numbers available for the requested service and country"},"info":{"type":"object","nullable":true}},"required":["title","details"]}}},"paths":{"/stubs/handler_api.php?action=getActiveActivations":{"get":{"operationId":"getActiveActivations","summary":"List of currently active activations for the key owner.","description":"List of currently active activations for the key owner.\n\nGated by flag `api_active_activations_enabled` (currently ON in this environment). While OFF, this action returns plain-text `BAD_ACTION`, HTTP 200, byte-identical to an unknown action.\n\nNever errors on unexpected failure (same philosophy as getServicesList/getCountries) — degrades to an empty `data: []` list with status still \"success\".\n\nactivationStatus values: 1=WAIT_CODE, 2=WAIT_ACCEPTING, 3=WAIT_NEXT_SMS, 6=OK, 7=REFUND, 8=CANCEL — this numbering is specific to us and may differ from other SMS APIs you have used.","tags":["v1"],"x-status":"new","x-feature-flag":"api_active_activations_enabled","parameters":[{"name":"action","in":"query","required":true,"schema":{"type":"string","enum":["getActiveActivations"]},"example":"getActiveActivations","description":"Fixed for this operation."},{"name":"api_key","in":"query","required":true,"schema":{"type":"string"},"example":"YOUR_API_KEY","description":"Your account API key. Placeholder shown — never a real key."},{"name":"start","in":"query","required":false,"schema":{"type":"integer","example":0},"description":"Offset for pagination."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","example":50},"description":"Page size, capped at 100 (non-positive/non-numeric falls back to the default 50)."}],"responses":{"200":{"description":"success: Scoped to the API key owner. \"Active\" means not cancelled or refunded, and still within its window to receive an SMS. activationCost is the price you were charged, never your cost, and provider id/name are never included.","content":{"application/json":{"schema":{"type":"object"},"examples":{"success":{"summary":"success","description":"Scoped to the API key owner. \"Active\" means not cancelled or refunded, and still within its window to receive an SMS. activationCost is the price you were charged, never your cost, and provider id/name are never included.","value":{"status":"success","data":[{"activationId":"557860099","serviceCode":"tg","phoneNumber":"18734721259","activationCost":0.1453,"activationStatus":"6","smsCode":"","smsText":"","activationTime":"2026-07-02T18:09:54+00:00","countryCode":6,"countryName":"United States","canGetAnotherSms":true,"currency":840}]}}}}}},"401":{"description":"BAD_KEY: Missing/invalid api_key. Checked by shared middleware before any action code runs. Becomes the {\"title\":\"BAD_KEY\",...} JSON envelope only under flag api_json_envelope_enabled AND format=json/*V2/*V3 intent.","content":{"text/plain":{"schema":{"type":"string"},"examples":{"BAD_KEY":{"summary":"BAD_KEY","description":"Missing/invalid api_key. Checked by shared middleware before any action code runs. Becomes the {\"title\":\"BAD_KEY\",...} JSON envelope only under flag api_json_envelope_enabled AND format=json/*V2/*V3 intent.","value":"BAD_KEY"}}}}}}},"post":{"operationId":"getActiveActivations","summary":"List of currently active activations for the key owner.","description":"List of currently active activations for the key owner.\n\nGated by flag `api_active_activations_enabled` (currently ON in this environment). While OFF, this action returns plain-text `BAD_ACTION`, HTTP 200, byte-identical to an unknown action.\n\nNever errors on unexpected failure (same philosophy as getServicesList/getCountries) — degrades to an empty `data: []` list with status still \"success\".\n\nactivationStatus values: 1=WAIT_CODE, 2=WAIT_ACCEPTING, 3=WAIT_NEXT_SMS, 6=OK, 7=REFUND, 8=CANCEL — this numbering is specific to us and may differ from other SMS APIs you have used.","tags":["v1"],"x-status":"new","x-feature-flag":"api_active_activations_enabled","parameters":[{"name":"action","in":"query","required":true,"schema":{"type":"string","enum":["getActiveActivations"]},"example":"getActiveActivations","description":"Fixed for this operation."},{"name":"api_key","in":"query","required":true,"schema":{"type":"string"},"example":"YOUR_API_KEY","description":"Your account API key. Placeholder shown — never a real key."},{"name":"start","in":"query","required":false,"schema":{"type":"integer","example":0},"description":"Offset for pagination."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","example":50},"description":"Page size, capped at 100 (non-positive/non-numeric falls back to the default 50)."}],"responses":{"200":{"description":"success: Scoped to the API key owner. \"Active\" means not cancelled or refunded, and still within its window to receive an SMS. activationCost is the price you were charged, never your cost, and provider id/name are never included.","content":{"application/json":{"schema":{"type":"object"},"examples":{"success":{"summary":"success","description":"Scoped to the API key owner. \"Active\" means not cancelled or refunded, and still within its window to receive an SMS. activationCost is the price you were charged, never your cost, and provider id/name are never included.","value":{"status":"success","data":[{"activationId":"557860099","serviceCode":"tg","phoneNumber":"18734721259","activationCost":0.1453,"activationStatus":"6","smsCode":"","smsText":"","activationTime":"2026-07-02T18:09:54+00:00","countryCode":6,"countryName":"United States","canGetAnotherSms":true,"currency":840}]}}}}}},"401":{"description":"BAD_KEY: Missing/invalid api_key. Checked by shared middleware before any action code runs. Becomes the {\"title\":\"BAD_KEY\",...} JSON envelope only under flag api_json_envelope_enabled AND format=json/*V2/*V3 intent.","content":{"text/plain":{"schema":{"type":"string"},"examples":{"BAD_KEY":{"summary":"BAD_KEY","description":"Missing/invalid api_key. Checked by shared middleware before any action code runs. Becomes the {\"title\":\"BAD_KEY\",...} JSON envelope only under flag api_json_envelope_enabled AND format=json/*V2/*V3 intent.","value":"BAD_KEY"}}}}}}}},"/stubs/handler_api.php?action=getBalance":{"get":{"operationId":"getBalance","summary":"Current account balance.","description":"Current account balance.\n\nBAD_KEY (HTTP 401) is returned before this method runs at all, whenever the API key is missing or invalid — this applies to every method, not just this one.","tags":["v1"],"x-status":"existing","parameters":[{"name":"action","in":"query","required":true,"schema":{"type":"string","enum":["getBalance"]},"example":"getBalance","description":"Fixed for this operation."},{"name":"api_key","in":"query","required":true,"schema":{"type":"string"},"example":"YOUR_API_KEY","description":"Your account API key. Placeholder shown — never a real key."},{"name":"format","in":"query","required":false,"schema":{"type":"string","example":"json"},"description":"Pass 'json' to get a JSON body instead of the plain-text token."}],"responses":{"200":{"description":"success: Default plain-text response, byte-for-byte unchanged. | success_1: format=json response. balance is a 4-decimal string (no trailing-zero trim); currency is always 840.","content":{"text/plain":{"schema":{"type":"string"},"examples":{"success":{"summary":"success","description":"Default plain-text response, byte-for-byte unchanged.","value":"ACCESS_BALANCE:12.3400"},"success_1":{"summary":"success_1","description":"format=json response. balance is a 4-decimal string (no trailing-zero trim); currency is always 840.","value":{"balance":"12.3400","currency":840}}}}}},"401":{"description":"BAD_KEY: Missing/invalid api_key. Checked by shared middleware before any action code runs. Becomes the {\"title\":\"BAD_KEY\",...} JSON envelope only under flag api_json_envelope_enabled AND format=json/*V2/*V3 intent.","content":{"text/plain":{"schema":{"type":"string"},"examples":{"BAD_KEY":{"summary":"BAD_KEY","description":"Missing/invalid api_key. Checked by shared middleware before any action code runs. Becomes the {\"title\":\"BAD_KEY\",...} JSON envelope only under flag api_json_envelope_enabled AND format=json/*V2/*V3 intent.","value":"BAD_KEY"}}}}}}},"post":{"operationId":"getBalance","summary":"Current account balance.","description":"Current account balance.\n\nBAD_KEY (HTTP 401) is returned before this method runs at all, whenever the API key is missing or invalid — this applies to every method, not just this one.","tags":["v1"],"x-status":"existing","parameters":[{"name":"action","in":"query","required":true,"schema":{"type":"string","enum":["getBalance"]},"example":"getBalance","description":"Fixed for this operation."},{"name":"api_key","in":"query","required":true,"schema":{"type":"string"},"example":"YOUR_API_KEY","description":"Your account API key. Placeholder shown — never a real key."},{"name":"format","in":"query","required":false,"schema":{"type":"string","example":"json"},"description":"Pass 'json' to get a JSON body instead of the plain-text token."}],"responses":{"200":{"description":"success: Default plain-text response, byte-for-byte unchanged. | success_1: format=json response. balance is a 4-decimal string (no trailing-zero trim); currency is always 840.","content":{"text/plain":{"schema":{"type":"string"},"examples":{"success":{"summary":"success","description":"Default plain-text response, byte-for-byte unchanged.","value":"ACCESS_BALANCE:12.3400"},"success_1":{"summary":"success_1","description":"format=json response. balance is a 4-decimal string (no trailing-zero trim); currency is always 840.","value":{"balance":"12.3400","currency":840}}}}}},"401":{"description":"BAD_KEY: Missing/invalid api_key. Checked by shared middleware before any action code runs. Becomes the {\"title\":\"BAD_KEY\",...} JSON envelope only under flag api_json_envelope_enabled AND format=json/*V2/*V3 intent.","content":{"text/plain":{"schema":{"type":"string"},"examples":{"BAD_KEY":{"summary":"BAD_KEY","description":"Missing/invalid api_key. Checked by shared middleware before any action code runs. Becomes the {\"title\":\"BAD_KEY\",...} JSON envelope only under flag api_json_envelope_enabled AND format=json/*V2/*V3 intent.","value":"BAD_KEY"}}}}}}}},"/stubs/handler_api.php?action=getCountries":{"get":{"operationId":"getCountries","summary":"Catalog of countries (id + localized names).","description":"Catalog of countries (id + localized names).\n\nGated by flag `api_catalog_enabled` (currently ON in this environment). While OFF, this action returns plain-text `BAD_ACTION`, HTTP 200, byte-identical to an unknown action.\n\nDegrades to an empty JSON array `[]` on unexpected failure rather than an error response.","tags":["v1"],"x-status":"new","x-feature-flag":"api_catalog_enabled","parameters":[{"name":"action","in":"query","required":true,"schema":{"type":"string","enum":["getCountries"]},"example":"getCountries","description":"Fixed for this operation."},{"name":"api_key","in":"query","required":true,"schema":{"type":"string"},"example":"YOUR_API_KEY","description":"Your account API key. Placeholder shown — never a real key."}],"responses":{"200":{"description":"success: id is the external sms_activate numeric code, not our internal country id. visible and retry are always 1 — no per-country override exists yet.","content":{"application/json":{"schema":{"type":"object"},"examples":{"success":{"summary":"success","description":"id is the external sms_activate numeric code, not our internal country id. visible and retry are always 1 — no per-country override exists yet.","value":[{"id":19,"rus":"Бразилия","eng":"Brazil","chn":"巴西","visible":1,"retry":1}]}}}}},"401":{"description":"BAD_KEY: Missing/invalid api_key. Checked by shared middleware before any action code runs. Becomes the {\"title\":\"BAD_KEY\",...} JSON envelope only under flag api_json_envelope_enabled AND format=json/*V2/*V3 intent.","content":{"text/plain":{"schema":{"type":"string"},"examples":{"BAD_KEY":{"summary":"BAD_KEY","description":"Missing/invalid api_key. Checked by shared middleware before any action code runs. Becomes the {\"title\":\"BAD_KEY\",...} JSON envelope only under flag api_json_envelope_enabled AND format=json/*V2/*V3 intent.","value":"BAD_KEY"}}}}}}},"post":{"operationId":"getCountries","summary":"Catalog of countries (id + localized names).","description":"Catalog of countries (id + localized names).\n\nGated by flag `api_catalog_enabled` (currently ON in this environment). While OFF, this action returns plain-text `BAD_ACTION`, HTTP 200, byte-identical to an unknown action.\n\nDegrades to an empty JSON array `[]` on unexpected failure rather than an error response.","tags":["v1"],"x-status":"new","x-feature-flag":"api_catalog_enabled","parameters":[{"name":"action","in":"query","required":true,"schema":{"type":"string","enum":["getCountries"]},"example":"getCountries","description":"Fixed for this operation."},{"name":"api_key","in":"query","required":true,"schema":{"type":"string"},"example":"YOUR_API_KEY","description":"Your account API key. Placeholder shown — never a real key."}],"responses":{"200":{"description":"success: id is the external sms_activate numeric code, not our internal country id. visible and retry are always 1 — no per-country override exists yet.","content":{"application/json":{"schema":{"type":"object"},"examples":{"success":{"summary":"success","description":"id is the external sms_activate numeric code, not our internal country id. visible and retry are always 1 — no per-country override exists yet.","value":[{"id":19,"rus":"Бразилия","eng":"Brazil","chn":"巴西","visible":1,"retry":1}]}}}}},"401":{"description":"BAD_KEY: Missing/invalid api_key. Checked by shared middleware before any action code runs. Becomes the {\"title\":\"BAD_KEY\",...} JSON envelope only under flag api_json_envelope_enabled AND format=json/*V2/*V3 intent.","content":{"text/plain":{"schema":{"type":"string"},"examples":{"BAD_KEY":{"summary":"BAD_KEY","description":"Missing/invalid api_key. Checked by shared middleware before any action code runs. Becomes the {\"title\":\"BAD_KEY\",...} JSON envelope only under flag api_json_envelope_enabled AND format=json/*V2/*V3 intent.","value":"BAD_KEY"}}}}}}}},"/stubs/handler_api.php?action=getFreePrices":{"get":{"operationId":"getFreePrices","summary":"Price-bucket detail map (price => count, multi-SMS flag) by country/service.","description":"Price-bucket detail map (price => count, multi-SMS flag) by country/service.","tags":["v2"],"x-status":"existing","parameters":[{"name":"action","in":"query","required":true,"schema":{"type":"string","enum":["getFreePrices"]},"example":"getFreePrices","description":"Fixed for this operation."},{"name":"api_key","in":"query","required":true,"schema":{"type":"string"},"example":"YOUR_API_KEY","description":"Your account API key. Placeholder shown — never a real key."},{"name":"service","in":"query","required":false,"schema":{"type":"string","example":"tg"},"description":"Filter to one service code. Comma-separated lists (e.g. 'tg,go') are coming soon. [flag: api_prices_comma_list_enabled]"},{"name":"country","in":"query","required":false,"schema":{"type":"integer","example":6},"description":"Filter to one numeric country code. Comma-separated lists (e.g. '6,33') are coming soon. [flag: api_prices_comma_list_enabled]"}],"responses":{"200":{"description":"success: Map keyed by price (a USD string, 4 decimal places) to numbers_count, plus a parallel has_multi map. Returns an empty object when price-bucket data isn't available for this account. | BAD_SERVICE: service is not a string, or the service code is unknown / removed. | BAD_COUNTRY: country is not an integer, or the country code is unknown / removed. | BAD_VALUES: Generic validation exception fallback.","content":{"application/json":{"schema":{"type":"object"},"examples":{"success":{"summary":"success","description":"Map keyed by price (a USD string, 4 decimal places) to numbers_count, plus a parallel has_multi map. Returns an empty object when price-bucket data isn't available for this account.","value":{"6":{"tg":{"prices":{"0.1491":100,"0.1650":40},"has_multi":{"0.1491":false,"0.1650":true}}}}},"BAD_SERVICE":{"summary":"BAD_SERVICE","description":"service is not a string, or the service code is unknown / removed.","value":"BAD_SERVICE"},"BAD_COUNTRY":{"summary":"BAD_COUNTRY","description":"country is not an integer, or the country code is unknown / removed.","value":"BAD_COUNTRY"},"BAD_VALUES":{"summary":"BAD_VALUES","description":"Generic validation exception fallback.","value":"BAD_VALUES"}}}}},"401":{"description":"BAD_KEY: Missing/invalid api_key. Checked by shared middleware before any action code runs. Becomes the {\"title\":\"BAD_KEY\",...} JSON envelope only under flag api_json_envelope_enabled AND format=json/*V2/*V3 intent.","content":{"text/plain":{"schema":{"type":"string"},"examples":{"BAD_KEY":{"summary":"BAD_KEY","description":"Missing/invalid api_key. Checked by shared middleware before any action code runs. Becomes the {\"title\":\"BAD_KEY\",...} JSON envelope only under flag api_json_envelope_enabled AND format=json/*V2/*V3 intent.","value":"BAD_KEY"}}}}}}},"post":{"operationId":"getFreePrices","summary":"Price-bucket detail map (price => count, multi-SMS flag) by country/service.","description":"Price-bucket detail map (price => count, multi-SMS flag) by country/service.","tags":["v2"],"x-status":"existing","parameters":[{"name":"action","in":"query","required":true,"schema":{"type":"string","enum":["getFreePrices"]},"example":"getFreePrices","description":"Fixed for this operation."},{"name":"api_key","in":"query","required":true,"schema":{"type":"string"},"example":"YOUR_API_KEY","description":"Your account API key. Placeholder shown — never a real key."},{"name":"service","in":"query","required":false,"schema":{"type":"string","example":"tg"},"description":"Filter to one service code. Comma-separated lists (e.g. 'tg,go') are coming soon. [flag: api_prices_comma_list_enabled]"},{"name":"country","in":"query","required":false,"schema":{"type":"integer","example":6},"description":"Filter to one numeric country code. Comma-separated lists (e.g. '6,33') are coming soon. [flag: api_prices_comma_list_enabled]"}],"responses":{"200":{"description":"success: Map keyed by price (a USD string, 4 decimal places) to numbers_count, plus a parallel has_multi map. Returns an empty object when price-bucket data isn't available for this account. | BAD_SERVICE: service is not a string, or the service code is unknown / removed. | BAD_COUNTRY: country is not an integer, or the country code is unknown / removed. | BAD_VALUES: Generic validation exception fallback.","content":{"application/json":{"schema":{"type":"object"},"examples":{"success":{"summary":"success","description":"Map keyed by price (a USD string, 4 decimal places) to numbers_count, plus a parallel has_multi map. Returns an empty object when price-bucket data isn't available for this account.","value":{"6":{"tg":{"prices":{"0.1491":100,"0.1650":40},"has_multi":{"0.1491":false,"0.1650":true}}}}},"BAD_SERVICE":{"summary":"BAD_SERVICE","description":"service is not a string, or the service code is unknown / removed.","value":"BAD_SERVICE"},"BAD_COUNTRY":{"summary":"BAD_COUNTRY","description":"country is not an integer, or the country code is unknown / removed.","value":"BAD_COUNTRY"},"BAD_VALUES":{"summary":"BAD_VALUES","description":"Generic validation exception fallback.","value":"BAD_VALUES"}}}}},"401":{"description":"BAD_KEY: Missing/invalid api_key. Checked by shared middleware before any action code runs. Becomes the {\"title\":\"BAD_KEY\",...} JSON envelope only under flag api_json_envelope_enabled AND format=json/*V2/*V3 intent.","content":{"text/plain":{"schema":{"type":"string"},"examples":{"BAD_KEY":{"summary":"BAD_KEY","description":"Missing/invalid api_key. Checked by shared middleware before any action code runs. Becomes the {\"title\":\"BAD_KEY\",...} JSON envelope only under flag api_json_envelope_enabled AND format=json/*V2/*V3 intent.","value":"BAD_KEY"}}}}}}}},"/stubs/handler_api.php?action=getNumber":{"get":{"operationId":"getNumber","summary":"Purchase a phone number for a service/country.","description":"Purchase a phone number for a service/country.\n\nAccepted but currently ignored (no validation rule, silently dropped, no error): operator, phoneException, minPrice.\n\nAutomatic country detection (e.g. `country=any`) is not supported: `country` must be a numeric country code — a non-numeric or unknown country returns BAD_COUNTRY.\n\nComma-separated lists on this method are supported for providerIds/exceptProviderIds only. Top-level `service`/`country` do not accept comma lists here — that capability is coming soon on the price-lookup methods (getPrices/getFreePrices/getPricesV2/getPricesV3) only.\n\ngetNumberTest behaves exactly like getNumber, but is the documented way to explicitly pass activationType/testParams.","tags":["v1"],"x-status":"existing","parameters":[{"name":"action","in":"query","required":true,"schema":{"type":"string","enum":["getNumber"]},"example":"getNumber","description":"Fixed for this operation."},{"name":"api_key","in":"query","required":true,"schema":{"type":"string"},"example":"YOUR_API_KEY","description":"Your account API key. Placeholder shown — never a real key."},{"name":"service","in":"query","required":true,"schema":{"type":"string","example":"tg"},"description":"sms_activate-style service code."},{"name":"country","in":"query","required":true,"schema":{"type":"integer","example":6},"description":"Numeric country code (sms_activate_code)."},{"name":"multiple","in":"query","required":false,"schema":{"type":"boolean","example":false},"description":"Require a variation that allows multiple SMS to the same number."},{"name":"maxPrice","in":"query","required":false,"schema":{"type":"number","example":0.2},"description":"Ceiling price in USD, 4dp. <=0/non-numeric is treated as \"not set\" (default sellable ceiling), never as \"unlimited\"."},{"name":"providerIds","in":"query","required":false,"schema":{"type":"string","example":"235,240"},"description":"Comma-separated provider ids to restrict the purchase to (our differentiator, pre-existing)."},{"name":"exceptProviderIds","in":"query","required":false,"schema":{"type":"string","example":"99"},"description":"Comma-separated provider ids to exclude."},{"name":"ref","in":"query","required":false,"schema":{"type":"string"},"description":"Referral id, falls back to the `ref` cookie."},{"name":"activationType","in":"query","required":false,"schema":{"type":"string","example":"SMS"},"description":"One of SMS, CALL_FLASH, CALL_VOICE, CALL_INTERACTIVE, RENT_SMS. Unknown value silently falls back to SMS. RENT_SMS is accepted but rental is not a supported product yet — do not rely on it."},{"name":"fixedPrice","in":"query","required":false,"schema":{"type":"string","example":"true"},"description":"Literal 'true'/'false'. Requires maxPrice. When 'true', the charge is locked to exactly maxPrice instead of the usual hold-then-settle-at-real-price flow. [flag: api_fixed_price_enabled]"}],"responses":{"200":{"description":"success: Activation id followed by the purchased phone number. | NO_NUMBERS: No number available for the requested service/country/filters (includes the case where a locked/removed variation is hit). | NO_BALANCE: Insufficient balance for the pre-check price. | BAD_SERVICE: Unknown service, or the service/country pair is removed from the catalog, or min_user_topup gate not met. | BAD_COUNTRY: Unknown country code (not in the catalog), or country is not a numeric code. | BAD_VALUES: Generic validation failure fallback (rare — most validated fields have a dedicated message below). | BAD_MULTIPLE: multiple is not a valid boolean value. | BAD_MAX_PRICE: maxPrice is not numeric. | BAD_PROVIDER_IDS: providerIds failed validation. A more specific message for this field is coming soon — until then, a generic message is returned instead (e.g. \"The provider ids field must be a string.\"). | BAD_EXCEPT_PROVIDER_IDS: exceptProviderIds failed validation. A more specific message for this field is coming soon — until then, a generic message is returned instead. | NO_PROVIDERS: None of the requested providerIds (minus exceptProviderIds) currently offer this service/country pair at all. Distinct from NO_NUMBERS (offers exist but are out of stock) and WRONG_MAX_PRICE (offers exist but cost more than maxPrice). | BAD_ACTIVATION_TYPE: activationType failed validation. A more specific message for this field is coming soon — until then, a generic message is returned instead. | BAD_FIXED_PRICE: fixedPrice is present but is not the literal string 'true' or 'false'.","content":{"text/plain":{"schema":{"type":"string"},"examples":{"success":{"summary":"success","description":"Activation id followed by the purchased phone number.","value":"ACCESS_NUMBER:557860099:18734721259"},"NO_NUMBERS":{"summary":"NO_NUMBERS","description":"No number available for the requested service/country/filters (includes the case where a locked/removed variation is hit).","value":"NO_NUMBERS"},"NO_BALANCE":{"summary":"NO_BALANCE","description":"Insufficient balance for the pre-check price.","value":"NO_BALANCE"},"BAD_SERVICE":{"summary":"BAD_SERVICE","description":"Unknown service, or the service/country pair is removed from the catalog, or min_user_topup gate not met.","value":"BAD_SERVICE"},"BAD_COUNTRY":{"summary":"BAD_COUNTRY","description":"Unknown country code (not in the catalog), or country is not a numeric code.","value":"BAD_COUNTRY"},"BAD_VALUES":{"summary":"BAD_VALUES","description":"Generic validation failure fallback (rare — most validated fields have a dedicated message below).","value":"BAD_VALUES"},"BAD_MULTIPLE":{"summary":"BAD_MULTIPLE","description":"multiple is not a valid boolean value.","value":"BAD_MULTIPLE"},"BAD_MAX_PRICE":{"summary":"BAD_MAX_PRICE","description":"maxPrice is not numeric.","value":"BAD_MAX_PRICE"},"BAD_PROVIDER_IDS":{"summary":"BAD_PROVIDER_IDS","description":"providerIds failed validation. A more specific message for this field is coming soon — until then, a generic message is returned instead (e.g. \"The provider ids field must be a string.\").","value":"BAD_PROVIDER_IDS","x-feature-flag":"api_validation_messages_enabled"},"BAD_EXCEPT_PROVIDER_IDS":{"summary":"BAD_EXCEPT_PROVIDER_IDS","description":"exceptProviderIds failed validation. A more specific message for this field is coming soon — until then, a generic message is returned instead.","value":"BAD_EXCEPT_PROVIDER_IDS","x-feature-flag":"api_validation_messages_enabled"},"NO_PROVIDERS":{"summary":"NO_PROVIDERS","description":"None of the requested providerIds (minus exceptProviderIds) currently offer this service/country pair at all. Distinct from NO_NUMBERS (offers exist but are out of stock) and WRONG_MAX_PRICE (offers exist but cost more than maxPrice).","value":"NO_PROVIDERS","x-feature-flag":"api_no_providers_enabled"},"BAD_ACTIVATION_TYPE":{"summary":"BAD_ACTIVATION_TYPE","description":"activationType failed validation. A more specific message for this field is coming soon — until then, a generic message is returned instead.","value":"BAD_ACTIVATION_TYPE","x-feature-flag":"api_validation_messages_enabled"},"BAD_FIXED_PRICE":{"summary":"BAD_FIXED_PRICE","description":"fixedPrice is present but is not the literal string 'true' or 'false'.","value":"BAD_FIXED_PRICE"}}}}},"400":{"description":"WRONG_MAX_PRICE: Returned when maxPrice is below the minimum sellable price for the pair (or for the selected providerIds); the number after the colon is that minimum. Not yet available — this case currently returns NO_NUMBERS instead.","content":{"text/plain":{"schema":{"type":"string"},"examples":{"WRONG_MAX_PRICE":{"summary":"WRONG_MAX_PRICE","description":"Returned when maxPrice is below the minimum sellable price for the pair (or for the selected providerIds); the number after the colon is that minimum. Not yet available — this case currently returns NO_NUMBERS instead.","value":"WRONG_MAX_PRICE:0.1453","x-feature-flag":"api_wrong_max_price_enabled"}}}}},"401":{"description":"BAD_KEY: Missing/invalid api_key. Checked by shared middleware before any action code runs. Becomes the {\"title\":\"BAD_KEY\",...} JSON envelope only under flag api_json_envelope_enabled AND format=json/*V2/*V3 intent.","content":{"text/plain":{"schema":{"type":"string"},"examples":{"BAD_KEY":{"summary":"BAD_KEY","description":"Missing/invalid api_key. Checked by shared middleware before any action code runs. Becomes the {\"title\":\"BAD_KEY\",...} JSON envelope only under flag api_json_envelope_enabled AND format=json/*V2/*V3 intent.","value":"BAD_KEY"}}}}},"429":{"description":"Too Many Requests: Rate limited before your request reaches our application — plain text, not part of a JSON envelope. Includes a Retry-After header.","content":{"text/plain":{"schema":{"type":"string"},"examples":{"Too Many Requests":{"summary":"Too Many Requests","description":"Rate limited before your request reaches our application — plain text, not part of a JSON envelope. Includes a Retry-After header.","value":"Too Many Requests"}}}}}}},"post":{"operationId":"getNumber","summary":"Purchase a phone number for a service/country.","description":"Purchase a phone number for a service/country.\n\nAccepted but currently ignored (no validation rule, silently dropped, no error): operator, phoneException, minPrice.\n\nAutomatic country detection (e.g. `country=any`) is not supported: `country` must be a numeric country code — a non-numeric or unknown country returns BAD_COUNTRY.\n\nComma-separated lists on this method are supported for providerIds/exceptProviderIds only. Top-level `service`/`country` do not accept comma lists here — that capability is coming soon on the price-lookup methods (getPrices/getFreePrices/getPricesV2/getPricesV3) only.\n\ngetNumberTest behaves exactly like getNumber, but is the documented way to explicitly pass activationType/testParams.","tags":["v1"],"x-status":"existing","parameters":[{"name":"action","in":"query","required":true,"schema":{"type":"string","enum":["getNumber"]},"example":"getNumber","description":"Fixed for this operation."},{"name":"api_key","in":"query","required":true,"schema":{"type":"string"},"example":"YOUR_API_KEY","description":"Your account API key. Placeholder shown — never a real key."},{"name":"service","in":"query","required":true,"schema":{"type":"string","example":"tg"},"description":"sms_activate-style service code."},{"name":"country","in":"query","required":true,"schema":{"type":"integer","example":6},"description":"Numeric country code (sms_activate_code)."},{"name":"multiple","in":"query","required":false,"schema":{"type":"boolean","example":false},"description":"Require a variation that allows multiple SMS to the same number."},{"name":"maxPrice","in":"query","required":false,"schema":{"type":"number","example":0.2},"description":"Ceiling price in USD, 4dp. <=0/non-numeric is treated as \"not set\" (default sellable ceiling), never as \"unlimited\"."},{"name":"providerIds","in":"query","required":false,"schema":{"type":"string","example":"235,240"},"description":"Comma-separated provider ids to restrict the purchase to (our differentiator, pre-existing)."},{"name":"exceptProviderIds","in":"query","required":false,"schema":{"type":"string","example":"99"},"description":"Comma-separated provider ids to exclude."},{"name":"ref","in":"query","required":false,"schema":{"type":"string"},"description":"Referral id, falls back to the `ref` cookie."},{"name":"activationType","in":"query","required":false,"schema":{"type":"string","example":"SMS"},"description":"One of SMS, CALL_FLASH, CALL_VOICE, CALL_INTERACTIVE, RENT_SMS. Unknown value silently falls back to SMS. RENT_SMS is accepted but rental is not a supported product yet — do not rely on it."},{"name":"fixedPrice","in":"query","required":false,"schema":{"type":"string","example":"true"},"description":"Literal 'true'/'false'. Requires maxPrice. When 'true', the charge is locked to exactly maxPrice instead of the usual hold-then-settle-at-real-price flow. [flag: api_fixed_price_enabled]"}],"responses":{"200":{"description":"success: Activation id followed by the purchased phone number. | NO_NUMBERS: No number available for the requested service/country/filters (includes the case where a locked/removed variation is hit). | NO_BALANCE: Insufficient balance for the pre-check price. | BAD_SERVICE: Unknown service, or the service/country pair is removed from the catalog, or min_user_topup gate not met. | BAD_COUNTRY: Unknown country code (not in the catalog), or country is not a numeric code. | BAD_VALUES: Generic validation failure fallback (rare — most validated fields have a dedicated message below). | BAD_MULTIPLE: multiple is not a valid boolean value. | BAD_MAX_PRICE: maxPrice is not numeric. | BAD_PROVIDER_IDS: providerIds failed validation. A more specific message for this field is coming soon — until then, a generic message is returned instead (e.g. \"The provider ids field must be a string.\"). | BAD_EXCEPT_PROVIDER_IDS: exceptProviderIds failed validation. A more specific message for this field is coming soon — until then, a generic message is returned instead. | NO_PROVIDERS: None of the requested providerIds (minus exceptProviderIds) currently offer this service/country pair at all. Distinct from NO_NUMBERS (offers exist but are out of stock) and WRONG_MAX_PRICE (offers exist but cost more than maxPrice). | BAD_ACTIVATION_TYPE: activationType failed validation. A more specific message for this field is coming soon — until then, a generic message is returned instead. | BAD_FIXED_PRICE: fixedPrice is present but is not the literal string 'true' or 'false'.","content":{"text/plain":{"schema":{"type":"string"},"examples":{"success":{"summary":"success","description":"Activation id followed by the purchased phone number.","value":"ACCESS_NUMBER:557860099:18734721259"},"NO_NUMBERS":{"summary":"NO_NUMBERS","description":"No number available for the requested service/country/filters (includes the case where a locked/removed variation is hit).","value":"NO_NUMBERS"},"NO_BALANCE":{"summary":"NO_BALANCE","description":"Insufficient balance for the pre-check price.","value":"NO_BALANCE"},"BAD_SERVICE":{"summary":"BAD_SERVICE","description":"Unknown service, or the service/country pair is removed from the catalog, or min_user_topup gate not met.","value":"BAD_SERVICE"},"BAD_COUNTRY":{"summary":"BAD_COUNTRY","description":"Unknown country code (not in the catalog), or country is not a numeric code.","value":"BAD_COUNTRY"},"BAD_VALUES":{"summary":"BAD_VALUES","description":"Generic validation failure fallback (rare — most validated fields have a dedicated message below).","value":"BAD_VALUES"},"BAD_MULTIPLE":{"summary":"BAD_MULTIPLE","description":"multiple is not a valid boolean value.","value":"BAD_MULTIPLE"},"BAD_MAX_PRICE":{"summary":"BAD_MAX_PRICE","description":"maxPrice is not numeric.","value":"BAD_MAX_PRICE"},"BAD_PROVIDER_IDS":{"summary":"BAD_PROVIDER_IDS","description":"providerIds failed validation. A more specific message for this field is coming soon — until then, a generic message is returned instead (e.g. \"The provider ids field must be a string.\").","value":"BAD_PROVIDER_IDS","x-feature-flag":"api_validation_messages_enabled"},"BAD_EXCEPT_PROVIDER_IDS":{"summary":"BAD_EXCEPT_PROVIDER_IDS","description":"exceptProviderIds failed validation. A more specific message for this field is coming soon — until then, a generic message is returned instead.","value":"BAD_EXCEPT_PROVIDER_IDS","x-feature-flag":"api_validation_messages_enabled"},"NO_PROVIDERS":{"summary":"NO_PROVIDERS","description":"None of the requested providerIds (minus exceptProviderIds) currently offer this service/country pair at all. Distinct from NO_NUMBERS (offers exist but are out of stock) and WRONG_MAX_PRICE (offers exist but cost more than maxPrice).","value":"NO_PROVIDERS","x-feature-flag":"api_no_providers_enabled"},"BAD_ACTIVATION_TYPE":{"summary":"BAD_ACTIVATION_TYPE","description":"activationType failed validation. A more specific message for this field is coming soon — until then, a generic message is returned instead.","value":"BAD_ACTIVATION_TYPE","x-feature-flag":"api_validation_messages_enabled"},"BAD_FIXED_PRICE":{"summary":"BAD_FIXED_PRICE","description":"fixedPrice is present but is not the literal string 'true' or 'false'.","value":"BAD_FIXED_PRICE"}}}}},"400":{"description":"WRONG_MAX_PRICE: Returned when maxPrice is below the minimum sellable price for the pair (or for the selected providerIds); the number after the colon is that minimum. Not yet available — this case currently returns NO_NUMBERS instead.","content":{"text/plain":{"schema":{"type":"string"},"examples":{"WRONG_MAX_PRICE":{"summary":"WRONG_MAX_PRICE","description":"Returned when maxPrice is below the minimum sellable price for the pair (or for the selected providerIds); the number after the colon is that minimum. Not yet available — this case currently returns NO_NUMBERS instead.","value":"WRONG_MAX_PRICE:0.1453","x-feature-flag":"api_wrong_max_price_enabled"}}}}},"401":{"description":"BAD_KEY: Missing/invalid api_key. Checked by shared middleware before any action code runs. Becomes the {\"title\":\"BAD_KEY\",...} JSON envelope only under flag api_json_envelope_enabled AND format=json/*V2/*V3 intent.","content":{"text/plain":{"schema":{"type":"string"},"examples":{"BAD_KEY":{"summary":"BAD_KEY","description":"Missing/invalid api_key. Checked by shared middleware before any action code runs. Becomes the {\"title\":\"BAD_KEY\",...} JSON envelope only under flag api_json_envelope_enabled AND format=json/*V2/*V3 intent.","value":"BAD_KEY"}}}}},"429":{"description":"Too Many Requests: Rate limited before your request reaches our application — plain text, not part of a JSON envelope. Includes a Retry-After header.","content":{"text/plain":{"schema":{"type":"string"},"examples":{"Too Many Requests":{"summary":"Too Many Requests","description":"Rate limited before your request reaches our application — plain text, not part of a JSON envelope. Includes a Retry-After header.","value":"Too Many Requests"}}}}}}}},"/stubs/handler_api.php?action=getNumberV2":{"get":{"operationId":"getNumberV2","summary":"Purchase a phone number, full typed JSON success/error envelope.","description":"Purchase a phone number, full typed JSON success/error envelope.\n\nGated by flag `api_get_number_v2_enabled` (currently ON in this environment). While OFF, this action returns plain-text `BAD_ACTION`, HTTP 200, byte-identical to an unknown action.","tags":["v2"],"x-status":"new","x-feature-flag":"api_get_number_v2_enabled","parameters":[{"name":"action","in":"query","required":true,"schema":{"type":"string","enum":["getNumberV2"]},"example":"getNumberV2","description":"Fixed for this operation."},{"name":"api_key","in":"query","required":true,"schema":{"type":"string"},"example":"YOUR_API_KEY","description":"Your account API key. Placeholder shown — never a real key."},{"name":"service","in":"query","required":true,"schema":{"type":"string","example":"tg"},"description":"sms_activate-style service code."},{"name":"country","in":"query","required":true,"schema":{"type":"integer","example":6},"description":"Numeric country code (sms_activate_code)."},{"name":"multiple","in":"query","required":false,"schema":{"type":"boolean","example":false},"description":"Require a variation that allows multiple SMS to the same number."},{"name":"maxPrice","in":"query","required":false,"schema":{"type":"number","example":0.2},"description":"Ceiling price in USD, 4dp. <=0/non-numeric is treated as \"not set\"."},{"name":"providerIds","in":"query","required":false,"schema":{"type":"string","example":"235,240"},"description":"Comma-separated provider ids."},{"name":"exceptProviderIds","in":"query","required":false,"schema":{"type":"string","example":"99"},"description":"Comma-separated provider ids to exclude."},{"name":"ref","in":"query","required":false,"schema":{"type":"string"},"description":"Referral id."},{"name":"activationType","in":"query","required":false,"schema":{"type":"string","example":"SMS"},"description":"SMS (default), CALL_FLASH, CALL_VOICE, CALL_INTERACTIVE, RENT_SMS (accepted, rental unsupported)."},{"name":"fixedPrice","in":"query","required":false,"schema":{"type":"string","example":"true"},"description":"Literal 'true'/'false'. Requires maxPrice. When 'true', the charge is locked to exactly maxPrice instead of the usual hold-then-settle-at-real-price flow. [flag: api_fixed_price_enabled]"}],"responses":{"200":{"description":"success: Purchase succeeded. activationCost may later be adjusted down once the final cost is confirmed — that's expected, not a bug. countryPhoneCode can be null, and activationEndTime marks when the SMS window closes. | NO_NUMBERS: No numbers available for the requested service/country/filters. | BAD_SERVICE: Unknown service, the pair is removed from the catalog, or the min_user_topup gate is not met (v1 parity). | BAD_COUNTRY: Unknown country code (not in the catalog). | NO_PROVIDERS: None of the requested providerIds (minus exceptProviderIds) currently offer the pair at all. Distinct from NO_NUMBERS (out of stock) and WRONG_MAX_PRICE (pricier than maxPrice).","content":{"application/json":{"schema":{"type":"object"},"examples":{"success":{"summary":"success","description":"Purchase succeeded. activationCost may later be adjusted down once the final cost is confirmed — that's expected, not a bug. countryPhoneCode can be null, and activationEndTime marks when the SMS window closes.","value":{"activationId":"557860099","phoneNumber":"18734721259","activationCost":0.05,"currency":840,"countryCode":6,"countryPhoneCode":1,"canGetAnotherSms":true,"activationTime":"2026-07-02T18:09:54+00:00","activationEndTime":"2026-07-02T18:29:54+00:00","activationOperator":"any"}},"NO_NUMBERS":{"summary":"NO_NUMBERS","description":"No numbers available for the requested service/country/filters.","value":{"title":"NO_NUMBERS","details":"No numbers available for the requested service and country"}},"BAD_SERVICE":{"summary":"BAD_SERVICE","description":"Unknown service, the pair is removed from the catalog, or the min_user_topup gate is not met (v1 parity).","value":{"title":"BAD_SERVICE","details":"This service/country combination is not available"}},"BAD_COUNTRY":{"summary":"BAD_COUNTRY","description":"Unknown country code (not in the catalog).","value":{"title":"BAD_COUNTRY","details":"Unknown country code."}},"NO_PROVIDERS":{"summary":"NO_PROVIDERS","description":"None of the requested providerIds (minus exceptProviderIds) currently offer the pair at all. Distinct from NO_NUMBERS (out of stock) and WRONG_MAX_PRICE (pricier than maxPrice).","value":{"title":"NO_PROVIDERS","details":"None of the selected providers currently offer this service/country"},"x-feature-flag":"api_no_providers_enabled"}}}}},"400":{"description":"WRONG_MAX_PRICE: maxPrice is below the public sellable minimum.","content":{"application/json":{"schema":{"type":"object"},"examples":{"WRONG_MAX_PRICE":{"summary":"WRONG_MAX_PRICE","description":"maxPrice is below the public sellable minimum.","value":{"title":"WRONG_MAX_PRICE","details":"The maximum price is less than the permitted price","info":{"min":0.1453}},"x-feature-flag":"api_wrong_max_price_enabled"}}}}},"401":{"description":"BAD_KEY: Missing/invalid api_key. Checked by shared middleware before any action code runs. Becomes the {\"title\":\"BAD_KEY\",...} JSON envelope only under flag api_json_envelope_enabled AND format=json/*V2/*V3 intent.","content":{"text/plain":{"schema":{"type":"string"},"examples":{"BAD_KEY":{"summary":"BAD_KEY","description":"Missing/invalid api_key. Checked by shared middleware before any action code runs. Becomes the {\"title\":\"BAD_KEY\",...} JSON envelope only under flag api_json_envelope_enabled AND format=json/*V2/*V3 intent.","value":"BAD_KEY"}}}}},"402":{"description":"NO_BALANCE: Insufficient balance.","content":{"application/json":{"schema":{"type":"object"},"examples":{"NO_BALANCE":{"summary":"NO_BALANCE","description":"Insufficient balance.","value":{"title":"NO_BALANCE","details":"Insufficient balance"}}}}}},"422":{"description":"UNPROCESSABLE_ENTITY: Validation failed (first validation message, e.g. BAD_SERVICE/BAD_COUNTRY/BAD_MAX_PRICE/BAD_FIXED_PRICE/...).","content":{"application/json":{"schema":{"type":"object"},"examples":{"UNPROCESSABLE_ENTITY":{"summary":"UNPROCESSABLE_ENTITY","description":"Validation failed (first validation message, e.g. BAD_SERVICE/BAD_COUNTRY/BAD_MAX_PRICE/BAD_FIXED_PRICE/...).","value":{"title":"UNPROCESSABLE_ENTITY","details":"The service field is required."}}}}}},"429":{"description":"Too Many Requests: Edge rate limit, plain text (not part of the JSON envelope).","content":{"text/plain":{"schema":{"type":"string"},"examples":{"Too Many Requests":{"summary":"Too Many Requests","description":"Edge rate limit, plain text (not part of the JSON envelope).","value":"Too Many Requests"}}}}}}},"post":{"operationId":"getNumberV2","summary":"Purchase a phone number, full typed JSON success/error envelope.","description":"Purchase a phone number, full typed JSON success/error envelope.\n\nGated by flag `api_get_number_v2_enabled` (currently ON in this environment). While OFF, this action returns plain-text `BAD_ACTION`, HTTP 200, byte-identical to an unknown action.","tags":["v2"],"x-status":"new","x-feature-flag":"api_get_number_v2_enabled","parameters":[{"name":"action","in":"query","required":true,"schema":{"type":"string","enum":["getNumberV2"]},"example":"getNumberV2","description":"Fixed for this operation."},{"name":"api_key","in":"query","required":true,"schema":{"type":"string"},"example":"YOUR_API_KEY","description":"Your account API key. Placeholder shown — never a real key."},{"name":"service","in":"query","required":true,"schema":{"type":"string","example":"tg"},"description":"sms_activate-style service code."},{"name":"country","in":"query","required":true,"schema":{"type":"integer","example":6},"description":"Numeric country code (sms_activate_code)."},{"name":"multiple","in":"query","required":false,"schema":{"type":"boolean","example":false},"description":"Require a variation that allows multiple SMS to the same number."},{"name":"maxPrice","in":"query","required":false,"schema":{"type":"number","example":0.2},"description":"Ceiling price in USD, 4dp. <=0/non-numeric is treated as \"not set\"."},{"name":"providerIds","in":"query","required":false,"schema":{"type":"string","example":"235,240"},"description":"Comma-separated provider ids."},{"name":"exceptProviderIds","in":"query","required":false,"schema":{"type":"string","example":"99"},"description":"Comma-separated provider ids to exclude."},{"name":"ref","in":"query","required":false,"schema":{"type":"string"},"description":"Referral id."},{"name":"activationType","in":"query","required":false,"schema":{"type":"string","example":"SMS"},"description":"SMS (default), CALL_FLASH, CALL_VOICE, CALL_INTERACTIVE, RENT_SMS (accepted, rental unsupported)."},{"name":"fixedPrice","in":"query","required":false,"schema":{"type":"string","example":"true"},"description":"Literal 'true'/'false'. Requires maxPrice. When 'true', the charge is locked to exactly maxPrice instead of the usual hold-then-settle-at-real-price flow. [flag: api_fixed_price_enabled]"}],"responses":{"200":{"description":"success: Purchase succeeded. activationCost may later be adjusted down once the final cost is confirmed — that's expected, not a bug. countryPhoneCode can be null, and activationEndTime marks when the SMS window closes. | NO_NUMBERS: No numbers available for the requested service/country/filters. | BAD_SERVICE: Unknown service, the pair is removed from the catalog, or the min_user_topup gate is not met (v1 parity). | BAD_COUNTRY: Unknown country code (not in the catalog). | NO_PROVIDERS: None of the requested providerIds (minus exceptProviderIds) currently offer the pair at all. Distinct from NO_NUMBERS (out of stock) and WRONG_MAX_PRICE (pricier than maxPrice).","content":{"application/json":{"schema":{"type":"object"},"examples":{"success":{"summary":"success","description":"Purchase succeeded. activationCost may later be adjusted down once the final cost is confirmed — that's expected, not a bug. countryPhoneCode can be null, and activationEndTime marks when the SMS window closes.","value":{"activationId":"557860099","phoneNumber":"18734721259","activationCost":0.05,"currency":840,"countryCode":6,"countryPhoneCode":1,"canGetAnotherSms":true,"activationTime":"2026-07-02T18:09:54+00:00","activationEndTime":"2026-07-02T18:29:54+00:00","activationOperator":"any"}},"NO_NUMBERS":{"summary":"NO_NUMBERS","description":"No numbers available for the requested service/country/filters.","value":{"title":"NO_NUMBERS","details":"No numbers available for the requested service and country"}},"BAD_SERVICE":{"summary":"BAD_SERVICE","description":"Unknown service, the pair is removed from the catalog, or the min_user_topup gate is not met (v1 parity).","value":{"title":"BAD_SERVICE","details":"This service/country combination is not available"}},"BAD_COUNTRY":{"summary":"BAD_COUNTRY","description":"Unknown country code (not in the catalog).","value":{"title":"BAD_COUNTRY","details":"Unknown country code."}},"NO_PROVIDERS":{"summary":"NO_PROVIDERS","description":"None of the requested providerIds (minus exceptProviderIds) currently offer the pair at all. Distinct from NO_NUMBERS (out of stock) and WRONG_MAX_PRICE (pricier than maxPrice).","value":{"title":"NO_PROVIDERS","details":"None of the selected providers currently offer this service/country"},"x-feature-flag":"api_no_providers_enabled"}}}}},"400":{"description":"WRONG_MAX_PRICE: maxPrice is below the public sellable minimum.","content":{"application/json":{"schema":{"type":"object"},"examples":{"WRONG_MAX_PRICE":{"summary":"WRONG_MAX_PRICE","description":"maxPrice is below the public sellable minimum.","value":{"title":"WRONG_MAX_PRICE","details":"The maximum price is less than the permitted price","info":{"min":0.1453}},"x-feature-flag":"api_wrong_max_price_enabled"}}}}},"401":{"description":"BAD_KEY: Missing/invalid api_key. Checked by shared middleware before any action code runs. Becomes the {\"title\":\"BAD_KEY\",...} JSON envelope only under flag api_json_envelope_enabled AND format=json/*V2/*V3 intent.","content":{"text/plain":{"schema":{"type":"string"},"examples":{"BAD_KEY":{"summary":"BAD_KEY","description":"Missing/invalid api_key. Checked by shared middleware before any action code runs. Becomes the {\"title\":\"BAD_KEY\",...} JSON envelope only under flag api_json_envelope_enabled AND format=json/*V2/*V3 intent.","value":"BAD_KEY"}}}}},"402":{"description":"NO_BALANCE: Insufficient balance.","content":{"application/json":{"schema":{"type":"object"},"examples":{"NO_BALANCE":{"summary":"NO_BALANCE","description":"Insufficient balance.","value":{"title":"NO_BALANCE","details":"Insufficient balance"}}}}}},"422":{"description":"UNPROCESSABLE_ENTITY: Validation failed (first validation message, e.g. BAD_SERVICE/BAD_COUNTRY/BAD_MAX_PRICE/BAD_FIXED_PRICE/...).","content":{"application/json":{"schema":{"type":"object"},"examples":{"UNPROCESSABLE_ENTITY":{"summary":"UNPROCESSABLE_ENTITY","description":"Validation failed (first validation message, e.g. BAD_SERVICE/BAD_COUNTRY/BAD_MAX_PRICE/BAD_FIXED_PRICE/...).","value":{"title":"UNPROCESSABLE_ENTITY","details":"The service field is required."}}}}}},"429":{"description":"Too Many Requests: Edge rate limit, plain text (not part of the JSON envelope).","content":{"text/plain":{"schema":{"type":"string"},"examples":{"Too Many Requests":{"summary":"Too Many Requests","description":"Edge rate limit, plain text (not part of the JSON envelope).","value":"Too Many Requests"}}}}}}}},"/stubs/handler_api.php?action=getOffers":{"get":{"operationId":"getOffers","summary":"Combined price+stock showcase: default/retail/min price, counts and the full price-bucket map, by service and country.","description":"Combined price+stock showcase: default/retail/min price, counts and the full price-bucket map, by service and country.\n\nGated by flag `api_offers_enabled` (currently ON in this environment). While OFF, this action returns plain-text `BAD_ACTION`, HTTP 200, byte-identical to an unknown action.\n\nRequires the same price-bucket data as getFreePrices/getPricesV3 — when that data isn't available for this account, this method returns an empty `data: {}` rather than falling back to catalog prices.\n\nThere is no `counts.physical` field: our provider module does not currently expose a physical stock figure separate from `counts.total`, and this method does not invent one. It may be added later if that data becomes available.\n\nNever exposes providers, cost, or purchase price — none of those exist in this response by design.","tags":["v3"],"x-status":"new","x-feature-flag":"api_offers_enabled","parameters":[{"name":"action","in":"query","required":true,"schema":{"type":"string","enum":["getOffers"]},"example":"getOffers","description":"Fixed for this operation."},{"name":"api_key","in":"query","required":true,"schema":{"type":"string"},"example":"YOUR_API_KEY","description":"Your account API key. Placeholder shown — never a real key."},{"name":"services","in":"query","required":false,"schema":{"type":"string","example":"tg,go"},"description":"Comma-separated service codes (e.g. 'tg,go'). A single code also works. Omit to include every service."},{"name":"countries","in":"query","required":false,"schema":{"type":"string","example":"6,33"},"description":"Comma-separated numeric country codes (e.g. '6,33'). A single code also works. Omit to include every country."}],"responses":{"200":{"description":"success: Keyed by service code then numeric country code (note the order: service first, unlike getPrices/getFreePrices/getPricesV3). prices.default/counts.total are the exact same values as getPrices' cost/count for the pair; prices.min is the same sellable minimum as getNumber's WRONG_MAX_PRICE; map is the same price(4dp)=>count bucket map as getFreePrices, keyed here per-bucket (not cumulative). prices.retail comes from the catalog's retail price and already includes any markup. A pair is omitted entirely when it has no live price-bucket data. Cached up to 45 seconds — treat it as a snapshot, not a live feed. | BAD_SERVICE: services fails to parse (empty, over 50 items, or malformed), or none of the listed service codes exist. A partially-valid list keeps the valid pairs and omits the unknown ones. | BAD_COUNTRY: countries fails to parse (empty, over 50 items, or a non-numeric token), or none of the listed country codes exist. A partially-valid list omits only the unknown ones.","content":{"application/json":{"schema":{"type":"object"},"examples":{"success":{"summary":"success","description":"Keyed by service code then numeric country code (note the order: service first, unlike getPrices/getFreePrices/getPricesV3). prices.default/counts.total are the exact same values as getPrices' cost/count for the pair; prices.min is the same sellable minimum as getNumber's WRONG_MAX_PRICE; map is the same price(4dp)=>count bucket map as getFreePrices, keyed here per-bucket (not cumulative). prices.retail comes from the catalog's retail price and already includes any markup. A pair is omitted entirely when it has no live price-bucket data. Cached up to 45 seconds — treat it as a snapshot, not a live feed.","value":{"data":{"tg":{"6":{"prices":{"default":0.15,"retail":0.165,"min":0.15},"counts":{"total":22598,"defaultPrice":4787},"map":{"0.1500":4787,"0.1765":12043,"1.7648":5814}}}}}},"BAD_SERVICE":{"summary":"BAD_SERVICE","description":"services fails to parse (empty, over 50 items, or malformed), or none of the listed service codes exist. A partially-valid list keeps the valid pairs and omits the unknown ones.","value":{"title":"BAD_SERVICE","details":"Unknown service code."}},"BAD_COUNTRY":{"summary":"BAD_COUNTRY","description":"countries fails to parse (empty, over 50 items, or a non-numeric token), or none of the listed country codes exist. A partially-valid list omits only the unknown ones.","value":{"title":"BAD_COUNTRY","details":"Unknown country code."}}}}}},"401":{"description":"BAD_KEY: Missing/invalid api_key. Checked by shared middleware before any action code runs. Becomes the {\"title\":\"BAD_KEY\",...} JSON envelope only under flag api_json_envelope_enabled AND format=json/*V2/*V3 intent.","content":{"text/plain":{"schema":{"type":"string"},"examples":{"BAD_KEY":{"summary":"BAD_KEY","description":"Missing/invalid api_key. Checked by shared middleware before any action code runs. Becomes the {\"title\":\"BAD_KEY\",...} JSON envelope only under flag api_json_envelope_enabled AND format=json/*V2/*V3 intent.","value":"BAD_KEY"}}}}},"429":{"description":"Too Many Requests: Rate limited per user (this method has no single service+country pair to key the usual per-pair limiter on).","content":{"text/plain":{"schema":{"type":"string"},"examples":{"Too Many Requests":{"summary":"Too Many Requests","description":"Rate limited per user (this method has no single service+country pair to key the usual per-pair limiter on).","value":"Too Many Requests"}}}}}}},"post":{"operationId":"getOffers","summary":"Combined price+stock showcase: default/retail/min price, counts and the full price-bucket map, by service and country.","description":"Combined price+stock showcase: default/retail/min price, counts and the full price-bucket map, by service and country.\n\nGated by flag `api_offers_enabled` (currently ON in this environment). While OFF, this action returns plain-text `BAD_ACTION`, HTTP 200, byte-identical to an unknown action.\n\nRequires the same price-bucket data as getFreePrices/getPricesV3 — when that data isn't available for this account, this method returns an empty `data: {}` rather than falling back to catalog prices.\n\nThere is no `counts.physical` field: our provider module does not currently expose a physical stock figure separate from `counts.total`, and this method does not invent one. It may be added later if that data becomes available.\n\nNever exposes providers, cost, or purchase price — none of those exist in this response by design.","tags":["v3"],"x-status":"new","x-feature-flag":"api_offers_enabled","parameters":[{"name":"action","in":"query","required":true,"schema":{"type":"string","enum":["getOffers"]},"example":"getOffers","description":"Fixed for this operation."},{"name":"api_key","in":"query","required":true,"schema":{"type":"string"},"example":"YOUR_API_KEY","description":"Your account API key. Placeholder shown — never a real key."},{"name":"services","in":"query","required":false,"schema":{"type":"string","example":"tg,go"},"description":"Comma-separated service codes (e.g. 'tg,go'). A single code also works. Omit to include every service."},{"name":"countries","in":"query","required":false,"schema":{"type":"string","example":"6,33"},"description":"Comma-separated numeric country codes (e.g. '6,33'). A single code also works. Omit to include every country."}],"responses":{"200":{"description":"success: Keyed by service code then numeric country code (note the order: service first, unlike getPrices/getFreePrices/getPricesV3). prices.default/counts.total are the exact same values as getPrices' cost/count for the pair; prices.min is the same sellable minimum as getNumber's WRONG_MAX_PRICE; map is the same price(4dp)=>count bucket map as getFreePrices, keyed here per-bucket (not cumulative). prices.retail comes from the catalog's retail price and already includes any markup. A pair is omitted entirely when it has no live price-bucket data. Cached up to 45 seconds — treat it as a snapshot, not a live feed. | BAD_SERVICE: services fails to parse (empty, over 50 items, or malformed), or none of the listed service codes exist. A partially-valid list keeps the valid pairs and omits the unknown ones. | BAD_COUNTRY: countries fails to parse (empty, over 50 items, or a non-numeric token), or none of the listed country codes exist. A partially-valid list omits only the unknown ones.","content":{"application/json":{"schema":{"type":"object"},"examples":{"success":{"summary":"success","description":"Keyed by service code then numeric country code (note the order: service first, unlike getPrices/getFreePrices/getPricesV3). prices.default/counts.total are the exact same values as getPrices' cost/count for the pair; prices.min is the same sellable minimum as getNumber's WRONG_MAX_PRICE; map is the same price(4dp)=>count bucket map as getFreePrices, keyed here per-bucket (not cumulative). prices.retail comes from the catalog's retail price and already includes any markup. A pair is omitted entirely when it has no live price-bucket data. Cached up to 45 seconds — treat it as a snapshot, not a live feed.","value":{"data":{"tg":{"6":{"prices":{"default":0.15,"retail":0.165,"min":0.15},"counts":{"total":22598,"defaultPrice":4787},"map":{"0.1500":4787,"0.1765":12043,"1.7648":5814}}}}}},"BAD_SERVICE":{"summary":"BAD_SERVICE","description":"services fails to parse (empty, over 50 items, or malformed), or none of the listed service codes exist. A partially-valid list keeps the valid pairs and omits the unknown ones.","value":{"title":"BAD_SERVICE","details":"Unknown service code."}},"BAD_COUNTRY":{"summary":"BAD_COUNTRY","description":"countries fails to parse (empty, over 50 items, or a non-numeric token), or none of the listed country codes exist. A partially-valid list omits only the unknown ones.","value":{"title":"BAD_COUNTRY","details":"Unknown country code."}}}}}},"401":{"description":"BAD_KEY: Missing/invalid api_key. Checked by shared middleware before any action code runs. Becomes the {\"title\":\"BAD_KEY\",...} JSON envelope only under flag api_json_envelope_enabled AND format=json/*V2/*V3 intent.","content":{"text/plain":{"schema":{"type":"string"},"examples":{"BAD_KEY":{"summary":"BAD_KEY","description":"Missing/invalid api_key. Checked by shared middleware before any action code runs. Becomes the {\"title\":\"BAD_KEY\",...} JSON envelope only under flag api_json_envelope_enabled AND format=json/*V2/*V3 intent.","value":"BAD_KEY"}}}}},"429":{"description":"Too Many Requests: Rate limited per user (this method has no single service+country pair to key the usual per-pair limiter on).","content":{"text/plain":{"schema":{"type":"string"},"examples":{"Too Many Requests":{"summary":"Too Many Requests","description":"Rate limited per user (this method has no single service+country pair to key the usual per-pair limiter on).","value":"Too Many Requests"}}}}}}}},"/stubs/handler_api.php?action=getPrices":{"get":{"operationId":"getPrices","summary":"Flat price/count map by country and service.","description":"Flat price/count map by country and service.\n\nAn unknown or removed service/country code returns BAD_SERVICE/BAD_COUNTRY. A valid code that simply has no offered variation for the pair still yields an empty result (the key is omitted).\n\nComma-separated lists (when enabled): each token is validated the same way as a single value; if none of the listed codes exist, BAD_SERVICE/BAD_COUNTRY is returned.","tags":["v1"],"x-status":"existing","parameters":[{"name":"action","in":"query","required":true,"schema":{"type":"string","enum":["getPrices"]},"example":"getPrices","description":"Fixed for this operation."},{"name":"api_key","in":"query","required":true,"schema":{"type":"string"},"example":"YOUR_API_KEY","description":"Your account API key. Placeholder shown — never a real key."},{"name":"service","in":"query","required":false,"schema":{"type":"string","example":"tg"},"description":"Filter to one service code. Comma-separated lists (e.g. 'tg,go') are coming soon. [flag: api_prices_comma_list_enabled]"},{"name":"country","in":"query","required":false,"schema":{"type":"integer","example":6},"description":"Filter to one numeric country code. Comma-separated lists (e.g. '6,33') are coming soon. [flag: api_prices_comma_list_enabled]"}],"responses":{"200":{"description":"success: cost is the current price as a string; count is the number of available numbers, sometimes a rough 50-100 placeholder when exact stock isn't tracked. An unknown or removed service/country code returns BAD_SERVICE/BAD_COUNTRY; a valid code with no offered variation for the pair is omitted. | BAD_SERVICE: service is not a string, or the service code is unknown / removed from the catalog. | BAD_COUNTRY: country is not an integer, or the country code is unknown / removed from the catalog. | BAD_VALUES: Generic validation exception fallback.","content":{"application/json":{"schema":{"type":"object"},"examples":{"success":{"summary":"success","description":"cost is the current price as a string; count is the number of available numbers, sometimes a rough 50-100 placeholder when exact stock isn't tracked. An unknown or removed service/country code returns BAD_SERVICE/BAD_COUNTRY; a valid code with no offered variation for the pair is omitted.","value":{"6":{"tg":{"cost":"0.1491","count":25370}}}},"BAD_SERVICE":{"summary":"BAD_SERVICE","description":"service is not a string, or the service code is unknown / removed from the catalog.","value":"BAD_SERVICE"},"BAD_COUNTRY":{"summary":"BAD_COUNTRY","description":"country is not an integer, or the country code is unknown / removed from the catalog.","value":"BAD_COUNTRY"},"BAD_VALUES":{"summary":"BAD_VALUES","description":"Generic validation exception fallback.","value":"BAD_VALUES"}}}}},"401":{"description":"BAD_KEY: Missing/invalid api_key. Checked by shared middleware before any action code runs. Becomes the {\"title\":\"BAD_KEY\",...} JSON envelope only under flag api_json_envelope_enabled AND format=json/*V2/*V3 intent.","content":{"text/plain":{"schema":{"type":"string"},"examples":{"BAD_KEY":{"summary":"BAD_KEY","description":"Missing/invalid api_key. Checked by shared middleware before any action code runs. Becomes the {\"title\":\"BAD_KEY\",...} JSON envelope only under flag api_json_envelope_enabled AND format=json/*V2/*V3 intent.","value":"BAD_KEY"}}}}}}},"post":{"operationId":"getPrices","summary":"Flat price/count map by country and service.","description":"Flat price/count map by country and service.\n\nAn unknown or removed service/country code returns BAD_SERVICE/BAD_COUNTRY. A valid code that simply has no offered variation for the pair still yields an empty result (the key is omitted).\n\nComma-separated lists (when enabled): each token is validated the same way as a single value; if none of the listed codes exist, BAD_SERVICE/BAD_COUNTRY is returned.","tags":["v1"],"x-status":"existing","parameters":[{"name":"action","in":"query","required":true,"schema":{"type":"string","enum":["getPrices"]},"example":"getPrices","description":"Fixed for this operation."},{"name":"api_key","in":"query","required":true,"schema":{"type":"string"},"example":"YOUR_API_KEY","description":"Your account API key. Placeholder shown — never a real key."},{"name":"service","in":"query","required":false,"schema":{"type":"string","example":"tg"},"description":"Filter to one service code. Comma-separated lists (e.g. 'tg,go') are coming soon. [flag: api_prices_comma_list_enabled]"},{"name":"country","in":"query","required":false,"schema":{"type":"integer","example":6},"description":"Filter to one numeric country code. Comma-separated lists (e.g. '6,33') are coming soon. [flag: api_prices_comma_list_enabled]"}],"responses":{"200":{"description":"success: cost is the current price as a string; count is the number of available numbers, sometimes a rough 50-100 placeholder when exact stock isn't tracked. An unknown or removed service/country code returns BAD_SERVICE/BAD_COUNTRY; a valid code with no offered variation for the pair is omitted. | BAD_SERVICE: service is not a string, or the service code is unknown / removed from the catalog. | BAD_COUNTRY: country is not an integer, or the country code is unknown / removed from the catalog. | BAD_VALUES: Generic validation exception fallback.","content":{"application/json":{"schema":{"type":"object"},"examples":{"success":{"summary":"success","description":"cost is the current price as a string; count is the number of available numbers, sometimes a rough 50-100 placeholder when exact stock isn't tracked. An unknown or removed service/country code returns BAD_SERVICE/BAD_COUNTRY; a valid code with no offered variation for the pair is omitted.","value":{"6":{"tg":{"cost":"0.1491","count":25370}}}},"BAD_SERVICE":{"summary":"BAD_SERVICE","description":"service is not a string, or the service code is unknown / removed from the catalog.","value":"BAD_SERVICE"},"BAD_COUNTRY":{"summary":"BAD_COUNTRY","description":"country is not an integer, or the country code is unknown / removed from the catalog.","value":"BAD_COUNTRY"},"BAD_VALUES":{"summary":"BAD_VALUES","description":"Generic validation exception fallback.","value":"BAD_VALUES"}}}}},"401":{"description":"BAD_KEY: Missing/invalid api_key. Checked by shared middleware before any action code runs. Becomes the {\"title\":\"BAD_KEY\",...} JSON envelope only under flag api_json_envelope_enabled AND format=json/*V2/*V3 intent.","content":{"text/plain":{"schema":{"type":"string"},"examples":{"BAD_KEY":{"summary":"BAD_KEY","description":"Missing/invalid api_key. Checked by shared middleware before any action code runs. Becomes the {\"title\":\"BAD_KEY\",...} JSON envelope only under flag api_json_envelope_enabled AND format=json/*V2/*V3 intent.","value":"BAD_KEY"}}}}}}}},"/stubs/handler_api.php?action=getPricesV2":{"get":{"operationId":"getPricesV2","summary":"Alias of getFreePrices.","description":"Alias of getFreePrices.","tags":["v2"],"x-status":"existing","parameters":[{"name":"action","in":"query","required":true,"schema":{"type":"string","enum":["getPricesV2"]},"example":"getPricesV2","description":"Fixed for this operation."},{"name":"api_key","in":"query","required":true,"schema":{"type":"string"},"example":"YOUR_API_KEY","description":"Your account API key. Placeholder shown — never a real key."},{"name":"service","in":"query","required":false,"schema":{"type":"string","example":"tg"},"description":"Filter to one service code. Comma-separated lists (e.g. 'tg,go') are coming soon. [flag: api_prices_comma_list_enabled]"},{"name":"country","in":"query","required":false,"schema":{"type":"integer","example":6},"description":"Filter to one numeric country code. Comma-separated lists (e.g. '6,33') are coming soon. [flag: api_prices_comma_list_enabled]"}],"responses":{"200":{"description":"success: Map keyed by price (a USD string, 4 decimal places) to numbers_count, plus a parallel has_multi map. Returns an empty object when price-bucket data isn't available for this account. | BAD_SERVICE: service is not a string, or the service code is unknown / removed. | BAD_COUNTRY: country is not an integer, or the country code is unknown / removed. | BAD_VALUES: Generic validation exception fallback.","content":{"application/json":{"schema":{"type":"object"},"examples":{"success":{"summary":"success","description":"Map keyed by price (a USD string, 4 decimal places) to numbers_count, plus a parallel has_multi map. Returns an empty object when price-bucket data isn't available for this account.","value":{"6":{"tg":{"prices":{"0.1491":100,"0.1650":40},"has_multi":{"0.1491":false,"0.1650":true}}}}},"BAD_SERVICE":{"summary":"BAD_SERVICE","description":"service is not a string, or the service code is unknown / removed.","value":"BAD_SERVICE"},"BAD_COUNTRY":{"summary":"BAD_COUNTRY","description":"country is not an integer, or the country code is unknown / removed.","value":"BAD_COUNTRY"},"BAD_VALUES":{"summary":"BAD_VALUES","description":"Generic validation exception fallback.","value":"BAD_VALUES"}}}}},"401":{"description":"BAD_KEY: Missing/invalid api_key. Checked by shared middleware before any action code runs. Becomes the {\"title\":\"BAD_KEY\",...} JSON envelope only under flag api_json_envelope_enabled AND format=json/*V2/*V3 intent.","content":{"text/plain":{"schema":{"type":"string"},"examples":{"BAD_KEY":{"summary":"BAD_KEY","description":"Missing/invalid api_key. Checked by shared middleware before any action code runs. Becomes the {\"title\":\"BAD_KEY\",...} JSON envelope only under flag api_json_envelope_enabled AND format=json/*V2/*V3 intent.","value":"BAD_KEY"}}}}}}},"post":{"operationId":"getPricesV2","summary":"Alias of getFreePrices.","description":"Alias of getFreePrices.","tags":["v2"],"x-status":"existing","parameters":[{"name":"action","in":"query","required":true,"schema":{"type":"string","enum":["getPricesV2"]},"example":"getPricesV2","description":"Fixed for this operation."},{"name":"api_key","in":"query","required":true,"schema":{"type":"string"},"example":"YOUR_API_KEY","description":"Your account API key. Placeholder shown — never a real key."},{"name":"service","in":"query","required":false,"schema":{"type":"string","example":"tg"},"description":"Filter to one service code. Comma-separated lists (e.g. 'tg,go') are coming soon. [flag: api_prices_comma_list_enabled]"},{"name":"country","in":"query","required":false,"schema":{"type":"integer","example":6},"description":"Filter to one numeric country code. Comma-separated lists (e.g. '6,33') are coming soon. [flag: api_prices_comma_list_enabled]"}],"responses":{"200":{"description":"success: Map keyed by price (a USD string, 4 decimal places) to numbers_count, plus a parallel has_multi map. Returns an empty object when price-bucket data isn't available for this account. | BAD_SERVICE: service is not a string, or the service code is unknown / removed. | BAD_COUNTRY: country is not an integer, or the country code is unknown / removed. | BAD_VALUES: Generic validation exception fallback.","content":{"application/json":{"schema":{"type":"object"},"examples":{"success":{"summary":"success","description":"Map keyed by price (a USD string, 4 decimal places) to numbers_count, plus a parallel has_multi map. Returns an empty object when price-bucket data isn't available for this account.","value":{"6":{"tg":{"prices":{"0.1491":100,"0.1650":40},"has_multi":{"0.1491":false,"0.1650":true}}}}},"BAD_SERVICE":{"summary":"BAD_SERVICE","description":"service is not a string, or the service code is unknown / removed.","value":"BAD_SERVICE"},"BAD_COUNTRY":{"summary":"BAD_COUNTRY","description":"country is not an integer, or the country code is unknown / removed.","value":"BAD_COUNTRY"},"BAD_VALUES":{"summary":"BAD_VALUES","description":"Generic validation exception fallback.","value":"BAD_VALUES"}}}}},"401":{"description":"BAD_KEY: Missing/invalid api_key. Checked by shared middleware before any action code runs. Becomes the {\"title\":\"BAD_KEY\",...} JSON envelope only under flag api_json_envelope_enabled AND format=json/*V2/*V3 intent.","content":{"text/plain":{"schema":{"type":"string"},"examples":{"BAD_KEY":{"summary":"BAD_KEY","description":"Missing/invalid api_key. Checked by shared middleware before any action code runs. Becomes the {\"title\":\"BAD_KEY\",...} JSON envelope only under flag api_json_envelope_enabled AND format=json/*V2/*V3 intent.","value":"BAD_KEY"}}}}}}}},"/stubs/handler_api.php?action=getPricesV3":{"get":{"operationId":"getPricesV3","summary":"Price/count map with a per-provider price breakdown.","description":"Price/count map with per-provider sale price breakdown.\n\nGated by flag `api_prices_v3_enabled` (currently ON in this environment). While OFF, this action returns plain-text `BAD_ACTION`, HTTP 200, byte-identical to an unknown action.\n\nUnlike every other JSON method in this family, an unexpected internal error here returns the plain-text BAD_ACTION response instead of a JSON body — this is intentional, so a JSON-parsing client never receives a half-formed JSON body.\n\nComma-separated lists (coming soon): will trigger when either service or country contains a comma; each token is validated the same way as a single value, and each list is capped at 50 items with 100 total country×service combinations.","tags":["v3"],"x-status":"new","x-feature-flag":"api_prices_v3_enabled","parameters":[{"name":"action","in":"query","required":true,"schema":{"type":"string","enum":["getPricesV3"]},"example":"getPricesV3","description":"Fixed for this operation."},{"name":"api_key","in":"query","required":true,"schema":{"type":"string"},"example":"YOUR_API_KEY","description":"Your account API key. Placeholder shown — never a real key."},{"name":"service","in":"query","required":true,"schema":{"type":"string","example":"tg"},"description":"Service code — required, unlike the V1 getPrices method. Comma-separated lists (e.g. 'tg,go') are coming soon. [flag: api_prices_comma_list_enabled]"},{"name":"country","in":"query","required":true,"schema":{"type":"integer","example":6},"description":"Numeric country code — required, unlike the V1 getPrices method. Comma-separated lists (e.g. '6,33') are coming soon. [flag: api_prices_comma_list_enabled]"}],"responses":{"200":{"description":"success: price and count mirror the V1 getPrices values, including any custom pricing on your account. currency is always 840. providers lists each provider's distinct sale prices (general catalog, never your cost), and is empty when no provider is live for the pair. Cached up to 45 seconds — treat it as a snapshot, not a live feed. | BAD_SERVICE: Missing/unknown/removed service (single mode), or none of the comma-list service codes exist (list mode). | BAD_COUNTRY: Missing/unknown/removed country (single mode), or none of the comma-list country codes exist (list mode).","content":{"application/json":{"schema":{"type":"object"},"examples":{"success":{"summary":"success","description":"price and count mirror the V1 getPrices values, including any custom pricing on your account. currency is always 840. providers lists each provider's distinct sale prices (general catalog, never your cost), and is empty when no provider is live for the pair. Cached up to 45 seconds — treat it as a snapshot, not a live feed.","value":{"6":{"tg":{"price":0.15,"count":25370,"currency":840,"providers":{"235":{"count":5603,"price":[0.23],"provider_id":235}}}}}},"BAD_SERVICE":{"summary":"BAD_SERVICE","description":"Missing/unknown/removed service (single mode), or none of the comma-list service codes exist (list mode).","value":{"title":"BAD_SERVICE","details":"Unknown or missing service code."}},"BAD_COUNTRY":{"summary":"BAD_COUNTRY","description":"Missing/unknown/removed country (single mode), or none of the comma-list country codes exist (list mode).","value":{"title":"BAD_COUNTRY","details":"Unknown or missing country code."}}}}}},"401":{"description":"BAD_KEY: Missing/invalid api_key. Checked by shared middleware before any action code runs. Becomes the {\"title\":\"BAD_KEY\",...} JSON envelope only under flag api_json_envelope_enabled AND format=json/*V2/*V3 intent.","content":{"text/plain":{"schema":{"type":"string"},"examples":{"BAD_KEY":{"summary":"BAD_KEY","description":"Missing/invalid api_key. Checked by shared middleware before any action code runs. Becomes the {\"title\":\"BAD_KEY\",...} JSON envelope only under flag api_json_envelope_enabled AND format=json/*V2/*V3 intent.","value":"BAD_KEY"}}}}},"422":{"description":"UNPROCESSABLE_ENTITY: Only relevant to comma-separated list requests (coming soon): the country×service combination count exceeds the 100-item cap.","content":{"application/json":{"schema":{"type":"object"},"examples":{"UNPROCESSABLE_ENTITY":{"summary":"UNPROCESSABLE_ENTITY","description":"Only relevant to comma-separated list requests (coming soon): the country×service combination count exceeds the 100-item cap.","value":{"title":"UNPROCESSABLE_ENTITY","details":"Too many country/service combinations in the comma-list; reduce the list size."}}}}}},"429":{"description":"Too Many Requests: Rate-limited per user, service and country combination (same limiter as getNumber/getNumberImsi/getNumberV2). In a comma-separated list request, a rate-limited pair is skipped rather than failing the whole batch.","content":{"text/plain":{"schema":{"type":"string"},"examples":{"Too Many Requests":{"summary":"Too Many Requests","description":"Rate-limited per user, service and country combination (same limiter as getNumber/getNumberImsi/getNumberV2). In a comma-separated list request, a rate-limited pair is skipped rather than failing the whole batch.","value":"Too Many Requests"}}}}}}},"post":{"operationId":"getPricesV3","summary":"Price/count map with a per-provider price breakdown.","description":"Price/count map with per-provider sale price breakdown.\n\nGated by flag `api_prices_v3_enabled` (currently ON in this environment). While OFF, this action returns plain-text `BAD_ACTION`, HTTP 200, byte-identical to an unknown action.\n\nUnlike every other JSON method in this family, an unexpected internal error here returns the plain-text BAD_ACTION response instead of a JSON body — this is intentional, so a JSON-parsing client never receives a half-formed JSON body.\n\nComma-separated lists (coming soon): will trigger when either service or country contains a comma; each token is validated the same way as a single value, and each list is capped at 50 items with 100 total country×service combinations.","tags":["v3"],"x-status":"new","x-feature-flag":"api_prices_v3_enabled","parameters":[{"name":"action","in":"query","required":true,"schema":{"type":"string","enum":["getPricesV3"]},"example":"getPricesV3","description":"Fixed for this operation."},{"name":"api_key","in":"query","required":true,"schema":{"type":"string"},"example":"YOUR_API_KEY","description":"Your account API key. Placeholder shown — never a real key."},{"name":"service","in":"query","required":true,"schema":{"type":"string","example":"tg"},"description":"Service code — required, unlike the V1 getPrices method. Comma-separated lists (e.g. 'tg,go') are coming soon. [flag: api_prices_comma_list_enabled]"},{"name":"country","in":"query","required":true,"schema":{"type":"integer","example":6},"description":"Numeric country code — required, unlike the V1 getPrices method. Comma-separated lists (e.g. '6,33') are coming soon. [flag: api_prices_comma_list_enabled]"}],"responses":{"200":{"description":"success: price and count mirror the V1 getPrices values, including any custom pricing on your account. currency is always 840. providers lists each provider's distinct sale prices (general catalog, never your cost), and is empty when no provider is live for the pair. Cached up to 45 seconds — treat it as a snapshot, not a live feed. | BAD_SERVICE: Missing/unknown/removed service (single mode), or none of the comma-list service codes exist (list mode). | BAD_COUNTRY: Missing/unknown/removed country (single mode), or none of the comma-list country codes exist (list mode).","content":{"application/json":{"schema":{"type":"object"},"examples":{"success":{"summary":"success","description":"price and count mirror the V1 getPrices values, including any custom pricing on your account. currency is always 840. providers lists each provider's distinct sale prices (general catalog, never your cost), and is empty when no provider is live for the pair. Cached up to 45 seconds — treat it as a snapshot, not a live feed.","value":{"6":{"tg":{"price":0.15,"count":25370,"currency":840,"providers":{"235":{"count":5603,"price":[0.23],"provider_id":235}}}}}},"BAD_SERVICE":{"summary":"BAD_SERVICE","description":"Missing/unknown/removed service (single mode), or none of the comma-list service codes exist (list mode).","value":{"title":"BAD_SERVICE","details":"Unknown or missing service code."}},"BAD_COUNTRY":{"summary":"BAD_COUNTRY","description":"Missing/unknown/removed country (single mode), or none of the comma-list country codes exist (list mode).","value":{"title":"BAD_COUNTRY","details":"Unknown or missing country code."}}}}}},"401":{"description":"BAD_KEY: Missing/invalid api_key. Checked by shared middleware before any action code runs. Becomes the {\"title\":\"BAD_KEY\",...} JSON envelope only under flag api_json_envelope_enabled AND format=json/*V2/*V3 intent.","content":{"text/plain":{"schema":{"type":"string"},"examples":{"BAD_KEY":{"summary":"BAD_KEY","description":"Missing/invalid api_key. Checked by shared middleware before any action code runs. Becomes the {\"title\":\"BAD_KEY\",...} JSON envelope only under flag api_json_envelope_enabled AND format=json/*V2/*V3 intent.","value":"BAD_KEY"}}}}},"422":{"description":"UNPROCESSABLE_ENTITY: Only relevant to comma-separated list requests (coming soon): the country×service combination count exceeds the 100-item cap.","content":{"application/json":{"schema":{"type":"object"},"examples":{"UNPROCESSABLE_ENTITY":{"summary":"UNPROCESSABLE_ENTITY","description":"Only relevant to comma-separated list requests (coming soon): the country×service combination count exceeds the 100-item cap.","value":{"title":"UNPROCESSABLE_ENTITY","details":"Too many country/service combinations in the comma-list; reduce the list size."}}}}}},"429":{"description":"Too Many Requests: Rate-limited per user, service and country combination (same limiter as getNumber/getNumberImsi/getNumberV2). In a comma-separated list request, a rate-limited pair is skipped rather than failing the whole batch.","content":{"text/plain":{"schema":{"type":"string"},"examples":{"Too Many Requests":{"summary":"Too Many Requests","description":"Rate-limited per user, service and country combination (same limiter as getNumber/getNumberImsi/getNumberV2). In a comma-separated list request, a rate-limited pair is skipped rather than failing the whole batch.","value":"Too Many Requests"}}}}}}}},"/stubs/handler_api.php?action=getProviders":{"get":{"operationId":"getProviders","summary":"Public provider list (id/name/numbers_count/delivery_percent/number_lifetime, no price).","description":"Public provider list (id/name/numbers_count/delivery_percent/number_lifetime, no price).","tags":["v1"],"x-status":"existing","parameters":[{"name":"action","in":"query","required":true,"schema":{"type":"string","enum":["getProviders"]},"example":"getProviders","description":"Fixed for this operation."},{"name":"api_key","in":"query","required":true,"schema":{"type":"string"},"example":"YOUR_API_KEY","description":"Your account API key. Placeholder shown — never a real key."},{"name":"service","in":"query","required":false,"schema":{"type":"string","example":"tg"},"description":"Filter by service code."},{"name":"country","in":"query","required":false,"schema":{"type":"string","example":"US"},"description":"Filter by country code."}],"responses":{"200":{"description":"success: Response body is an HTML wrapper around a JSON array — treat it exactly as shown, and don't assume Content-Type is application/json. Cost and real vendor names are never included; id is our public numeric id, and name is always the literal Provider{id}. | BAD_VALUES: Unknown service/country code. | ERROR: Unexpected internal error (self-status fallback).","content":{"text/html; charset=utf-8":{"schema":{"type":"string"},"examples":{"success":{"summary":"success","description":"Response body is an HTML wrapper around a JSON array — treat it exactly as shown, and don't assume Content-Type is application/json. Cost and real vendor names are never included; id is our public numeric id, and name is always the literal Provider{id}.","value":"<html><head><meta charset=\"utf-8\"></head><body>[{\"id\":235,\"name\":\"Provider235\",\"numbers_count\":5603,\"delivery_percent\":97.5,\"number_lifetime\":1200}]</body></html>"},"BAD_VALUES":{"summary":"BAD_VALUES","description":"Unknown service/country code.","value":"BAD_VALUES"},"ERROR":{"summary":"ERROR","description":"Unexpected internal error (self-status fallback).","value":"ERROR"}}}}},"401":{"description":"BAD_KEY: Missing/invalid api_key. Checked by shared middleware before any action code runs. Becomes the {\"title\":\"BAD_KEY\",...} JSON envelope only under flag api_json_envelope_enabled AND format=json/*V2/*V3 intent.","content":{"text/plain":{"schema":{"type":"string"},"examples":{"BAD_KEY":{"summary":"BAD_KEY","description":"Missing/invalid api_key. Checked by shared middleware before any action code runs. Becomes the {\"title\":\"BAD_KEY\",...} JSON envelope only under flag api_json_envelope_enabled AND format=json/*V2/*V3 intent.","value":"BAD_KEY"}}}}}}},"post":{"operationId":"getProviders","summary":"Public provider list (id/name/numbers_count/delivery_percent/number_lifetime, no price).","description":"Public provider list (id/name/numbers_count/delivery_percent/number_lifetime, no price).","tags":["v1"],"x-status":"existing","parameters":[{"name":"action","in":"query","required":true,"schema":{"type":"string","enum":["getProviders"]},"example":"getProviders","description":"Fixed for this operation."},{"name":"api_key","in":"query","required":true,"schema":{"type":"string"},"example":"YOUR_API_KEY","description":"Your account API key. Placeholder shown — never a real key."},{"name":"service","in":"query","required":false,"schema":{"type":"string","example":"tg"},"description":"Filter by service code."},{"name":"country","in":"query","required":false,"schema":{"type":"string","example":"US"},"description":"Filter by country code."}],"responses":{"200":{"description":"success: Response body is an HTML wrapper around a JSON array — treat it exactly as shown, and don't assume Content-Type is application/json. Cost and real vendor names are never included; id is our public numeric id, and name is always the literal Provider{id}. | BAD_VALUES: Unknown service/country code. | ERROR: Unexpected internal error (self-status fallback).","content":{"text/html; charset=utf-8":{"schema":{"type":"string"},"examples":{"success":{"summary":"success","description":"Response body is an HTML wrapper around a JSON array — treat it exactly as shown, and don't assume Content-Type is application/json. Cost and real vendor names are never included; id is our public numeric id, and name is always the literal Provider{id}.","value":"<html><head><meta charset=\"utf-8\"></head><body>[{\"id\":235,\"name\":\"Provider235\",\"numbers_count\":5603,\"delivery_percent\":97.5,\"number_lifetime\":1200}]</body></html>"},"BAD_VALUES":{"summary":"BAD_VALUES","description":"Unknown service/country code.","value":"BAD_VALUES"},"ERROR":{"summary":"ERROR","description":"Unexpected internal error (self-status fallback).","value":"ERROR"}}}}},"401":{"description":"BAD_KEY: Missing/invalid api_key. Checked by shared middleware before any action code runs. Becomes the {\"title\":\"BAD_KEY\",...} JSON envelope only under flag api_json_envelope_enabled AND format=json/*V2/*V3 intent.","content":{"text/plain":{"schema":{"type":"string"},"examples":{"BAD_KEY":{"summary":"BAD_KEY","description":"Missing/invalid api_key. Checked by shared middleware before any action code runs. Becomes the {\"title\":\"BAD_KEY\",...} JSON envelope only under flag api_json_envelope_enabled AND format=json/*V2/*V3 intent.","value":"BAD_KEY"}}}}}}}},"/stubs/handler_api.php?action=getServiceNumbersCount":{"get":{"operationId":"getServiceNumbersCount","summary":"Available numbers count for a service/country.","description":"Available numbers count for a service/country.","tags":["v1"],"x-status":"existing","parameters":[{"name":"action","in":"query","required":true,"schema":{"type":"string","enum":["getServiceNumbersCount"]},"example":"getServiceNumbersCount","description":"Fixed for this operation."},{"name":"api_key","in":"query","required":true,"schema":{"type":"string"},"example":"YOUR_API_KEY","description":"Your account API key. Placeholder shown — never a real key."},{"name":"service","in":"query","required":true,"schema":{"type":"string","example":"tg"},"description":"Service code, must exist."}],"responses":{"200":{"description":"success: One entry per country that has stock for the service. numbersCount is the batch-ladder maximum when price buckets are enabled, otherwise the summed stock count. | BAD_SERVICE: Unknown service code.","content":{"application/json":{"schema":{"type":"object"},"examples":{"success":{"summary":"success","description":"One entry per country that has stock for the service. numbersCount is the batch-ladder maximum when price buckets are enabled, otherwise the summed stock count.","value":[{"countryCode":"6","numbersCount":25370}]},"BAD_SERVICE":{"summary":"BAD_SERVICE","description":"Unknown service code.","value":"BAD_SERVICE"}}}}},"401":{"description":"BAD_KEY: Missing/invalid api_key. Checked by shared middleware before any action code runs. Becomes the {\"title\":\"BAD_KEY\",...} JSON envelope only under flag api_json_envelope_enabled AND format=json/*V2/*V3 intent.","content":{"text/plain":{"schema":{"type":"string"},"examples":{"BAD_KEY":{"summary":"BAD_KEY","description":"Missing/invalid api_key. Checked by shared middleware before any action code runs. Becomes the {\"title\":\"BAD_KEY\",...} JSON envelope only under flag api_json_envelope_enabled AND format=json/*V2/*V3 intent.","value":"BAD_KEY"}}}}}}},"post":{"operationId":"getServiceNumbersCount","summary":"Available numbers count for a service/country.","description":"Available numbers count for a service/country.","tags":["v1"],"x-status":"existing","parameters":[{"name":"action","in":"query","required":true,"schema":{"type":"string","enum":["getServiceNumbersCount"]},"example":"getServiceNumbersCount","description":"Fixed for this operation."},{"name":"api_key","in":"query","required":true,"schema":{"type":"string"},"example":"YOUR_API_KEY","description":"Your account API key. Placeholder shown — never a real key."},{"name":"service","in":"query","required":true,"schema":{"type":"string","example":"tg"},"description":"Service code, must exist."}],"responses":{"200":{"description":"success: One entry per country that has stock for the service. numbersCount is the batch-ladder maximum when price buckets are enabled, otherwise the summed stock count. | BAD_SERVICE: Unknown service code.","content":{"application/json":{"schema":{"type":"object"},"examples":{"success":{"summary":"success","description":"One entry per country that has stock for the service. numbersCount is the batch-ladder maximum when price buckets are enabled, otherwise the summed stock count.","value":[{"countryCode":"6","numbersCount":25370}]},"BAD_SERVICE":{"summary":"BAD_SERVICE","description":"Unknown service code.","value":"BAD_SERVICE"}}}}},"401":{"description":"BAD_KEY: Missing/invalid api_key. Checked by shared middleware before any action code runs. Becomes the {\"title\":\"BAD_KEY\",...} JSON envelope only under flag api_json_envelope_enabled AND format=json/*V2/*V3 intent.","content":{"text/plain":{"schema":{"type":"string"},"examples":{"BAD_KEY":{"summary":"BAD_KEY","description":"Missing/invalid api_key. Checked by shared middleware before any action code runs. Becomes the {\"title\":\"BAD_KEY\",...} JSON envelope only under flag api_json_envelope_enabled AND format=json/*V2/*V3 intent.","value":"BAD_KEY"}}}}}}}},"/stubs/handler_api.php?action=getServicesList":{"get":{"operationId":"getServicesList","summary":"Catalog of services (code + name), optionally localized.","description":"Catalog of services (code + name), optionally localized.\n\nGated by flag `api_catalog_enabled` (currently ON in this environment). While OFF, this action returns plain-text `BAD_ACTION`, HTTP 200, byte-identical to an unknown action.\n\nThe only failure mode of this method is a 200 success response with an empty services list — there is no dedicated error response.","tags":["v1"],"x-status":"new","x-feature-flag":"api_catalog_enabled","parameters":[{"name":"action","in":"query","required":true,"schema":{"type":"string","enum":["getServicesList"]},"example":"getServicesList","description":"Fixed for this operation."},{"name":"api_key","in":"query","required":true,"schema":{"type":"string"},"example":"YOUR_API_KEY","description":"Your account API key. Placeholder shown — never a real key."},{"name":"country","in":"query","required":false,"schema":{"type":"string","example":"US"},"description":"Filter to services with at least one live variation in this country."},{"name":"lang","in":"query","required":false,"schema":{"type":"string","example":"en"},"description":"One of the 11 supported locales: en,ru,cn,es,pt,vn,id,hi,tr,ko,jp. Defaults to en, unsupported values fall back to en."}],"responses":{"200":{"description":"success: Never errors on unexpected failure — degrades to an empty services list with status still \"success\".","content":{"application/json":{"schema":{"type":"object"},"examples":{"success":{"summary":"success","description":"Never errors on unexpected failure — degrades to an empty services list with status still \"success\".","value":{"status":"success","services":[{"code":"tg","name":"Telegram"}]}}}}}},"401":{"description":"BAD_KEY: Missing/invalid api_key. Checked by shared middleware before any action code runs. Becomes the {\"title\":\"BAD_KEY\",...} JSON envelope only under flag api_json_envelope_enabled AND format=json/*V2/*V3 intent.","content":{"text/plain":{"schema":{"type":"string"},"examples":{"BAD_KEY":{"summary":"BAD_KEY","description":"Missing/invalid api_key. Checked by shared middleware before any action code runs. Becomes the {\"title\":\"BAD_KEY\",...} JSON envelope only under flag api_json_envelope_enabled AND format=json/*V2/*V3 intent.","value":"BAD_KEY"}}}}}}},"post":{"operationId":"getServicesList","summary":"Catalog of services (code + name), optionally localized.","description":"Catalog of services (code + name), optionally localized.\n\nGated by flag `api_catalog_enabled` (currently ON in this environment). While OFF, this action returns plain-text `BAD_ACTION`, HTTP 200, byte-identical to an unknown action.\n\nThe only failure mode of this method is a 200 success response with an empty services list — there is no dedicated error response.","tags":["v1"],"x-status":"new","x-feature-flag":"api_catalog_enabled","parameters":[{"name":"action","in":"query","required":true,"schema":{"type":"string","enum":["getServicesList"]},"example":"getServicesList","description":"Fixed for this operation."},{"name":"api_key","in":"query","required":true,"schema":{"type":"string"},"example":"YOUR_API_KEY","description":"Your account API key. Placeholder shown — never a real key."},{"name":"country","in":"query","required":false,"schema":{"type":"string","example":"US"},"description":"Filter to services with at least one live variation in this country."},{"name":"lang","in":"query","required":false,"schema":{"type":"string","example":"en"},"description":"One of the 11 supported locales: en,ru,cn,es,pt,vn,id,hi,tr,ko,jp. Defaults to en, unsupported values fall back to en."}],"responses":{"200":{"description":"success: Never errors on unexpected failure — degrades to an empty services list with status still \"success\".","content":{"application/json":{"schema":{"type":"object"},"examples":{"success":{"summary":"success","description":"Never errors on unexpected failure — degrades to an empty services list with status still \"success\".","value":{"status":"success","services":[{"code":"tg","name":"Telegram"}]}}}}}},"401":{"description":"BAD_KEY: Missing/invalid api_key. Checked by shared middleware before any action code runs. Becomes the {\"title\":\"BAD_KEY\",...} JSON envelope only under flag api_json_envelope_enabled AND format=json/*V2/*V3 intent.","content":{"text/plain":{"schema":{"type":"string"},"examples":{"BAD_KEY":{"summary":"BAD_KEY","description":"Missing/invalid api_key. Checked by shared middleware before any action code runs. Becomes the {\"title\":\"BAD_KEY\",...} JSON envelope only under flag api_json_envelope_enabled AND format=json/*V2/*V3 intent.","value":"BAD_KEY"}}}}}}}},"/stubs/handler_api.php?action=getStatus":{"get":{"operationId":"getStatus","summary":"Poll the status/code of an activation.","description":"Poll the status/code of an activation.","tags":["v1"],"x-status":"existing","parameters":[{"name":"action","in":"query","required":true,"schema":{"type":"string","enum":["getStatus"]},"example":"getStatus","description":"Fixed for this operation."},{"name":"api_key","in":"query","required":true,"schema":{"type":"string"},"example":"YOUR_API_KEY","description":"Your account API key. Placeholder shown — never a real key."},{"name":"id","in":"query","required":true,"schema":{"type":"string","example":"557860099"},"description":"Activation id."},{"name":"full_text","in":"query","required":false,"schema":{"type":"boolean","example":false},"description":"Return the full multi-word text segment instead of truncating to code:status."}],"responses":{"200":{"description":"success: No code received yet. | success_1: Code received, waiting on a retry/next-SMS decision. | success_2: Code delivered. | success_3: Activation was cancelled. | NO_ACTIVATION: Unknown activation id. | BAD_ACTION: Validation exception / unexpected error (self-status fallback).","content":{"text/plain":{"schema":{"type":"string"},"examples":{"success":{"summary":"success","description":"No code received yet.","value":"STATUS_WAIT_CODE"},"success_1":{"summary":"success_1","description":"Code received, waiting on a retry/next-SMS decision.","value":"STATUS_WAIT_RETRY:8522"},"success_2":{"summary":"success_2","description":"Code delivered.","value":"STATUS_OK:852508"},"success_3":{"summary":"success_3","description":"Activation was cancelled.","value":"ACCESS_CANCEL"},"NO_ACTIVATION":{"summary":"NO_ACTIVATION","description":"Unknown activation id.","value":"NO_ACTIVATION"},"BAD_ACTION":{"summary":"BAD_ACTION","description":"Validation exception / unexpected error (self-status fallback).","value":"BAD_ACTION"}}}}},"401":{"description":"BAD_KEY: Missing/invalid api_key. Checked by shared middleware before any action code runs. Becomes the {\"title\":\"BAD_KEY\",...} JSON envelope only under flag api_json_envelope_enabled AND format=json/*V2/*V3 intent.","content":{"text/plain":{"schema":{"type":"string"},"examples":{"BAD_KEY":{"summary":"BAD_KEY","description":"Missing/invalid api_key. Checked by shared middleware before any action code runs. Becomes the {\"title\":\"BAD_KEY\",...} JSON envelope only under flag api_json_envelope_enabled AND format=json/*V2/*V3 intent.","value":"BAD_KEY"}}}}}}},"post":{"operationId":"getStatus","summary":"Poll the status/code of an activation.","description":"Poll the status/code of an activation.","tags":["v1"],"x-status":"existing","parameters":[{"name":"action","in":"query","required":true,"schema":{"type":"string","enum":["getStatus"]},"example":"getStatus","description":"Fixed for this operation."},{"name":"api_key","in":"query","required":true,"schema":{"type":"string"},"example":"YOUR_API_KEY","description":"Your account API key. Placeholder shown — never a real key."},{"name":"id","in":"query","required":true,"schema":{"type":"string","example":"557860099"},"description":"Activation id."},{"name":"full_text","in":"query","required":false,"schema":{"type":"boolean","example":false},"description":"Return the full multi-word text segment instead of truncating to code:status."}],"responses":{"200":{"description":"success: No code received yet. | success_1: Code received, waiting on a retry/next-SMS decision. | success_2: Code delivered. | success_3: Activation was cancelled. | NO_ACTIVATION: Unknown activation id. | BAD_ACTION: Validation exception / unexpected error (self-status fallback).","content":{"text/plain":{"schema":{"type":"string"},"examples":{"success":{"summary":"success","description":"No code received yet.","value":"STATUS_WAIT_CODE"},"success_1":{"summary":"success_1","description":"Code received, waiting on a retry/next-SMS decision.","value":"STATUS_WAIT_RETRY:8522"},"success_2":{"summary":"success_2","description":"Code delivered.","value":"STATUS_OK:852508"},"success_3":{"summary":"success_3","description":"Activation was cancelled.","value":"ACCESS_CANCEL"},"NO_ACTIVATION":{"summary":"NO_ACTIVATION","description":"Unknown activation id.","value":"NO_ACTIVATION"},"BAD_ACTION":{"summary":"BAD_ACTION","description":"Validation exception / unexpected error (self-status fallback).","value":"BAD_ACTION"}}}}},"401":{"description":"BAD_KEY: Missing/invalid api_key. Checked by shared middleware before any action code runs. Becomes the {\"title\":\"BAD_KEY\",...} JSON envelope only under flag api_json_envelope_enabled AND format=json/*V2/*V3 intent.","content":{"text/plain":{"schema":{"type":"string"},"examples":{"BAD_KEY":{"summary":"BAD_KEY","description":"Missing/invalid api_key. Checked by shared middleware before any action code runs. Becomes the {\"title\":\"BAD_KEY\",...} JSON envelope only under flag api_json_envelope_enabled AND format=json/*V2/*V3 intent.","value":"BAD_KEY"}}}}}}}},"/stubs/handler_api.php?action=getStatusV2":{"get":{"operationId":"getStatusV2","summary":"Activation status as JSON (verificationType + sms block).","description":"Activation status as JSON (verificationType + sms block).\n\nGated by flag `api_get_status_v2_enabled` (currently ON in this environment). While OFF, this action returns plain-text `BAD_ACTION`, HTTP 200, byte-identical to an unknown action.","tags":["v2"],"x-status":"new","x-feature-flag":"api_get_status_v2_enabled","parameters":[{"name":"action","in":"query","required":true,"schema":{"type":"string","enum":["getStatusV2"]},"example":"getStatusV2","description":"Fixed for this operation."},{"name":"api_key","in":"query","required":true,"schema":{"type":"string"},"example":"YOUR_API_KEY","description":"Your account API key. Placeholder shown — never a real key."},{"name":"id","in":"query","required":true,"schema":{"type":"string","example":"557860099"},"description":"Activation id."}],"responses":{"200":{"description":"success: No code received yet. | success_1: Code delivered. There is no voice-call verification type in this system — verificationType is always 0 or 1.","content":{"application/json":{"schema":{"type":"object"},"examples":{"success":{"summary":"success","description":"No code received yet.","value":{"verificationType":0,"sms":null}},"success_1":{"summary":"success_1","description":"Code delivered. There is no voice-call verification type in this system — verificationType is always 0 or 1.","value":{"verificationType":1,"sms":{"dateTime":"2026-07-02T18:12:31+00:00","code":"852508","text":"Your Telegram code is 852508"}}}}}}},"401":{"description":"BAD_KEY: Missing/invalid api_key. Checked by shared middleware before any action code runs. Becomes the {\"title\":\"BAD_KEY\",...} JSON envelope only under flag api_json_envelope_enabled AND format=json/*V2/*V3 intent.","content":{"text/plain":{"schema":{"type":"string"},"examples":{"BAD_KEY":{"summary":"BAD_KEY","description":"Missing/invalid api_key. Checked by shared middleware before any action code runs. Becomes the {\"title\":\"BAD_KEY\",...} JSON envelope only under flag api_json_envelope_enabled AND format=json/*V2/*V3 intent.","value":"BAD_KEY"}}}}},"404":{"description":"NOT_FOUND: Unknown activation id, missing id, or any unexpected error (single documented error for this method).","content":{"application/json":{"schema":{"type":"object"},"examples":{"NOT_FOUND":{"summary":"NOT_FOUND","description":"Unknown activation id, missing id, or any unexpected error (single documented error for this method).","value":{"title":"NOT_FOUND","details":"Activation Not Found"}}}}}}}},"post":{"operationId":"getStatusV2","summary":"Activation status as JSON (verificationType + sms block).","description":"Activation status as JSON (verificationType + sms block).\n\nGated by flag `api_get_status_v2_enabled` (currently ON in this environment). While OFF, this action returns plain-text `BAD_ACTION`, HTTP 200, byte-identical to an unknown action.","tags":["v2"],"x-status":"new","x-feature-flag":"api_get_status_v2_enabled","parameters":[{"name":"action","in":"query","required":true,"schema":{"type":"string","enum":["getStatusV2"]},"example":"getStatusV2","description":"Fixed for this operation."},{"name":"api_key","in":"query","required":true,"schema":{"type":"string"},"example":"YOUR_API_KEY","description":"Your account API key. Placeholder shown — never a real key."},{"name":"id","in":"query","required":true,"schema":{"type":"string","example":"557860099"},"description":"Activation id."}],"responses":{"200":{"description":"success: No code received yet. | success_1: Code delivered. There is no voice-call verification type in this system — verificationType is always 0 or 1.","content":{"application/json":{"schema":{"type":"object"},"examples":{"success":{"summary":"success","description":"No code received yet.","value":{"verificationType":0,"sms":null}},"success_1":{"summary":"success_1","description":"Code delivered. There is no voice-call verification type in this system — verificationType is always 0 or 1.","value":{"verificationType":1,"sms":{"dateTime":"2026-07-02T18:12:31+00:00","code":"852508","text":"Your Telegram code is 852508"}}}}}}},"401":{"description":"BAD_KEY: Missing/invalid api_key. Checked by shared middleware before any action code runs. Becomes the {\"title\":\"BAD_KEY\",...} JSON envelope only under flag api_json_envelope_enabled AND format=json/*V2/*V3 intent.","content":{"text/plain":{"schema":{"type":"string"},"examples":{"BAD_KEY":{"summary":"BAD_KEY","description":"Missing/invalid api_key. Checked by shared middleware before any action code runs. Becomes the {\"title\":\"BAD_KEY\",...} JSON envelope only under flag api_json_envelope_enabled AND format=json/*V2/*V3 intent.","value":"BAD_KEY"}}}}},"404":{"description":"NOT_FOUND: Unknown activation id, missing id, or any unexpected error (single documented error for this method).","content":{"application/json":{"schema":{"type":"object"},"examples":{"NOT_FOUND":{"summary":"NOT_FOUND","description":"Unknown activation id, missing id, or any unexpected error (single documented error for this method).","value":{"title":"NOT_FOUND","details":"Activation Not Found"}}}}}}}}},"/stubs/handler_api.php?action=setStatus":{"get":{"operationId":"setStatus","summary":"Change the status of an activation (ready/retry/cancel/complete).","description":"Change the status of an activation (ready/retry/cancel/complete).\n\nThe response is always a plain status token, never a JSON envelope — use setStatusV2 if you need JSON.","tags":["v1"],"x-status":"existing","parameters":[{"name":"action","in":"query","required":true,"schema":{"type":"string","enum":["setStatus"]},"example":"setStatus","description":"Fixed for this operation."},{"name":"api_key","in":"query","required":true,"schema":{"type":"string"},"example":"YOUR_API_KEY","description":"Your account API key. Placeholder shown — never a real key."},{"name":"id","in":"query","required":true,"schema":{"type":"string","example":"557860099"},"description":"Activation id (activation_code)."},{"name":"status","in":"query","required":true,"schema":{"type":"integer","example":8},"description":"One of 1 (ACCESS_READY), 3 (ACCESS_RETRY_GET), 6 (ACCESS_ACTIVATION), 8 (ACCESS_CANCEL), or -1 (accepted as an alias of 8/cancel). [flag: api_setstatus_minus1_enabled]"}],"responses":{"200":{"description":"success: status=1 | success_1: status=3 | success_2: status=6 | success_3: status=8. | NO_ACTIVATION: Unknown activation id, or id is missing. | BAD_STATUS: Unsupported status value, or the state machine rejected the transition. | EARLY_CANCEL_DENIED: Cancel requested before the provider-defined minimum activation age.","content":{"text/plain":{"schema":{"type":"string"},"examples":{"success":{"summary":"success","description":"status=1","value":"ACCESS_READY"},"success_1":{"summary":"success_1","description":"status=3","value":"ACCESS_RETRY_GET"},"success_2":{"summary":"success_2","description":"status=6","value":"ACCESS_ACTIVATION"},"success_3":{"summary":"success_3","description":"status=8.","value":"ACCESS_CANCEL"},"NO_ACTIVATION":{"summary":"NO_ACTIVATION","description":"Unknown activation id, or id is missing.","value":"NO_ACTIVATION"},"BAD_STATUS":{"summary":"BAD_STATUS","description":"Unsupported status value, or the state machine rejected the transition.","value":"BAD_STATUS"},"EARLY_CANCEL_DENIED":{"summary":"EARLY_CANCEL_DENIED","description":"Cancel requested before the provider-defined minimum activation age.","value":"EARLY_CANCEL_DENIED"}}}}},"401":{"description":"BAD_KEY: Missing/invalid api_key. Checked by shared middleware before any action code runs. Becomes the {\"title\":\"BAD_KEY\",...} JSON envelope only under flag api_json_envelope_enabled AND format=json/*V2/*V3 intent.","content":{"text/plain":{"schema":{"type":"string"},"examples":{"BAD_KEY":{"summary":"BAD_KEY","description":"Missing/invalid api_key. Checked by shared middleware before any action code runs. Becomes the {\"title\":\"BAD_KEY\",...} JSON envelope only under flag api_json_envelope_enabled AND format=json/*V2/*V3 intent.","value":"BAD_KEY"}}}}}}},"post":{"operationId":"setStatus","summary":"Change the status of an activation (ready/retry/cancel/complete).","description":"Change the status of an activation (ready/retry/cancel/complete).\n\nThe response is always a plain status token, never a JSON envelope — use setStatusV2 if you need JSON.","tags":["v1"],"x-status":"existing","parameters":[{"name":"action","in":"query","required":true,"schema":{"type":"string","enum":["setStatus"]},"example":"setStatus","description":"Fixed for this operation."},{"name":"api_key","in":"query","required":true,"schema":{"type":"string"},"example":"YOUR_API_KEY","description":"Your account API key. Placeholder shown — never a real key."},{"name":"id","in":"query","required":true,"schema":{"type":"string","example":"557860099"},"description":"Activation id (activation_code)."},{"name":"status","in":"query","required":true,"schema":{"type":"integer","example":8},"description":"One of 1 (ACCESS_READY), 3 (ACCESS_RETRY_GET), 6 (ACCESS_ACTIVATION), 8 (ACCESS_CANCEL), or -1 (accepted as an alias of 8/cancel). [flag: api_setstatus_minus1_enabled]"}],"responses":{"200":{"description":"success: status=1 | success_1: status=3 | success_2: status=6 | success_3: status=8. | NO_ACTIVATION: Unknown activation id, or id is missing. | BAD_STATUS: Unsupported status value, or the state machine rejected the transition. | EARLY_CANCEL_DENIED: Cancel requested before the provider-defined minimum activation age.","content":{"text/plain":{"schema":{"type":"string"},"examples":{"success":{"summary":"success","description":"status=1","value":"ACCESS_READY"},"success_1":{"summary":"success_1","description":"status=3","value":"ACCESS_RETRY_GET"},"success_2":{"summary":"success_2","description":"status=6","value":"ACCESS_ACTIVATION"},"success_3":{"summary":"success_3","description":"status=8.","value":"ACCESS_CANCEL"},"NO_ACTIVATION":{"summary":"NO_ACTIVATION","description":"Unknown activation id, or id is missing.","value":"NO_ACTIVATION"},"BAD_STATUS":{"summary":"BAD_STATUS","description":"Unsupported status value, or the state machine rejected the transition.","value":"BAD_STATUS"},"EARLY_CANCEL_DENIED":{"summary":"EARLY_CANCEL_DENIED","description":"Cancel requested before the provider-defined minimum activation age.","value":"EARLY_CANCEL_DENIED"}}}}},"401":{"description":"BAD_KEY: Missing/invalid api_key. Checked by shared middleware before any action code runs. Becomes the {\"title\":\"BAD_KEY\",...} JSON envelope only under flag api_json_envelope_enabled AND format=json/*V2/*V3 intent.","content":{"text/plain":{"schema":{"type":"string"},"examples":{"BAD_KEY":{"summary":"BAD_KEY","description":"Missing/invalid api_key. Checked by shared middleware before any action code runs. Becomes the {\"title\":\"BAD_KEY\",...} JSON envelope only under flag api_json_envelope_enabled AND format=json/*V2/*V3 intent.","value":"BAD_KEY"}}}}}}}},"/stubs/handler_api.php?action=setStatusV2":{"get":{"operationId":"setStatusV2","summary":"Change activation status, JSON success/error envelope.","description":"Change activation status, JSON success/error envelope.\n\nGated by flag `api_set_status_v2_enabled` (currently ON in this environment). While OFF, this action returns plain-text `BAD_ACTION`, HTTP 200, byte-identical to an unknown action.","tags":["v2"],"x-status":"new","x-feature-flag":"api_set_status_v2_enabled","parameters":[{"name":"action","in":"query","required":true,"schema":{"type":"string","enum":["setStatusV2"]},"example":"setStatusV2","description":"Fixed for this operation."},{"name":"api_key","in":"query","required":true,"schema":{"type":"string"},"example":"YOUR_API_KEY","description":"Your account API key. Placeholder shown — never a real key."},{"name":"id","in":"query","required":true,"schema":{"type":"string","example":"557860099"},"description":"Activation id."},{"name":"status","in":"query","required":true,"schema":{"type":"integer","example":8},"description":"One of 1, 3, 6, 8, -1 (-1 is always accepted as an alias for 8/cancel in this JSON version, regardless of whether that alias is enabled on the older text-based setStatus)."}],"responses":{"200":{"description":"success: Status changed. | BAD_STATUS: Unsupported status value, or invalid/missing id.","content":{"application/json":{"schema":{"type":"object"},"examples":{"success":{"summary":"success","description":"Status changed.","value":{"status":"success"}},"BAD_STATUS":{"summary":"BAD_STATUS","description":"Unsupported status value, or invalid/missing id.","value":{"title":"BAD_STATUS","details":"Wrong status value"}}}}}},"401":{"description":"BAD_KEY: Missing/invalid api_key. Checked by shared middleware before any action code runs. Becomes the {\"title\":\"BAD_KEY\",...} JSON envelope only under flag api_json_envelope_enabled AND format=json/*V2/*V3 intent.","content":{"text/plain":{"schema":{"type":"string"},"examples":{"BAD_KEY":{"summary":"BAD_KEY","description":"Missing/invalid api_key. Checked by shared middleware before any action code runs. Becomes the {\"title\":\"BAD_KEY\",...} JSON envelope only under flag api_json_envelope_enabled AND format=json/*V2/*V3 intent.","value":"BAD_KEY"}}}}},"404":{"description":"NOT_FOUND: Unknown activation id.","content":{"application/json":{"schema":{"type":"object"},"examples":{"NOT_FOUND":{"summary":"NOT_FOUND","description":"Unknown activation id.","value":{"title":"NOT_FOUND","details":"Activation Not Found"}}}}}},"409":{"description":"EARLY_CANCEL_DENIED: Cancel requested too early.","content":{"application/json":{"schema":{"type":"object"},"examples":{"EARLY_CANCEL_DENIED":{"summary":"EARLY_CANCEL_DENIED","description":"Cancel requested too early.","value":{"title":"EARLY_CANCEL_DENIED","details":"Early cancel denied","info":{"minActivationTime":120}}}}}}}}},"post":{"operationId":"setStatusV2","summary":"Change activation status, JSON success/error envelope.","description":"Change activation status, JSON success/error envelope.\n\nGated by flag `api_set_status_v2_enabled` (currently ON in this environment). While OFF, this action returns plain-text `BAD_ACTION`, HTTP 200, byte-identical to an unknown action.","tags":["v2"],"x-status":"new","x-feature-flag":"api_set_status_v2_enabled","parameters":[{"name":"action","in":"query","required":true,"schema":{"type":"string","enum":["setStatusV2"]},"example":"setStatusV2","description":"Fixed for this operation."},{"name":"api_key","in":"query","required":true,"schema":{"type":"string"},"example":"YOUR_API_KEY","description":"Your account API key. Placeholder shown — never a real key."},{"name":"id","in":"query","required":true,"schema":{"type":"string","example":"557860099"},"description":"Activation id."},{"name":"status","in":"query","required":true,"schema":{"type":"integer","example":8},"description":"One of 1, 3, 6, 8, -1 (-1 is always accepted as an alias for 8/cancel in this JSON version, regardless of whether that alias is enabled on the older text-based setStatus)."}],"responses":{"200":{"description":"success: Status changed. | BAD_STATUS: Unsupported status value, or invalid/missing id.","content":{"application/json":{"schema":{"type":"object"},"examples":{"success":{"summary":"success","description":"Status changed.","value":{"status":"success"}},"BAD_STATUS":{"summary":"BAD_STATUS","description":"Unsupported status value, or invalid/missing id.","value":{"title":"BAD_STATUS","details":"Wrong status value"}}}}}},"401":{"description":"BAD_KEY: Missing/invalid api_key. Checked by shared middleware before any action code runs. Becomes the {\"title\":\"BAD_KEY\",...} JSON envelope only under flag api_json_envelope_enabled AND format=json/*V2/*V3 intent.","content":{"text/plain":{"schema":{"type":"string"},"examples":{"BAD_KEY":{"summary":"BAD_KEY","description":"Missing/invalid api_key. Checked by shared middleware before any action code runs. Becomes the {\"title\":\"BAD_KEY\",...} JSON envelope only under flag api_json_envelope_enabled AND format=json/*V2/*V3 intent.","value":"BAD_KEY"}}}}},"404":{"description":"NOT_FOUND: Unknown activation id.","content":{"application/json":{"schema":{"type":"object"},"examples":{"NOT_FOUND":{"summary":"NOT_FOUND","description":"Unknown activation id.","value":{"title":"NOT_FOUND","details":"Activation Not Found"}}}}}},"409":{"description":"EARLY_CANCEL_DENIED: Cancel requested too early.","content":{"application/json":{"schema":{"type":"object"},"examples":{"EARLY_CANCEL_DENIED":{"summary":"EARLY_CANCEL_DENIED","description":"Cancel requested too early.","value":{"title":"EARLY_CANCEL_DENIED","details":"Early cancel denied","info":{"minActivationTime":120}}}}}}}}}}}}