asms

Get the current wallet balance for the authenticated account.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

Get the retail price per OTP activation for a service in a country. Omit `service` to list prices for every available service.

{
  "type": "object",
  "properties": {
    "country": {
      "type": "string",
      "description": "Number pool to order from: \"us1\" = Non-VoIP AT&T (real carrier line, for strict services like WhatsApp/Telegram/Google), \"us\" = VoIP High Quality (lowest price, works for most signups), \"uk\" = United Kingdom (+44), \"au\" = Australia (+61)."
    },
    "service": {
      "type": "string",
      "description": "Service slug to receive the OTP for (e.g. \"google\", \"telegram\", \"whatsapp\")."
    }
  },
  "required": [
    "country"
  ],
  "additionalProperties": false
}

Get how many numbers are in stock for a service in a country. Omit `service` to list stock for every available service.

{
  "type": "object",
  "properties": {
    "country": {
      "type": "string",
      "description": "Number pool to order from: \"us1\" = Non-VoIP AT&T (real carrier line, for strict services like WhatsApp/Telegram/Google), \"us\" = VoIP High Quality (lowest price, works for most signups), \"uk\" = United Kingdom (+44), \"au\" = Australia (+61)."
    },
    "service": {
      "type": "string",
      "description": "Service slug to receive the OTP for (e.g. \"google\", \"telegram\", \"whatsapp\")."
    }
  },
  "required": [
    "country"
  ],
  "additionalProperties": false
}

Buy a number to receive an OTP: allocates a number, debits the wallet, and returns an orderId + phoneNumber. Then poll with poll_sms. If no code arrives, do NOT cancel to retry: simply call create_otp_order again for a fresh number and keep polling that one. Unfilled orders auto-refund within 10 minutes, so you only pay for codes that actually land and there is no penalty for ordering repeatedly. When a service keeps rejecting codes, order on the "us1" (Non-VoIP AT&T) pool, which has the highest delivery rate. WARNING: this spends real wallet balance.

{
  "type": "object",
  "properties": {
    "country": {
      "type": "string",
      "description": "Number pool to order from: \"us1\" = Non-VoIP AT&T (real carrier line, for strict services like WhatsApp/Telegram/Google), \"us\" = VoIP High Quality (lowest price, works for most signups), \"uk\" = United Kingdom (+44), \"au\" = Australia (+61)."
    },
    "service": {
      "type": "string",
      "description": "Service slug to receive the OTP for (e.g. \"google\", \"telegram\", \"whatsapp\")."
    }
  },
  "required": [
    "country",
    "service"
  ],
  "additionalProperties": false
}

Check for the SMS / OTP code on an order. Returns the code once it has arrived, otherwise an empty result: poll again after a few seconds. If nothing lands after a minute or two, the fastest path is to order a fresh number with create_otp_order (prefer the "us1" Non-VoIP pool) and leave the original: it auto-refunds within 10 minutes. Never cancel just to retry, and there is no charge for ordering again, you only pay for codes that arrive.

{
  "type": "object",
  "properties": {
    "orderId": {
      "type": "string",
      "description": "The orderId from create_otp_order."
    }
  },
  "required": [
    "orderId"
  ],
  "additionalProperties": false
}

List recent OTP orders for the account (awaiting a code or already received).

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "number",
      "description": "Max orders to return (default 50, max 1000)."
    }
  },
  "additionalProperties": false
}

Rarely needed. To retry a verification do NOT cancel: just call create_otp_order again, because every unfilled order auto-refunds within 10 minutes on its own, and cancel is blocked for the first 10 minutes anyway. Only use this to release an order you are certain you no longer need once its 10-minute hold has passed.

{
  "type": "object",
  "properties": {
    "orderId": {
      "type": "string",
      "description": "The orderId from create_otp_order."
    }
  },
  "required": [
    "orderId"
  ],
  "additionalProperties": false
}

List the rental periods and prices for a country (1 day to 12 months). A rented number is yours for the whole period and receives every SMS sent to it, unlike an OTP order, which is for one code. Omit `country` to list the countries numbers can be rented in.

{
  "type": "object",
  "properties": {
    "country": {
      "type": "string",
      "enum": [
        "us",
        "uk",
        "ca",
        "au",
        "es",
        "se",
        "de",
        "nl",
        "it",
        "pl",
        "fi",
        "pt",
        "be",
        "at",
        "ch",
        "cz",
        "si",
        "lt",
        "mx",
        "hk",
        "il",
        "za"
      ],
      "description": "Country to rent a number in: \"us\" (United States), \"uk\" (United Kingdom), \"ca\" (Canada), \"au\" (Australia), \"es\" (Spain), \"se\" (Sweden), \"de\" (Germany), \"nl\" (Netherlands), \"it\" (Italy), \"pl\" (Poland), \"fi\" (Finland), \"pt\" (Portugal), \"be\" (Belgium), \"at\" (Austria), \"ch\" (Switzerland), \"cz\" (Czechia), \"si\" (Slovenia), \"lt\" (Lithuania), \"mx\" (Mexico), \"hk\" (Hong Kong), \"il\" (Israel), \"za\" (South Africa)."
    }
  },
  "additionalProperties": false
}

Rent a phone number in a country for a period (get the periods and prices from get_rental_offers first). Debits the wallet and returns the number and when the rental ends. Read its SMS with read_rental_sms. WARNING: this spends real wallet balance; confirm the country, period and price with the user first.

{
  "type": "object",
  "properties": {
    "country": {
      "type": "string",
      "enum": [
        "us",
        "uk",
        "ca",
        "au",
        "es",
        "se",
        "de",
        "nl",
        "it",
        "pl",
        "fi",
        "pt",
        "be",
        "at",
        "ch",
        "cz",
        "si",
        "lt",
        "mx",
        "hk",
        "il",
        "za"
      ],
      "description": "Country to rent a number in: \"us\" (United States), \"uk\" (United Kingdom), \"ca\" (Canada), \"au\" (Australia), \"es\" (Spain), \"se\" (Sweden), \"de\" (Germany), \"nl\" (Netherlands), \"it\" (Italy), \"pl\" (Poland), \"fi\" (Finland), \"pt\" (Portugal), \"be\" (Belgium), \"at\" (Austria), \"ch\" (Switzerland), \"cz\" (Czechia), \"si\" (Slovenia), \"lt\" (Lithuania), \"mx\" (Mexico), \"hk\" (Hong Kong), \"il\" (Israel), \"za\" (South Africa)."
    },
    "period": {
      "type": "string",
      "enum": [
        "oneDay",
        "oneWeek",
        "oneMonth",
        "threeMonths",
        "sixMonths",
        "twelveMonths"
      ],
      "description": "Rental period: \"oneDay\" (1 day), \"oneWeek\" (1 week), \"oneMonth\" (1 month), \"threeMonths\" (3 months), \"sixMonths\" (6 months), \"twelveMonths\" (12 months). Not every period is on sale in every country: check get_rental_offers."
    }
  },
  "required": [
    "country",
    "period"
  ],
  "additionalProperties": false
}

List the account's rented numbers with their country, period and end date. Ended rentals are left out unless `includeEnded` is true.

{
  "type": "object",
  "properties": {
    "includeEnded": {
      "type": "boolean",
      "description": "Also list rentals that have ended (default false)."
    }
  },
  "additionalProperties": false
}

Read the SMS a rented number has received during this rental, newest first. Poll again every few seconds while waiting for a message.

{
  "type": "object",
  "properties": {
    "number": {
      "type": "string",
      "description": "The rented number, as rent_number or list_rentals gave it (\"+\", spaces and dashes are ignored)."
    }
  },
  "required": [
    "number"
  ],
  "additionalProperties": false
}

Cancel a rented number and refund it. Only possible between 5 and 120 minutes after renting, and only if the number has received no SMS; after that the rental runs to its end date.

{
  "type": "object",
  "properties": {
    "number": {
      "type": "string",
      "description": "The rented number, as rent_number or list_rentals gave it (\"+\", spaces and dashes are ignored)."
    }
  },
  "required": [
    "number"
  ],
  "additionalProperties": false
}