{"openapi":"3.1.0","info":{"title":"SMS-Act API","version":"1.0.0","summary":"Rent temporary phone numbers and receive SMS verification codes programmatically.","description":"## Authentication\nSend your Access Key in the `X-Access-Key` header. Generate it in the SMS-Act dashboard — it is shown **only once**.\n\n## Responses\nSuccess responses use HTTP 2xx and wrap the payload in `data`. Errors use HTTP 4xx/5xx and an `error` object.\n**Branch on `error.code`, never on `error.message`** — messages are for humans and may change.\n\n## Activation lifecycle\n`waiting` → `completed` (code received) or `cancelled` (cancelled by you, or expired after at most 20 minutes).\nCancelled activations are always fully refunded.\n\n## Polling\nPoll `GET /activations/{id}` no more often than every 3 seconds. Faster polling is not an error, but returns the last known state.\n\n## Idempotency\nSend an `Idempotency-Key` header with `POST /activations` so that network retries never create (and charge) a second activation.\n\n## Rate limits\n60 requests per 10 seconds per Access Key by default. Exceeding it returns `429 RATE_LIMITED` with a `Retry-After` header.\n"},"servers":[{"url":"https://sms-act.net/sms/open-api/v1"}],"security":[{"AccessKey":[]}],"tags":[{"name":"Account","description":"Balance of the account that owns the Access Key."},{"name":"Catalog","description":"Services and countries you can order, with prices and availability hints."},{"name":"Activations","description":"Order numbers, poll for codes, cancel for a refund."},{"name":"System","description":"Service health."}],"paths":{"/health":{"get":{"tags":["System"],"operationId":"getHealth","summary":"Health check","security":[],"responses":{"200":{"description":"Service is up.","content":{"application/json":{"schema":{"type":"object","required":["status","version"],"properties":{"status":{"type":"string","const":"ok"},"version":{"type":"string","examples":["1.5.0"]}}}}}}}}},"/account/balance":{"get":{"tags":["Account"],"operationId":"getBalance","summary":"Get account balance","responses":{"200":{"description":"Current balance.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Balance"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/services":{"get":{"tags":["Catalog"],"operationId":"listServices","summary":"List services that can be ordered","parameters":[{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PageSize"},{"name":"q","in":"query","description":"Case-insensitive search on service code or name.","schema":{"type":"string","maxLength":50}}],"responses":{"200":{"description":"A page of services.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"type":"object","required":["data","pagination"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Service"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/countries":{"get":{"tags":["Catalog"],"operationId":"listCountries","summary":"List countries","parameters":[{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PageSize"},{"name":"q","in":"query","description":"Case-insensitive search on English name or ISO code.","schema":{"type":"string","maxLength":50}}],"responses":{"200":{"description":"A page of countries.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"type":"object","required":["data","pagination"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Country"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/services/{service}/countries":{"get":{"tags":["Catalog"],"operationId":"listServiceCountries","summary":"List countries where a service can be ordered","description":"Includes the price and a best-effort availability hint. Not paginated.","parameters":[{"name":"service","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-zA-Z0-9_-]{1,20}$","examples":["wa"]}}],"responses":{"200":{"description":"Orderable countries for the service.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ServiceCountry"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/activations":{"post":{"tags":["Activations"],"operationId":"createActivation","summary":"Order a phone number","description":"Charges `price.amount` credits. Nothing is charged if the request fails.","parameters":[{"name":"Idempotency-Key","in":"header","description":"Strongly recommended. Replaying the same key within 24 hours returns the original activation instead of ordering again.","schema":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[\\x21-\\x7E]+$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["service","countryId"],"additionalProperties":false,"properties":{"service":{"type":"string","examples":["wa"]},"countryId":{"type":"integer","minimum":0,"examples":[6]}}}}}},"responses":{"200":{"description":"Idempotent replay — the activation created by an earlier request with the same `Idempotency-Key`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Idempotent-Replayed":{"schema":{"type":"string","const":"true"}}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Activation"}}}}}},"201":{"description":"Activation created.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ActivationCreated"}}},"example":{"data":{"id":"2348810953","status":"waiting","service":"wa","serviceName":"Whatsapp","countryId":6,"countryName":"Indonesia","phoneNumber":"+6281234567890","code":null,"price":{"amount":8,"currency":"credits"},"createdAt":"2026-10-08T09:30:00Z","expiresAt":"2026-10-08T09:50:00Z","completedAt":null,"cancelledAt":null}}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"502":{"$ref":"#/components/responses/UpstreamError"}}},"get":{"tags":["Activations"],"operationId":"listActivations","summary":"List activations created through the API","parameters":[{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PageSize"},{"name":"status","in":"query","schema":{"$ref":"#/components/schemas/ActivationStatus"}}],"responses":{"200":{"description":"A page of activations, newest first.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"type":"object","required":["data","pagination"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Activation"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"example":{"data":[{"id":"2348810953","status":"completed","service":"wa","serviceName":"Whatsapp","countryId":6,"countryName":"Indonesia","phoneNumber":"+6281234567890","code":"482915","price":{"amount":8,"currency":"credits"},"createdAt":"2026-10-08T09:30:00Z","expiresAt":"2026-10-08T09:50:00Z","completedAt":"2026-10-08T09:31:12Z","cancelledAt":null}],"pagination":{"page":1,"pageSize":20,"total":1}}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/activations/{id}":{"get":{"tags":["Activations"],"operationId":"getActivation","summary":"Get an activation (poll this for the code)","parameters":[{"$ref":"#/components/parameters/ActivationId"}],"responses":{"200":{"description":"The activation. `code` is set once `status` is `completed`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Activation"}}},"example":{"data":{"id":"2348810953","status":"completed","service":"wa","serviceName":"Whatsapp","countryId":6,"countryName":"Indonesia","phoneNumber":"+6281234567890","code":"482915","price":{"amount":8,"currency":"credits"},"createdAt":"2026-10-08T09:30:00Z","expiresAt":"2026-10-08T09:50:00Z","completedAt":"2026-10-08T09:31:12Z","cancelledAt":null}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/activations/{id}/cancel":{"post":{"tags":["Activations"],"operationId":"cancelActivation","summary":"Cancel an activation and get a full refund","description":"Allowed only while `waiting`. Cancelling an already cancelled activation succeeds.","parameters":[{"$ref":"#/components/parameters/ActivationId"}],"responses":{"200":{"description":"The cancelled activation.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Activation"}}},"example":{"data":{"id":"2348810953","status":"cancelled","service":"wa","serviceName":"Whatsapp","countryId":6,"countryName":"Indonesia","phoneNumber":"+6281234567890","code":null,"price":{"amount":8,"currency":"credits"},"createdAt":"2026-10-08T09:30:00Z","expiresAt":"2026-10-08T09:50:00Z","completedAt":null,"cancelledAt":"2026-10-08T09:35:00Z"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"502":{"$ref":"#/components/responses/UpstreamError"}}}}},"components":{"securitySchemes":{"AccessKey":{"type":"apiKey","in":"header","name":"X-Access-Key"}},"headers":{"X-Request-Id":{"description":"Unique request identifier. Include it when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"parameters":{"Page":{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},"PageSize":{"name":"pageSize","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},"ActivationId":{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9]{1,19}$","examples":["2348810953"]}}},"schemas":{"Money":{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"number","examples":[8]},"currency":{"type":"string","const":"credits"}}},"Balance":{"type":"object","required":["balance","currency","minBalanceToOrder"],"properties":{"balance":{"type":"number","description":"May contain decimals.","examples":[92]},"currency":{"type":"string","const":"credits"},"minBalanceToOrder":{"type":"number","description":"Minimum balance required to create an activation.","examples":[60]}}},"Pagination":{"type":"object","required":["page","pageSize","total"],"properties":{"page":{"type":"integer","minimum":1,"examples":[1]},"pageSize":{"type":"integer","minimum":1,"maximum":100,"examples":[20]},"total":{"type":"integer","minimum":0,"examples":[1]}}},"Service":{"type":"object","required":["code","name"],"properties":{"code":{"type":"string","examples":["wa"]},"name":{"type":"string","examples":["Whatsapp"]}}},"Country":{"type":"object","required":["id","iso2","name"],"properties":{"id":{"type":"integer","examples":[6]},"iso2":{"type":["string","null"],"description":"ISO 3166-1 alpha-2. Several countries may share a code (e.g. virtual and physical US numbers) — always order by `id`.","examples":["ID"]},"name":{"type":"string","examples":["Indonesia"]}}},"ServiceCountry":{"type":"object","required":["countryId","iso2","countryName","price","available"],"properties":{"countryId":{"type":"integer","examples":[6]},"iso2":{"type":["string","null"],"examples":["ID"]},"countryName":{"type":"string","examples":["Indonesia"]},"price":{"$ref":"#/components/schemas/Money"},"available":{"type":"boolean","examples":[true],"description":"Best-effort stock hint. `true` does not guarantee a number; `false` means ordering will most likely fail with `NO_NUMBERS_AVAILABLE`."}}},"ActivationStatus":{"type":"string","enum":["waiting","completed","cancelled"]},"Activation":{"type":"object","required":["id","status","service","serviceName","countryId","countryName","phoneNumber","code","price","createdAt","expiresAt","completedAt","cancelledAt"],"properties":{"id":{"type":"string","examples":["2348810953"]},"status":{"$ref":"#/components/schemas/ActivationStatus"},"service":{"type":"string","examples":["wa"]},"serviceName":{"type":"string","examples":["Whatsapp"]},"countryId":{"type":["integer","null"],"description":"Null only for a few legacy activations created before the country was recorded.","examples":[6]},"countryName":{"type":["string","null"],"description":"English name. Null in the same cases as `countryId`.","examples":["Indonesia"]},"phoneNumber":{"type":"string","description":"E.164 format.","examples":["+6281234567890"]},"code":{"type":["string","null"],"description":"The verification code, set when `status` is `completed`.","examples":["482915"]},"price":{"$ref":"#/components/schemas/Money"},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-08T09:30:00Z"]},"expiresAt":{"type":"string","format":"date-time","examples":["2026-10-08T09:50:00Z"],"description":"Upper bound: if no code arrives, the activation is cancelled and refunded automatically, usually after about 15 minutes and at the latest by this time."},"completedAt":{"type":["string","null"],"format":"date-time","examples":["2026-10-08T09:31:12Z"]},"cancelledAt":{"type":["string","null"],"format":"date-time","examples":["2026-10-08T09:35:00Z"]}}},"ActivationCreated":{"description":"Returned by `POST /activations`. Same as `Activation`, optionally with a `warning`.","allOf":[{"$ref":"#/components/schemas/Activation"},{"type":"object","properties":{"warning":{"$ref":"#/components/schemas/ActivationWarning"}}}]},"ActivationWarning":{"type":"object","description":"The activation was created and charged; this is only a heads-up. Do not retry because of it.","required":["code","failedToday","blockThreshold","message"],"properties":{"code":{"type":"string","const":"DAILY_FAILURE_WARNING"},"failedToday":{"type":"integer","examples":[3]},"blockThreshold":{"type":"integer","examples":[5],"description":"Ordering is blocked for the rest of the day once this many activations have failed."},"message":{"type":"string","examples":["3 activations have failed today. New activations will be blocked for the rest of the day after 5 failures."]}}},"ErrorCode":{"type":"string","enum":["INVALID_REQUEST","UNAUTHORIZED","INSUFFICIENT_BALANCE","ACCOUNT_SUSPENDED","DAILY_LIMIT_REACHED","ACTIVATIONS_RESTRICTED","ACTIVATION_NOT_FOUND","NOT_FOUND","NO_NUMBERS_AVAILABLE","PENDING_LIMIT_REACHED","ACTIVATION_NOT_CANCELLABLE","IDEMPOTENCY_IN_PROGRESS","UNSUPPORTED_SERVICE_COUNTRY","IDEMPOTENCY_KEY_REUSED","RATE_LIMITED","UPSTREAM_ERROR","INTERNAL_ERROR"],"x-error-catalog":[{"code":"INVALID_REQUEST","status":400,"retryable":false,"description":"A parameter is missing or malformed. details.field names it."},{"code":"UNAUTHORIZED","status":401,"retryable":false,"description":"The X-Access-Key header is missing, invalid or the key was revoked."},{"code":"INSUFFICIENT_BALANCE","status":402,"retryable":false,"description":"Balance is below the minimum required to create activations. Top up and retry."},{"code":"ACCOUNT_SUSPENDED","status":403,"retryable":false,"description":"The account that owns the key has been suspended."},{"code":"DAILY_LIMIT_REACHED","status":403,"retryable":false,"description":"Too many activations failed today (cancelled orders count as failures). Ordering resumes tomorrow. With the default limits, a new account that has never received a code can fail up to 14 times a day; see ACTIVATIONS_RESTRICTED."},{"code":"ACTIVATIONS_RESTRICTED","status":403,"retryable":false,"description":"Ordering is restricted for today due to an abnormal failure pattern: 15 or more failures with a success rate below 10%, for any account. cancelled orders (manual or automatic timeout) count as failures."},{"code":"ACTIVATION_NOT_FOUND","status":404,"retryable":false,"description":"The activation does not exist or belongs to another account."},{"code":"NOT_FOUND","status":404,"retryable":false,"description":"The endpoint or service does not exist."},{"code":"NO_NUMBERS_AVAILABLE","status":409,"retryable":true,"description":"No numbers right now for this service and country. Retry in a minute or try another country."},{"code":"PENDING_LIMIT_REACHED","status":409,"retryable":true,"description":"Too many activations are still waiting for a code (at most 3 at a time, counting orders placed on the website too). Wait for one to finish or cancel it."},{"code":"ACTIVATION_NOT_CANCELLABLE","status":409,"retryable":false,"description":"The activation already received a code and cannot be cancelled."},{"code":"IDEMPOTENCY_IN_PROGRESS","status":409,"retryable":true,"description":"A request with the same Idempotency-Key is still being processed."},{"code":"UNSUPPORTED_SERVICE_COUNTRY","status":422,"retryable":false,"description":"This service cannot be ordered in this country. See GET /services/{service}/countries."},{"code":"IDEMPOTENCY_KEY_REUSED","status":422,"retryable":false,"description":"The Idempotency-Key was already used with a different request body."},{"code":"RATE_LIMITED","status":429,"retryable":true,"description":"Too many requests: more than 60 per 10 seconds on one key, too many failed authentication attempts from one IP, or another order from the same account is still being created. Wait for the number of seconds in Retry-After."},{"code":"UPSTREAM_ERROR","status":502,"retryable":true,"description":"The number provider failed. Nothing was charged."},{"code":"INTERNAL_ERROR","status":500,"retryable":true,"description":"Unexpected server error. Nothing was charged. Retry with the same Idempotency-Key."}]},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable. Do not parse."},"requestId":{"type":"string"},"details":{"type":"object","description":"Optional machine-readable context, depending on `code`.","additionalProperties":true}}}}}},"responses":{"InvalidRequest":{"description":"`INVALID_REQUEST` — a parameter is missing or malformed (`details.field`).","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"`UNAUTHORIZED` — missing, invalid or revoked Access Key.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InsufficientBalance":{"description":"`INSUFFICIENT_BALANCE` — `details.balance`, `details.required`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"`ACCOUNT_SUSPENDED`. `POST /activations` may also return `DAILY_LIMIT_REACHED` (`details.failedToday`, `details.blockThreshold`) or `ACTIVATIONS_RESTRICTED`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"`ACTIVATION_NOT_FOUND` or `NOT_FOUND`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Conflict":{"description":"`NO_NUMBERS_AVAILABLE`, `PENDING_LIMIT_REACHED` (`details.pending`, `details.limit`), `ACTIVATION_NOT_CANCELLABLE` or `IDEMPOTENCY_IN_PROGRESS`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unprocessable":{"description":"`UNSUPPORTED_SERVICE_COUNTRY` or `IDEMPOTENCY_KEY_REUSED`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"`RATE_LIMITED` — wait `Retry-After` seconds.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"UpstreamError":{"description":"`UPSTREAM_ERROR` — the number provider failed. Nothing was charged and it is safe to retry.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"`INTERNAL_ERROR` — unexpected server error. Nothing was charged and it is safe to retry (use the same `Idempotency-Key` for `POST /activations`).","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}