{
  "openapi": "3.1.0",
  "info": {
    "title": "Get SMS Developer API",
    "version": "1.1.2",
    "description": "Backend-to-backend SMS activation API. Not a drop-in5sim API. Bearer customer keys; no upstream credentials. Dynamic retail pricing includes site markup. Five active orders/account. 120requests/min/account+key,10purchases/min,30polls/min,30actions/min. Honor Retry-After. Keep stable purchase UUID on timeout/429/503. No browser CORS; no sandbox or callbacks. See /developers/integration.md for mandatory recovery algorithm. Durable backend example: /developers/example-client.py. UUID versions1–5 only; prefer v4. Five concurrent orders must share the30polls/minute budget. New purchases require explicit operator=any; fixed operators return409 PRICE_PROTECTION_REQUIRED before reservation. Legacy recorded orders retain their original request/replay semantics.\nFull endpoint reference: https://get-sms.io/developers. All examples are illustrative; sample UUIDs, price and timestamps are not live values. Never execute example purchases without an approved current quote and a durably saved intent UUID.",
    "contact": {
      "email": "support@get-sms.io"
    }
  },
  "servers": [
    {
      "url": "https://get-sms.io/api/v1"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/catalog": {
      "get": {
        "operationId": "getCatalog",
        "summary": "Read supported canonical identifiers",
        "description": "",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Catalog"
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  },
                  "required": [
                    "data",
                    "request_id"
                  ]
                },
                "example": {
                  "data": {
                    "currency": "USD",
                    "services": [
                      {
                        "id": "telegram",
                        "name": "Telegram"
                      }
                    ],
                    "countries": [
                      {
                        "id": "usa",
                        "name": "USA",
                        "dial_code": "+1"
                      },
                      {
                        "id": "england",
                        "name": "United Kingdom",
                        "dial_code": "+44"
                      }
                    ]
                  },
                  "request_id": "22222222-2222-4222-8222-222222222222"
                }
              }
            }
          },
          "400": {
            "description": "Request rejected; inspect error.code and message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Request rejected; inspect error.code and message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Request rejected; inspect error.code and message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Request rejected; inspect error.code and message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Request rejected; inspect error.code and message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "Request rejected; inspect error.code and message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. Honor Retry-After.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds before retry."
              }
            }
          },
          "503": {
            "description": "Service/provider unavailable. Recover same request; never create a new intent to retry.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/prices": {
      "get": {
        "operationId": "getPrices",
        "summary": "Read current Get SMS retail prices, including current site markup",
        "description": "Current site settings are read on every request. USD decimal strings. Stock is not guaranteed. Get SMS retail prices contain its markup; add your own resale margin separately. Unknown country/service identifiers are rejected with400 INVALID_REQUEST after catalog validation, before fetching prices. A supported selection without stock returns an empty prices array; catalog connectivity errors remain503.",
        "parameters": [
          {
            "name": "country",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "service",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Prices"
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  },
                  "required": [
                    "data",
                    "request_id"
                  ]
                },
                "example": {
                  "data": {
                    "currency": "USD",
                    "checked_at": "2026-10-20T12:00:00.000Z",
                    "prices": [
                      {
                        "country": "usa",
                        "service": "telegram",
                        "operator": "any",
                        "price": "1.2000",
                        "stock": 100,
                        "success_rate": 80
                      }
                    ]
                  },
                  "request_id": "22222222-2222-4222-8222-222222222222"
                }
              }
            }
          },
          "400": {
            "description": "Request rejected; inspect error.code and message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Request rejected; inspect error.code and message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Request rejected; inspect error.code and message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Request rejected; inspect error.code and message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Request rejected; inspect error.code and message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "Request rejected; inspect error.code and message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. Honor Retry-After.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds before retry."
              }
            }
          },
          "503": {
            "description": "Service/provider unavailable. Recover same request; never create a new intent to retry.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/balance": {
      "get": {
        "operationId": "getBalance",
        "summary": "Read customer USD balance and reservations",
        "description": "",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Balance"
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  },
                  "required": [
                    "data",
                    "request_id"
                  ]
                },
                "example": {
                  "data": {
                    "currency": "USD",
                    "balance": "10.0000",
                    "reserved": "1.2000",
                    "available": "8.8000"
                  },
                  "request_id": "22222222-2222-4222-8222-222222222222"
                }
              }
            }
          },
          "400": {
            "description": "Request rejected; inspect error.code and message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Request rejected; inspect error.code and message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Request rejected; inspect error.code and message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Request rejected; inspect error.code and message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Request rejected; inspect error.code and message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "Request rejected; inspect error.code and message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. Honor Retry-After.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds before retry."
              }
            }
          },
          "503": {
            "description": "Service/provider unavailable. Recover same request; never create a new intent to retry.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/orders": {
      "get": {
        "operationId": "listOrders",
        "summary": "Paginated account-wide history",
        "description": "",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100000,
              "default": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/History"
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  },
                  "required": [
                    "data",
                    "request_id"
                  ]
                },
                "example": {
                  "data": {
                    "page": 1,
                    "limit": 20,
                    "total": 1,
                    "orders": [
                      {
                        "id": "11111111-1111-4111-8111-111111111111",
                        "service": "telegram",
                        "country": "usa",
                        "operator": "any",
                        "phone": "+12025550123",
                        "status": "pending",
                        "currency": "USD",
                        "price": "1.2000",
                        "created_at": "2026-10-20T12:00:00.000Z",
                        "expires_at": "2026-10-20T12:15:00.000Z",
                        "cancel_available_at": "2026-10-20T12:01:00.000Z",
                        "last_checked_at": "2026-10-20T12:00:10.000Z",
                        "sms": []
                      }
                    ]
                  },
                  "request_id": "22222222-2222-4222-8222-222222222222"
                }
              }
            }
          },
          "400": {
            "description": "Request rejected; inspect error.code and message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Request rejected; inspect error.code and message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Request rejected; inspect error.code and message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Request rejected; inspect error.code and message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Request rejected; inspect error.code and message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "Request rejected; inspect error.code and message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. Honor Retry-After.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds before retry."
              }
            }
          },
          "503": {
            "description": "Service/provider unavailable. Recover same request; never create a new intent to retry.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "createOrder",
        "summary": "Create or recover one purchase intent",
        "description": "Persist one UUID with exact body before sending. Keys are scoped to the customer, not a credential. Same key/body returns recorded order; changed body gives409. Caller timeout must not create a new intent. Allow120s; recover with GET /requests/{key}. Number acquisition may take70s. Max five shared active orders. Failed preflight can leave no order; retry the same key/body only after recovery. No webhook/sandbox in v1. New fixed-operator requests are refused before reservation; existing recorded same-intent replays remain supported.",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "UUID versions 1–5; uppercase/lowercase accepted. Prefer UUIDv4."
          }
        ],
        "responses": {
          "202": {
            "description": "Recorded order; inspect status, not HTTP alone.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Order"
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  },
                  "required": [
                    "data",
                    "request_id"
                  ]
                },
                "example": {
                  "data": {
                    "id": "11111111-1111-4111-8111-111111111111",
                    "service": "telegram",
                    "country": "usa",
                    "operator": "any",
                    "phone": null,
                    "status": "purchasing",
                    "currency": "USD",
                    "price": "1.2000",
                    "created_at": "2026-10-20T12:00:00.000Z",
                    "expires_at": null,
                    "cancel_available_at": null,
                    "last_checked_at": null,
                    "sms": []
                  },
                  "request_id": "22222222-2222-4222-8222-222222222222"
                }
              }
            }
          },
          "400": {
            "description": "Request rejected; inspect error.code and message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Request rejected; inspect error.code and message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Request rejected; inspect error.code and message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Request rejected; inspect error.code and message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Request rejected; inspect error.code and message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "Request rejected; inspect error.code and message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. Honor Retry-After.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds before retry."
              }
            }
          },
          "503": {
            "description": "Service/provider unavailable. Recover same request; never create a new intent to retry.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateOrder"
              },
              "example": {
                "country": "usa",
                "service": "telegram",
                "operator": "any",
                "max_price": "1.2000"
              }
            }
          }
        }
      }
    },
    "/requests/{key}": {
      "get": {
        "operationId": "findRequestOrder",
        "summary": "Recover a purchase after a lost response",
        "description": "404 means no order is recorded yet, not proof the earlier request will never complete. Retry the original POST with exactly the same key/body.",
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "UUID versions 1–5; uppercase/lowercase accepted. Prefer UUIDv4."
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Order"
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  },
                  "required": [
                    "data",
                    "request_id"
                  ]
                },
                "example": {
                  "data": {
                    "id": "11111111-1111-4111-8111-111111111111",
                    "service": "telegram",
                    "country": "usa",
                    "operator": "any",
                    "phone": "+12025550123",
                    "status": "pending",
                    "currency": "USD",
                    "price": "1.2000",
                    "created_at": "2026-10-20T12:00:00.000Z",
                    "expires_at": "2026-10-20T12:15:00.000Z",
                    "cancel_available_at": "2026-10-20T12:01:00.000Z",
                    "last_checked_at": "2026-10-20T12:00:10.000Z",
                    "sms": []
                  },
                  "request_id": "22222222-2222-4222-8222-222222222222"
                }
              }
            }
          },
          "400": {
            "description": "Request rejected; inspect error.code and message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Request rejected; inspect error.code and message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Request rejected; inspect error.code and message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Request rejected; inspect error.code and message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Request rejected; inspect error.code and message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "Request rejected; inspect error.code and message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. Honor Retry-After.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds before retry."
              }
            }
          },
          "503": {
            "description": "Service/provider unavailable. Recover same request; never create a new intent to retry.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/orders/{id}": {
      "get": {
        "operationId": "getOrder",
        "summary": "Read owned order, phone and SMS",
        "description": "Poll every5seconds or slower, max30 polls/min/customer. May refresh provider state. Never treats an unknown purchase result as a rejection. All UTC timestamps are ISO8601. Unknown upstream identity returns saved reconciliation state without attempting an upstream refresh.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "UUID versions 1–5; uppercase/lowercase accepted. Prefer UUIDv4."
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Order"
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  },
                  "required": [
                    "data",
                    "request_id"
                  ]
                },
                "example": {
                  "data": {
                    "id": "11111111-1111-4111-8111-111111111111",
                    "service": "telegram",
                    "country": "usa",
                    "operator": "any",
                    "phone": "+12025550123",
                    "status": "received",
                    "currency": "USD",
                    "price": "1.2000",
                    "created_at": "2026-10-20T12:00:00.000Z",
                    "expires_at": "2026-10-20T12:15:00.000Z",
                    "cancel_available_at": "2026-10-20T12:01:00.000Z",
                    "last_checked_at": "2026-10-20T12:02:05.000Z",
                    "sms": [
                      {
                        "code": "012345",
                        "body": "Example verification code: 012345",
                        "received_at": "2026-10-20T12:02:00.000Z"
                      }
                    ]
                  },
                  "request_id": "22222222-2222-4222-8222-222222222222"
                }
              }
            }
          },
          "400": {
            "description": "Request rejected; inspect error.code and message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Request rejected; inspect error.code and message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Request rejected; inspect error.code and message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Request rejected; inspect error.code and message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Request rejected; inspect error.code and message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "Request rejected; inspect error.code and message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. Honor Retry-After.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds before retry."
              }
            }
          },
          "503": {
            "description": "Service/provider unavailable. Recover same request; never create a new intent to retry.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/orders/{id}/cancel": {
      "post": {
        "operationId": "cancelOrder",
        "summary": "Cancel order",
        "description": "Use after cancel_available_at and before SMS. Send {}. Cancellation is independently verified before unused funds are released. HTTP 200 does not prove a refund: inspect data.status and GET /balance. A recorded order can already be finished. If SMS arrives during cancellation, HTTP 409 ORDER_CONFLICT may follow a saved delivery; GET /orders/{id} using the same order UUID to retrieve received or finished state and its SMS. Do not create a new purchase or promise a refund from the cancellation response alone.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "UUID versions 1–5; uppercase/lowercase accepted. Prefer UUIDv4."
          }
        ],
        "responses": {
          "200": {
            "description": "Recorded order state after the action; not necessarily cancelled. An already completed order may return finished. Inspect data.status, SMS and GET /balance before concluding that a refund occurred.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Order"
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  },
                  "required": [
                    "data",
                    "request_id"
                  ]
                },
                "example": {
                  "data": {
                    "id": "11111111-1111-4111-8111-111111111111",
                    "service": "telegram",
                    "country": "usa",
                    "operator": "any",
                    "phone": "+12025550123",
                    "status": "cancelled",
                    "currency": "USD",
                    "price": "1.2000",
                    "created_at": "2026-10-20T12:00:00.000Z",
                    "expires_at": "2026-10-20T12:15:00.000Z",
                    "cancel_available_at": "2026-10-20T12:01:00.000Z",
                    "last_checked_at": "2026-10-20T12:00:10.000Z",
                    "sms": []
                  },
                  "request_id": "22222222-2222-4222-8222-222222222222"
                }
              }
            }
          },
          "400": {
            "description": "Request rejected; inspect error.code and message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Request rejected; inspect error.code and message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Request rejected; inspect error.code and message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "WAIT_REQUIRED includes retry_after and Retry-After seconds. ORDER_CONFLICT during cancellation can mean SMS was saved; GET /orders/{id} with the same UUID to retrieve received/finished state and readable SMS. Do not create a new purchase or assume a refund.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Present for WAIT_REQUIRED. Seconds before retry."
              }
            }
          },
          "413": {
            "description": "Request rejected; inspect error.code and message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "Request rejected; inspect error.code and message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. Honor Retry-After.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds before retry."
              }
            }
          },
          "503": {
            "description": "Service/provider unavailable. Recover same request; never create a new intent to retry.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false
              },
              "example": {}
            }
          }
        }
      }
    },
    "/orders/{id}/finish": {
      "post": {
        "operationId": "finishOrder",
        "summary": "Finish order",
        "description": "Finish only after SMS. The order price is charged. Repeating terminal actions returns recorded terminal state.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "UUID versions 1–5; uppercase/lowercase accepted. Prefer UUIDv4."
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Order"
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  },
                  "required": [
                    "data",
                    "request_id"
                  ]
                },
                "example": {
                  "data": {
                    "id": "11111111-1111-4111-8111-111111111111",
                    "service": "telegram",
                    "country": "usa",
                    "operator": "any",
                    "phone": "+12025550123",
                    "status": "finished",
                    "currency": "USD",
                    "price": "1.2000",
                    "created_at": "2026-10-20T12:00:00.000Z",
                    "expires_at": "2026-10-20T12:15:00.000Z",
                    "cancel_available_at": "2026-10-20T12:01:00.000Z",
                    "last_checked_at": "2026-10-20T12:00:10.000Z",
                    "sms": [
                      {
                        "code": "012345",
                        "body": "Example verification code: 012345",
                        "received_at": "2026-10-20T12:02:00.000Z"
                      }
                    ]
                  },
                  "request_id": "22222222-2222-4222-8222-222222222222"
                }
              }
            }
          },
          "400": {
            "description": "Request rejected; inspect error.code and message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Request rejected; inspect error.code and message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Request rejected; inspect error.code and message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Request rejected; inspect error.code and message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Request rejected; inspect error.code and message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "Request rejected; inspect error.code and message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. Honor Retry-After.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds before retry."
              }
            }
          },
          "503": {
            "description": "Service/provider unavailable. Recover same request; never create a new intent to retry.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false
              },
              "example": {}
            }
          }
        }
      }
    },
    "/orders/{id}/stop": {
      "post": {
        "operationId": "stopOrder",
        "summary": "Stop order",
        "description": "Request unassigned number search stop after15seconds. An in-flight purchase can still finish. No premature refund; once assigned use normal cancel rules.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "UUID versions 1–5; uppercase/lowercase accepted. Prefer UUIDv4."
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Order"
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  },
                  "required": [
                    "data",
                    "request_id"
                  ]
                },
                "example": {
                  "data": {
                    "id": "11111111-1111-4111-8111-111111111111",
                    "service": "telegram",
                    "country": "usa",
                    "operator": "any",
                    "phone": null,
                    "status": "purchasing",
                    "currency": "USD",
                    "price": "1.2000",
                    "created_at": "2026-10-20T12:00:00.000Z",
                    "expires_at": null,
                    "cancel_available_at": null,
                    "last_checked_at": null,
                    "sms": []
                  },
                  "request_id": "22222222-2222-4222-8222-222222222222"
                }
              }
            }
          },
          "400": {
            "description": "Request rejected; inspect error.code and message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Request rejected; inspect error.code and message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Request rejected; inspect error.code and message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "WAIT_REQUIRED includes retry_after and Retry-After seconds; other conflicts require inspecting current order state.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Present for WAIT_REQUIRED. Seconds before retry."
              }
            }
          },
          "413": {
            "description": "Request rejected; inspect error.code and message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "Request rejected; inspect error.code and message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. Honor Retry-After.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds before retry."
              }
            }
          },
          "503": {
            "description": "Service/provider unavailable. Recover same request; never create a new intent to retry.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false
              },
              "example": {}
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "gs_live_ followed by64hexadecimalcharacters. Server-side only. Create/revoke in /developers with customer login."
      }
    },
    "schemas": {
      "Money": {
        "type": "string",
        "pattern": "^\\d+\\.\\d{4}$",
        "examples": [
          "1.2000"
        ]
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              },
              "retry_after": {
                "type": "integer",
                "minimum": 1
              }
            },
            "required": [
              "code",
              "message"
            ],
            "description": "Structured error details."
          },
          "request_id": {
            "type": "string",
            "format": "uuid",
            "description": "Support correlation UUID; different for every HTTP request, including retries."
          }
        },
        "required": [
          "error",
          "request_id"
        ]
      },
      "Balance": {
        "type": "object",
        "properties": {
          "balance": {
            "$ref": "#/components/schemas/Money"
          },
          "reserved": {
            "$ref": "#/components/schemas/Money"
          },
          "available": {
            "$ref": "#/components/schemas/Money"
          },
          "currency": {
            "const": "USD",
            "description": "USD. All wallet and order money is expressed in USD."
          }
        },
        "required": [
          "balance",
          "reserved",
          "available",
          "currency"
        ]
      },
      "SMS": {
        "type": "object",
        "properties": {
          "code": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Code as a string (leading zeros preserved), or null if no code was extracted."
          },
          "body": {
            "type": "string",
            "description": "Original SMS text. May contain sensitive data; do not log or send to analytics."
          },
          "received_at": {
            "type": "string",
            "format": "date-time",
            "description": "SMS arrival timestamp in UTC. Use to distinguish multiple messages."
          }
        },
        "required": [
          "code",
          "body",
          "received_at"
        ]
      },
      "Order": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Get SMS order UUID. Store as a string; do not use an upstream numeric ID."
          },
          "service": {
            "type": "string",
            "description": "Canonical catalog service ID, for example telegram."
          },
          "country": {
            "type": "string",
            "description": "Canonical catalog country ID; USA is usa, United Kingdom is england. Türkiye is unavailable."
          },
          "operator": {
            "type": "string",
            "description": "Use any from a current quote for a new order. A physical operator is not guaranteed."
          },
          "phone": {
            "anyOf": [
              {
                "type": "string",
                "pattern": "^\\+[1-9][0-9]{6,14}$"
              },
              {
                "type": "null"
              }
            ],
            "description": "E.164 phone string with +. Null until a number is assigned. Never convert to a number."
          },
          "status": {
            "type": "string",
            "enum": [
              "created",
              "purchasing",
              "pending",
              "received",
              "reconciliation",
              "finished",
              "cancelled",
              "timeout",
              "banned",
              "failed"
            ],
            "description": "Order lifecycle state. finished can be automatic after saved SMS and provider closure; delivered SMS remains readable and is charged at the agreed price. HTTP success alone does not mean cancellation or refund."
          },
          "currency": {
            "const": "USD",
            "description": "USD. All wallet and order money is expressed in USD."
          },
          "price": {
            "$ref": "#/components/schemas/Money"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "Order creation time, ISO 8601 UTC."
          },
          "expires_at": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time"
              },
              {
                "type": "null"
              }
            ],
            "description": "Order expiry if known; null before assignment or when unavailable."
          },
          "cancel_available_at": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time"
              },
              {
                "type": "null"
              }
            ],
            "description": "Earliest cancellation time under the account policy; null if not known. Read this field instead of hard-coding a timer."
          },
          "last_checked_at": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time"
              },
              {
                "type": "null"
              }
            ],
            "description": "Most recent saved provider check; null if none."
          },
          "sms": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SMS"
            },
            "description": "Chronologically ordered SMS records. More than one SMS can arrive."
          }
        },
        "required": [
          "id",
          "service",
          "country",
          "operator",
          "phone",
          "status",
          "currency",
          "price",
          "created_at",
          "expires_at",
          "cancel_available_at",
          "last_checked_at",
          "sms"
        ],
        "description": "When valid SMS is stored and the provider closes an unresolved order, Get SMS settles it automatically as finished and charged, keeping SMS readable, including provider cancellation, timeout or ban. finished does not require a client /finish call. Historical terminal records are not rewritten. Read status and balance; HTTP success or conflict alone is not a refund."
      },
      "CreateOrder": {
        "type": "object",
        "properties": {
          "country": {
            "type": "string",
            "description": "Canonical catalog country ID; USA is usa, United Kingdom is england. Türkiye is unavailable."
          },
          "service": {
            "type": "string",
            "description": "Canonical catalog service ID, for example telegram."
          },
          "operator": {
            "type": "string",
            "description": "New intents must explicitly choose any from a current protected quote. No fixed operator guarantee. Exact replay of an already recorded legacy order keeps its original body.",
            "examples": [
              "any"
            ]
          },
          "max_price": {
            "type": "string",
            "pattern": "^(?!0+(?:\\.0+)?$)\\d{1,8}(\\.\\d{1,4})?$",
            "description": "Positive maximum Get SMS charge in USD. Fetch a live quote; no hard-coded prices."
          }
        },
        "required": [
          "country",
          "service",
          "operator",
          "max_price"
        ],
        "additionalProperties": false
      },
      "Catalog": {
        "type": "object",
        "properties": {
          "currency": {
            "const": "USD",
            "description": "USD. All wallet and order money is expressed in USD."
          },
          "services": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                }
              },
              "required": [
                "id",
                "name"
              ]
            },
            "description": "Canonical service identifiers and display names."
          },
          "countries": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "dial_code": {
                  "type": "string"
                }
              },
              "required": [
                "id",
                "name",
                "dial_code"
              ]
            },
            "description": "Canonical country identifiers, display names and dialing codes."
          }
        },
        "required": [
          "currency",
          "services",
          "countries"
        ]
      },
      "Prices": {
        "type": "object",
        "properties": {
          "currency": {
            "const": "USD",
            "description": "USD. All wallet and order money is expressed in USD."
          },
          "checked_at": {
            "type": "string",
            "format": "date-time",
            "description": "Time this price response was produced. Prices can change before purchase."
          },
          "prices": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "country": {
                  "type": "string"
                },
                "service": {
                  "type": "string"
                },
                "operator": {
                  "type": "string"
                },
                "price": {
                  "$ref": "#/components/schemas/Money"
                },
                "stock": {
                  "type": "number",
                  "minimum": 0
                },
                "success_rate": {
                  "type": "number"
                }
              },
              "required": [
                "country",
                "service",
                "operator",
                "price",
                "stock"
              ]
            },
            "description": "Available price-protected options. May be empty."
          }
        },
        "required": [
          "currency",
          "checked_at",
          "prices"
        ]
      },
      "History": {
        "type": "object",
        "properties": {
          "page": {
            "type": "integer",
            "description": "Current one-based page."
          },
          "limit": {
            "type": "integer",
            "description": "Page size: 1–50, default 20."
          },
          "total": {
            "type": "integer",
            "description": "Total account orders at query time."
          },
          "orders": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Order"
            },
            "description": "Page of saved orders belonging to this customer."
          }
        },
        "required": [
          "page",
          "limit",
          "total",
          "orders"
        ]
      }
    }
  }
}
