Cloud Phone Numbers

Query NexSMS countries and projects, buy numbers, list purchased numbers, read SMS verification codes, and release a number to request a refund. Purchases take only the country, project, and quantity; the server charges the account balance at the current price. Each request is limited to 10 numbers.

A number is identified by its full tel string, which both reading SMS and releasing the number use. For the conventions shared by all service endpoints, see Service and authentication.

Agent/MCP interactive tasks wait 120 seconds for SMS by default. Confirmed invalid/unsupported numbers or receiving timeouts trigger eligible old-number release and automatic replacement, with at most 3 attempts including the first. Country/project changes must still match the site and required user constraints and do not reset the count. Reconcile unknown purchase outcomes against records and billing before further spending. HTTP endpoints do not implicitly run a replacement loop.

Search this page

Showing 6 of 6 endpoints

GET/sms/countries

List number countries

Lists the countries/regions where cloud phone numbers can be purchased; countryId is used to query projects and to purchase.

AuthBearer API Key

Request parameters

None

Response fields

Field	Type	Description
`contextId`	`string`	Sign-in and team context identifier for this request, usable as X-Nex-Service-Context in subsequent requests
`data`	`object[]`	Country list
`data[].countryId`	`number`	Country ID
`data[].countryName`	`string`	Country name

Response example

{
  "code": 0,
  "msg": "成功",
  "data": [
    {
      "countryId": 1,
      "countryName": "美国"
    },
    {
      "countryId": 44,
      "countryName": "英国"
    }
  ],
  "contextId": "a3f5c2e1b7d94c0e8f6a1b2c3d4e5f60a3f5c2e1b7d94c0e8f6a1b2c3d4e5f6"
}

GET/sms/stocks

Number projects and stock

Queries the projects (target apps or sites) available for SMS verification in a country, with real-time unit prices and stock.

AuthBearer API Key

Request parameters

Field	Type	Required	Description
`countryId`	`number`	Required	Country ID, from /sms/countries

Notes

Returns code 1 "countryId is required" when countryId is missing or not a positive integer.
Stock reflects only the state at query time and is not guaranteed to still be available at submission.

Response fields

Field	Type	Description
`contextId`	`string`	Sign-in and team context identifier for this request, usable as X-Nex-Service-Context in subsequent requests
`data`	`object[]`	Project list
`data[].countryId`	`number`	Country ID
`data[].countryName`	`string`	Country name
`data[].projectId`	`number`	Project ID, submitted when purchasing
`data[].projectName`	`string`	Project name, e.g. Telegram, WhatsApp
`data[].available`	`number`	Stock quantity at query time
`data[].price`	`number`	Upstream unit price
`data[].discountPrice`	`number`	Actual selling price; purchases are charged at this unit price
`data[].currency`	`string`	Currency
`data[].iconUrl`	`string`	Project icon URL, may be null

Response example

{
  "code": 0,
  "msg": "成功",
  "data": [
    {
      "countryId": 1,
      "countryName": "美国",
      "projectId": 1001,
      "projectName": "Telegram",
      "available": 128,
      "price": 0.25,
      "discountPrice": 0.3,
      "currency": "USDT",
      "iconUrl": "https://oss.nexbrowser.net/images/sms/telegram.png"
    }
  ],
  "contextId": "a3f5c2e1b7d94c0e8f6a1b2c3d4e5f60a3f5c2e1b7d94c0e8f6a1b2c3d4e5f6"
}

POST/sms/buy

Buy phone numbers

Purchases SMS verification numbers by country and project and charges the account balance, up to 10 per request.

AuthBearer API Key

Request parameters

Field	Type	Required	Description
`countryId`	`number`	Required	Country ID
`projectId`	`number`	Required	Project ID, from /sms/stocks
`quantity`	`number`	Optional	Purchase quantity, 1 to 10, default 1

Notes

After validating the country, project, and quantity, the request is submitted once. The server charges the current price and validates permission, balance, and stock; business errors pass through unchanged.
Only countryId, projectId, and quantity are accepted. The removed maxTotalPrice or any other unknown field returns code 1 without submitting a purchase. Missing countryId or projectId, or quantity outside 1 to 10, also returns code 1.
Batch purchases run one by one and are not atomic; if a later number fails, earlier ones may already have been purchased.
On success with data null, refresh /sms/records to get the numbers; on timeout or an unclear result, check /sms/records and /billing/trades first instead of purchasing again.

Response fields

Field	Type	Description
`contextId`	`string`	Sign-in and team context identifier for this request, usable as X-Nex-Service-Context in subsequent requests
`data`	`object[] \| null`	The server usually returns null; when an array of numbers is returned, the fields match /sms/records entries

Response example

{
  "code": 0,
  "msg": "成功",
  "data": null,
  "contextId": "a3f5c2e1b7d94c0e8f6a1b2c3d4e5f60a3f5c2e1b7d94c0e8f6a1b2c3d4e5f6"
}

GET/sms/records

Purchased number records

Pages through numbers the current user purchased in the current team, including state, expiry time, and received SMS messages.

AuthBearer API Key

Request parameters

Field	Type	Required	Description
`page`	`number`	Optional	Page number, default 1
`size`	`number`	Optional	Page size, default 20, values over 100 are treated as 100
`keyword`	`string`	Optional	Keyword, matches phone number, country name, or project name

Notes

If page or size is not a positive integer, the default is used and no error is returned.
When you need a number, check this endpoint first and purchase only if no usable number exists.

Response fields

Field	Type	Description
`contextId`	`string`	Sign-in and team context identifier for this request, usable as X-Nex-Service-Context in subsequent requests
`data.count`	`number`	Total number of matching records
`data.size`	`number`	Page size, echoes the request value
`data.page`	`number`	Current page number, echoes the request value
`data.total`	`number`	Total number of pages
`data.data`	`object[]`	Records on the current page
`data.data[].id`	`number`	Local record ID
`data.data[].orderNo`	`string`	Order number
`data.data[].tel`	`string`	Phone number, kept as the original string
`data.data[].countryId`	`number`	Country ID
`data.data[].countryName`	`string`	Country name
`data.data[].projectId`	`number`	Project ID
`data.data[].projectName`	`string`	Project name, i.e. the target app or site
`data.data[].price`	`number`	Unit price paid, USDT
`data.data[].state`	`number`	State: 0 waiting for SMS, 1 SMS received, 2 expired, -1 refunded
`data.data[].message`	`string`	JSON text of received SMS messages, newest first
`data.data[].product`	`string`	JSON text of the project snapshot at purchase time
`data.data[].expireTime`	`string`	Number expiry time
`data.data[].createdAt`	`string`	Creation time
`data.data[].updatedAt`	`string`	Update time

Response example

{
  "code": 0,
  "msg": "成功",
  "data": {
    "count": 1,
    "size": 20,
    "page": 1,
    "total": 1,
    "data": [
      {
        "id": 7101,
        "orderNo": "NSMS20261023000001",
        "tel": "+12025550123",
        "countryId": 1,
        "countryName": "美国",
        "projectId": 1001,
        "projectName": "Telegram",
        "price": 0.3,
        "state": 0,
        "message": "[]",
        "product": "{\"projectId\":1001,\"projectName\":\"Telegram\",\"discountPrice\":0.3}",
        "expireTime": "2026-10-23 10:20:00",
        "createdAt": "2026-10-23 10:00:00",
        "updatedAt": "2026-10-23 10:00:00"
      }
    ]
  },
  "contextId": "a3f5c2e1b7d94c0e8f6a1b2c3d4e5f60a3f5c2e1b7d94c0e8f6a1b2c3d4e5f6"
}

POST/sms/pull

Read number SMS

Actively pulls the latest SMS messages for a single number from upstream and returns the updated number record.

AuthBearer API Key

Request parameters

Field	Type	Required	Description
`tel`	`string`	Required	Full phone number, from tel in /sms/records

Notes

Missing tel returns code 1 "tel is required".
message is JSON text; some records are encoded twice, so if it is still a string after one parse, parse it again.
Whether an SMS has arrived is determined by the message list, not by state alone; poll every 5 to 15 seconds and stop after the number expires.

Response fields

Field	Type	Description
`contextId`	`string`	Sign-in and team context identifier for this request, usable as X-Nex-Service-Context in subsequent requests
`data`	`object \| null`	Number record, fields match /sms/records entries; may be null if the number does not exist
`data.tel`	`string`	Phone number, kept as the original string
`data.state`	`number`	State: 0 waiting for SMS, 1 SMS received, 2 expired, -1 refunded
`data.message`	`string`	JSON text of received SMS messages, newest first
`data.expireTime`	`string`	Number expiry time
`data.message[].code`	`string`	Verification code of each SMS after parsing message, may be empty
`data.message[].message`	`string`	SMS body
`data.message[].from`	`string`	Sender
`data.message[].receivedAt`	`string`	Received time

Response example

{
  "code": 0,
  "msg": "成功",
  "data": {
    "id": 7101,
    "orderNo": "NSMS20261023000001",
    "tel": "+12025550123",
    "countryId": 1,
    "countryName": "美国",
    "projectId": 1001,
    "projectName": "Telegram",
    "price": 0.3,
    "state": 1,
    "message": "[{\"msgId\":\"m-1\",\"number\":\"+12025550123\",\"app\":\"Telegram\",\"region\":\"US\",\"from\":\"Telegram\",\"message\":\"Telegram code: 12345\",\"code\":\"12345\",\"receivedAt\":\"2026-10-23 10:02:00\"}]",
    "product": "{\"projectId\":1001,\"projectName\":\"Telegram\",\"discountPrice\":0.3}",
    "expireTime": "2026-10-23 10:20:00",
    "createdAt": "2026-10-23 10:00:00",
    "updatedAt": "2026-10-23 10:00:00"
  },
  "contextId": "a3f5c2e1b7d94c0e8f6a1b2c3d4e5f60a3f5c2e1b7d94c0e8f6a1b2c3d4e5f6"
}

POST/sms/recover

Release number and request refund

Requests release and refund for a number still waiting for SMS; whether a refund is given and its amount are decided by the server and upstream.

AuthBearer API Key

Request parameters

Field	Type	Required	Description
`tel`	`string`	Required	Full phone number
`reason`	`string`	Required	Reason: no_code (no code received), rejected (number rejected), already_registered (already registered), cannot_send_code (site cannot send a code), other

Notes

Missing tel returns code 1 "tel is required"; a reason outside the enum returns "reason must be one of …".
Numbers that have received SMS cannot be refunded; the server returns -3004. Rules such as purchase duration are decided upstream; see msg for the specific reason.
The response does not mean the refund has been credited, and do not rely only on state in the response; refresh /sms/records and /billing/trades to confirm, and do not retry automatically on failure.

Response fields

Field	Type	Description
`contextId`	`string`	Sign-in and team context identifier for this request, usable as X-Nex-Service-Context in subsequent requests
`data`	`object \| null`	Number record, fields match /sms/records entries; may be null on repeated operations or when not in the waiting state

Response example

{
  "code": 0,
  "msg": "成功",
  "data": {
    "id": 7101,
    "orderNo": "NSMS20261023000001",
    "tel": "+12025550123",
    "countryId": 1,
    "countryName": "美国",
    "projectId": 1001,
    "projectName": "Telegram",
    "price": 0.3,
    "state": -1,
    "message": "[]",
    "product": "{\"projectId\":1001,\"projectName\":\"Telegram\",\"discountPrice\":0.3}",
    "expireTime": "2026-10-23 10:20:00",
    "createdAt": "2026-10-23 10:00:00",
    "updatedAt": "2026-10-23 10:00:00"
  },
  "contextId": "a3f5c2e1b7d94c0e8f6a1b2c3d4e5f60a3f5c2e1b7d94c0e8f6a1b2c3d4e5f6"
}