Numbers

Embed

<a href="https://numestri.com/docs/ref-numbers"><img src="https://numestri.com/docs/_api/public/orgs/25229885-9620-4c08-bd2e-a0d0d74ac8b6/spaces/ef21e0c3-966d-4b03-b6d2-e66d449835d4/pages/ba976336-ca07-443a-8a59-10ff1819fa6b/social-card.svg?v=3e7ae33eec8b" alt="Numbers" width="600" height="315"></a>

POSThttps://numestri.com/api/v1/purchase/sms

Order a number

Order a one-time number for a platform in a country. Your balance is debited immediately and refunded automatically if no code arrives.

service and country must be exact ids (whatsapp, US); names and aliases are rejected with 400. Then choose how it is filled:

neither option nor provider: the best option in stock fills it, failing over to the next if it cannot deliver;
provider: only that provider fills it, its best option first; PROVIDER_UNAVAILABLE if it has nothing in stock;
option: exactly that offer at its listed price, or OPTION_GONE — never a substitute.

On failure, branch on type (OUT_OF_STOCK, BALANCE_ERROR, PRICE_NOT_FOUND, SERVICE_UNAVAILABLE) or on the finer code (see OrderFailure).

Safe to retry: send an Idempotency-Key header (or idempotency_key parameter) and a repeat returns the original order instead of buying another.

Counts towards the per-account purchase limit (60 a minute by default, shared with rentals, email accounts and resends); over it is a 429 RATE_LIMITED with Retry-After.

Also accepts GET, with the same parameters in the query string.

Parameters

Idempotency-Keystringheader

Optional. Any unique string (a UUID is ideal), up to 255 printable characters. Retrying with the same key returns the original purchase — same body, plus an Idempotent-Replayed: true header — instead of buying again, and charges nothing. A retry while the first request is still running is a 409 (param: idempotency_key); a retry after a failed purchase tries again. A key already used on a different endpoint (say, a purchase key sent to /sms/resend) is a 422. Keys are per account and do not expire. Send it as this header, or as the idempotency_key parameter (GET query string or POST body) if your client cannot set headers.

Request body application/x-www-form-urlencoded

servicestringrequired

Platform id, exactly as /catalog/platforms lists it (e.g. whatsapp). Names and aliases such as WhatsApp are rejected with 400.

countrystringrequired

ISO 3166-1 alpha-2 country code, exactly as /catalog/platforms/{platform}/countries lists it (e.g. US). Country names and lowercase codes are rejected with 400.

optionstring

An option id from …/providers/{provider}/options (or /request/price). Buys exactly that offer at its price, or fails with OPTION_GONE. Private numbers only.

providerstring

A provider id from …/countries/{country}/providers. Only that provider fills the order; PROVIDER_UNAVAILABLE if it has nothing in stock. Ignored when option is given. Private numbers only.

max_pricestring

Refuse (PRICE_ABOVE_MAX, type: PRICE_NOT_FOUND) if the price is above this, in dollars. Anything but a positive amount is a 400 (param: max_price).

number_classstring

private (default) or shared: a cheaper public inbox anyone can read. Case-insensitive.

private | shared = private

idempotency_keystring

Same as the Idempotency-Key header, for clients that cannot set headers (e.g. GET). The header wins when both are sent.

keystring

Your API key, if you send it in the body rather than a header or the query string.

{
  "service": "whatsapp",
  "country": "US",
  "option": "k3Jd9QmXa2Lp0cWe",
  "provider": "prv_k3Jd9QmXa2",
  "max_price": "0.75",
  "number_class": "private",
  "idempotency_key": "3f1c2a9e-8d4b-4c61-9a57-0b6f2e1d7c34",
  "key": "string"
}

Code samples

cURL

curl -X POST "https://numestri.com/api/v1/purchase/sms" \
  -H "Idempotency-Key: <value>" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d '{"service":"whatsapp","country":"US","option":"k3Jd9QmXa2Lp0cWe","provider":"prv_k3Jd9QmXa2","max_price":"0.75","number_class":"private","idempotency_key":"3f1c2a9e-8d4b-4c61-9a57-0b6f2e1d7c34","key":"string"}'

TypeScript

const res = await fetch('https://numestri.com/api/v1/purchase/sms', {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<value>',
    'Content-Type': 'application/x-www-form-urlencoded',
  },
  body: JSON.stringify({"service":"whatsapp","country":"US","option":"k3Jd9QmXa2Lp0cWe","provider":"prv_k3Jd9QmXa2","max_price":"0.75","number_class":"private","idempotency_key":"3f1c2a9e-8d4b-4c61-9a57-0b6f2e1d7c34","key":"string"}),
});
const data = await res.json();

Python

import requests

res = requests.request(
    "POST",
    "https://numestri.com/api/v1/purchase/sms",
    headers={
    "Idempotency-Key": "<value>",
    "Content-Type": "application/x-www-form-urlencoded",
    },
    json={"service": "whatsapp", "country": "US", "option": "k3Jd9QmXa2Lp0cWe", "provider": "prv_k3Jd9QmXa2", "max_price": "0.75", "number_class": "private", "idempotency_key": "3f1c2a9e-8d4b-4c61-9a57-0b6f2e1d7c34", "key": "string"},
)
data = res.json()

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	req, _ := http.NewRequest("POST", "https://numestri.com/api/v1/purchase/sms", strings.NewReader(`{"service":"whatsapp","country":"US","option":"k3Jd9QmXa2Lp0cWe","provider":"prv_k3Jd9QmXa2","max_price":"0.75","number_class":"private","idempotency_key":"3f1c2a9e-8d4b-4c61-9a57-0b6f2e1d7c34","key":"string"}`))
	req.Header.Set("Idempotency-Key", "<value>")
	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

PHP

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://numestri.com/api/v1/purchase/sms');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Idempotency-Key: <value>', 'Content-Type: application/x-www-form-urlencoded']);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"service":"whatsapp","country":"US","option":"k3Jd9QmXa2Lp0cWe","provider":"prv_k3Jd9QmXa2","max_price":"0.75","number_class":"private","idempotency_key":"3f1c2a9e-8d4b-4c61-9a57-0b6f2e1d7c34","key":"string"}');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Ruby

require 'net/http'
require 'uri'

uri = URI('https://numestri.com/api/v1/purchase/sms')
req = Net::HTTP::Post.new(uri)
req['Idempotency-Key'] = '<value>'
req['Content-Type'] = 'application/x-www-form-urlencoded'
req.body = '{"service":"whatsapp","country":"US","option":"k3Jd9QmXa2Lp0cWe","provider":"prv_k3Jd9QmXa2","max_price":"0.75","number_class":"private","idempotency_key":"3f1c2a9e-8d4b-4c61-9a57-0b6f2e1d7c34","key":"string"}'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
  http.request(req)
end
puts res.body

Java

import java.net.URI;
import java.net.http.*;
import java.net.http.HttpRequest.BodyPublishers;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://numestri.com/api/v1/purchase/sms"))
    .header("Idempotency-Key", "<value>")
    .header("Content-Type", "application/x-www-form-urlencoded")
    .method("POST", BodyPublishers.ofString("{\"service\":\"whatsapp\",\"country\":\"US\",\"option\":\"k3Jd9QmXa2Lp0cWe\",\"provider\":\"prv_k3Jd9QmXa2\",\"max_price\":\"0.75\",\"number_class\":\"private\",\"idempotency_key\":\"3f1c2a9e-8d4b-4c61-9a57-0b6f2e1d7c34\",\"key\":\"string\"}"))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Responses

200 The number. Poll order_id with /sms/check or /request/active.

Example

{
  "success": {},
  "number": 19550925198,
  "cc": "1",
  "phonenumber": "9550925198",
  "order_id": "JRJ5UEXS",
  "country": "United States",
  "country_code": "US",
  "service": "Telegram",
  "service_id": "telegram",
  "pool": null,
  "expires_in": 1198,
  "expiration": 1791943200,
  "message": "You have successfully ordered a Telegram number for 1.94.",
  "cost": "1.94",
  "cost_in_cents": 194
}

Schema

successrequired

numberintegerrequired

The full number, with country code, as a number.

ccstringrequired

Country calling code.

phonenumberstringrequired

The national number, without the country code.

order_idstringrequired

Poll this with /sms/check.

countrystringrequired

country_codestringrequired

servicestringrequired

service_idstringrequired

poolinteger

Always null; kept for compatibility.

expires_inintegerrequired

Seconds until the order expires.

expirationintegerrequired

Unix seconds when the order expires.

messagestringrequired

coststringrequired

US dollars, as a fixed two-decimal string.

cost_in_centsintegerrequired

The same amount in integer US cents.

400 A missing or invalid parameter (Error, param names it), or the price is above max_price (OrderFailure, code: PRICE_ABOVE_MAX).

Example

{
  "success": 0,
  "errors": [
    {
      "message": "You are missing a required parameter for this request.",
      "param": "country",
      "description": "Country code from /api/v1/catalog/platforms/{platform}/countries, e.g. US"
    }
  ]
}

Error

successrequired

errorsobject[]required

Show child parameters

messagestringrequired

paramstring

The parameter at fault, when there is one.

descriptionstring

What the parameter should contain.

{
  "success": 0,
  "errors": [
    {
      "message": "You are missing a required parameter for this request.",
      "param": "country",
      "description": "Country code from /api/v1/catalog/platforms/{platform}/countries, e.g. US"
    }
  ]
}

OrderFailure

successrequired

messagestringrequired

Human-readable, safe to show.

typestringrequired

codestringrequired

{
  "success": 0,
  "message": "That option is no longer available. Pick another.",
  "type": "OUT_OF_STOCK",
  "code": "OPTION_GONE"
}

402 Insufficient balance (type: BALANCE_ERROR).

Example

{
  "success": 0,
  "message": "That option is no longer available. Pick another.",
  "type": "OUT_OF_STOCK",
  "code": "OPTION_GONE"
}

Schema

successrequired

messagestringrequired

Human-readable, safe to show.

typestringrequired

codestringrequired

403 The API key is not valid.

Example

{
  "success": 0,
  "errors": [
    {
      "message": "You are missing a required parameter for this request.",
      "param": "country",
      "description": "Country code from /api/v1/catalog/platforms/{platform}/countries, e.g. US"
    }
  ]
}

Schema

successrequired

errorsobject[]required

Show child parameters

messagestringrequired

paramstring

The parameter at fault, when there is one.

descriptionstring

What the parameter should contain.

409 Out of stock (OUT_OF_STOCK, OPTION_GONE, PROVIDER_UNAVAILABLE) or the pairing is not sold (NOT_SOLD, type: PRICE_NOT_FOUND).

Example

{
  "success": 0,
  "message": "That option is no longer available. Pick another.",
  "type": "OUT_OF_STOCK",
  "code": "OPTION_GONE"
}

Schema

successrequired

messagestringrequired

Human-readable, safe to show.

typestringrequired

codestringrequired

429 Over the API rate limit (Error), or supply is rate-limiting (OrderFailure, code: RATE_LIMITED).

Example

{
  "success": 0,
  "errors": [
    {
      "message": "You are missing a required parameter for this request.",
      "param": "country",
      "description": "Country code from /api/v1/catalog/platforms/{platform}/countries, e.g. US"
    }
  ]
}

Error

successrequired

errorsobject[]required

Show child parameters

messagestringrequired

paramstring

The parameter at fault, when there is one.

descriptionstring

What the parameter should contain.

{
  "success": 0,
  "errors": [
    {
      "message": "You are missing a required parameter for this request.",
      "param": "country",
      "description": "Country code from /api/v1/catalog/platforms/{platform}/countries, e.g. US"
    }
  ]
}

OrderFailure

successrequired

messagestringrequired

Human-readable, safe to show.

typestringrequired

codestringrequired

{
  "success": 0,
  "message": "That option is no longer available. Pick another.",
  "type": "OUT_OF_STOCK",
  "code": "OPTION_GONE"
}

500 Something went wrong on our side.

Example

{
  "success": 0,
  "errors": [
    {
      "message": "You are missing a required parameter for this request.",
      "param": "country",
      "description": "Country code from /api/v1/catalog/platforms/{platform}/countries, e.g. US"
    }
  ]
}

Schema

successrequired

errorsobject[]required

Show child parameters

messagestringrequired

paramstring

The parameter at fault, when there is one.

descriptionstring

What the parameter should contain.

503 Supply temporarily unavailable (type: SERVICE_UNAVAILABLE, code: UNAVAILABLE).

Example

{
  "success": 0,
  "message": "That option is no longer available. Pick another.",
  "type": "OUT_OF_STOCK",
  "code": "OPTION_GONE"
}

Schema

successrequired

messagestringrequired

Human-readable, safe to show.

typestringrequired

codestringrequired

GEThttps://numestri.com/api/v1/sms/check

Poll one order

The state of one order. Always HTTP 200 for an order you own, whatever its state — branch on status, not the HTTP code. Prefer /request/active when polling more than one order.

Also accepts POST, with the same parameters in a form (application/x-www-form-urlencoded) or JSON body.

Parameters

orderidstringqueryrequired

The order_id returned by /purchase/sms (or /sms/resend).

Code samples

cURL

curl -X GET "https://numestri.com/api/v1/sms/check?orderid="

TypeScript

const res = await fetch('https://numestri.com/api/v1/sms/check?orderid=', {
  method: 'GET',
});
const data = await res.json();

Python

import requests

res = requests.request(
    "GET",
    "https://numestri.com/api/v1/sms/check?orderid=",
)
data = res.json()

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://numestri.com/api/v1/sms/check?orderid=", nil)
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

PHP

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://numestri.com/api/v1/sms/check?orderid=');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Ruby

require 'net/http'
require 'uri'

uri = URI('https://numestri.com/api/v1/sms/check?orderid=')
req = Net::HTTP::Get.new(uri)
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
  http.request(req)
end
puts res.body

Java

import java.net.URI;
import java.net.http.*;
import java.net.http.HttpRequest.BodyPublishers;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://numestri.com/api/v1/sms/check?orderid="))
    .GET()
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Responses

200 The order's state. status 3 carries the code.

Example

{
  "status": {},
  "sms": "140722",
  "full_sms": "140722 is your Telegram verification code.",
  "expiration": 0
}

Code received

statusrequired

smsstringrequired

The code.

full_smsstringrequired

The whole message.

expirationintegerrequired

Unix seconds.

{
  "status": {},
  "sms": "140722",
  "full_sms": "140722 is your Telegram verification code.",
  "expiration": 0
}

Refunded

statusrequired

messagerequired

resendrequired

expirationintegerrequired

time_leftintegerrequired

{
  "status": {},
  "message": {},
  "resend": {},
  "expiration": 0,
  "time_left": 0
}

Any other state

statusintegerrequired

1 pending (ready: request your code), 2 expired, 3 completed, 4 resend, 5 cancelled, 6 refunded, 7 processing, 8 activating. 7 and 8 are still in flight but NOT ready: the number cannot receive yet, and a code requested from the platform now is lost. Keep polling until it reads 1.

1 | 2 | 3 | 4 | 5 | 6 | 7 | 8

resendrequired

expirationintegerrequired

Unix seconds.

time_leftintegerrequired

Seconds left before the order expires. It runs from purchase, including while the number activates.

ready_at_estimateinteger

While the order is activating / processing (7 / 8): unix seconds when such a number is typically ready to receive, from recent orders. Null when the number is ready, or no estimate exists. An estimate, not a promise: wait for pending (1) before requesting the code.

{
  "status": 1,
  "resend": {},
  "expiration": 0,
  "time_left": 1188,
  "ready_at_estimate": null
}

400 A parameter (or the API key) is missing or invalid. param names it.

Example

{
  "success": 0,
  "errors": [
    {
      "message": "You are missing a required parameter for this request.",
      "param": "country",
      "description": "Country code from /api/v1/catalog/platforms/{platform}/countries, e.g. US"
    }
  ]
}

Schema

successrequired

errorsobject[]required

Show child parameters

messagestringrequired

paramstring

The parameter at fault, when there is one.

descriptionstring

What the parameter should contain.

403 The API key is not valid.

Example

{
  "success": 0,
  "errors": [
    {
      "message": "You are missing a required parameter for this request.",
      "param": "country",
      "description": "Country code from /api/v1/catalog/platforms/{platform}/countries, e.g. US"
    }
  ]
}

Schema

successrequired

errorsobject[]required

Show child parameters

messagestringrequired

paramstring

The parameter at fault, when there is one.

descriptionstring

What the parameter should contain.

404 No such order of yours.

Example

{
  "success": 0,
  "message": "We could not find this order!"
}

Schema

successrequired

messagestringrequired

429 Over the rate limit (32 requests per second per account by default). Wait Retry-After seconds.

Example

{
  "success": 0,
  "errors": [
    {
      "message": "You are missing a required parameter for this request.",
      "param": "country",
      "description": "Country code from /api/v1/catalog/platforms/{platform}/countries, e.g. US"
    }
  ]
}

Schema

successrequired

errorsobject[]required

Show child parameters

messagestringrequired

paramstring

The parameter at fault, when there is one.

descriptionstring

What the parameter should contain.

500 Something went wrong on our side.

Example

{
  "success": 0,
  "errors": [
    {
      "message": "You are missing a required parameter for this request.",
      "param": "country",
      "description": "Country code from /api/v1/catalog/platforms/{platform}/countries, e.g. US"
    }
  ]
}

Schema

successrequired

errorsobject[]required

Show child parameters

messagestringrequired

paramstring

The parameter at fault, when there is one.

descriptionstring

What the parameter should contain.

GEThttps://numestri.com/api/v1/request/active

Poll every open order

Every outstanding order (pending, or completed and not yet archived) in one call, newest first. The recommended polling endpoint when you have more than one order.

Also accepts POST, with the same parameters in a form (application/x-www-form-urlencoded) or JSON body.

Code samples

cURL

curl -X GET "https://numestri.com/api/v1/request/active"

TypeScript

const res = await fetch('https://numestri.com/api/v1/request/active', {
  method: 'GET',
});
const data = await res.json();

Python

import requests

res = requests.request(
    "GET",
    "https://numestri.com/api/v1/request/active",
)
data = res.json()

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://numestri.com/api/v1/request/active", nil)
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

PHP

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://numestri.com/api/v1/request/active');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Ruby

require 'net/http'
require 'uri'

uri = URI('https://numestri.com/api/v1/request/active')
req = Net::HTTP::Get.new(uri)
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
  http.request(req)
end
puts res.body

Java

import java.net.URI;
import java.net.http.*;
import java.net.http.HttpRequest.BodyPublishers;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://numestri.com/api/v1/request/active"))
    .GET()
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Responses

200 Your open orders.

Example

[
  {
    "timestamp": "2026-10-14 01:40:12",
    "cost": "1.94",
    "order_code": "JRJ5UEXS",
    "phonenumber": "19550925198",
    "code": "140722",
    "full_code": "string",
    "short_name": "US",
    "service": "Telegram",
    "status": "completed",
    "expiry": 0,
    "time_left": 1102,
    "ready_at_estimate": null
  }
]

Schema

timestampstringrequired

When it was ordered, UTC, YYYY-MM-DD HH:MM:SS.

coststringrequired

US dollars, as a fixed two-decimal string.

order_codestringrequired

phonenumberstringrequired

The full number, with country code.

codestringrequired

The code, or "0" while none has arrived.

full_codestringrequired

The whole message, or "" while none has arrived.

short_namestringrequired

ISO country code.

servicestringrequired

statusstringrequired

The OrderStatus by name. processing and activating are still in flight but not ready to receive: keep polling, and request the code from the platform only once it reads pending.

expiryintegerrequired

Unix seconds.

time_leftintegerrequired

Seconds left.

ready_at_estimateintegerrequired

400 A parameter (or the API key) is missing or invalid. param names it.

Example

{
  "success": 0,
  "errors": [
    {
      "message": "You are missing a required parameter for this request.",
      "param": "country",
      "description": "Country code from /api/v1/catalog/platforms/{platform}/countries, e.g. US"
    }
  ]
}

Schema

successrequired

errorsobject[]required

Show child parameters

messagestringrequired

paramstring

The parameter at fault, when there is one.

descriptionstring

What the parameter should contain.

403 The API key is not valid.

Example

{
  "success": 0,
  "errors": [
    {
      "message": "You are missing a required parameter for this request.",
      "param": "country",
      "description": "Country code from /api/v1/catalog/platforms/{platform}/countries, e.g. US"
    }
  ]
}

Schema

successrequired

errorsobject[]required

Show child parameters

messagestringrequired

paramstring

The parameter at fault, when there is one.

descriptionstring

What the parameter should contain.

429 Over the rate limit (32 requests per second per account by default). Wait Retry-After seconds.

Example

{
  "success": 0,
  "errors": [
    {
      "message": "You are missing a required parameter for this request.",
      "param": "country",
      "description": "Country code from /api/v1/catalog/platforms/{platform}/countries, e.g. US"
    }
  ]
}

Schema

successrequired

errorsobject[]required

Show child parameters

messagestringrequired

paramstring

The parameter at fault, when there is one.

descriptionstring

What the parameter should contain.

500 Something went wrong on our side.

Example

{
  "success": 0,
  "errors": [
    {
      "message": "You are missing a required parameter for this request.",
      "param": "country",
      "description": "Country code from /api/v1/catalog/platforms/{platform}/countries, e.g. US"
    }
  ]
}

Schema

successrequired

errorsobject[]required

Show child parameters

messagestringrequired

paramstring

The parameter at fault, when there is one.

descriptionstring

What the parameter should contain.

POSThttps://numestri.com/api/v1/sms/cancel

Cancel an order

Cancel an order and refund it in full. An order that already received a code cannot be refunded. A cancellation in the first moments after ordering may be refused with 409 CANCEL_TOO_EARLY; retry_after (and the Retry-After header) says how many seconds to wait when known.

Also accepts GET, with the same parameters in the query string.

Request body application/x-www-form-urlencoded

orderidstringrequired

The order to cancel.

keystring

Your API key, if you send it in the body rather than a header or the query string.

{
  "orderid": "JRJ5UEXS",
  "key": "string"
}

Code samples

cURL

curl -X POST "https://numestri.com/api/v1/sms/cancel" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d '{"orderid":"JRJ5UEXS","key":"string"}'

TypeScript

const res = await fetch('https://numestri.com/api/v1/sms/cancel', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
  },
  body: JSON.stringify({"orderid":"JRJ5UEXS","key":"string"}),
});
const data = await res.json();

Python

import requests

res = requests.request(
    "POST",
    "https://numestri.com/api/v1/sms/cancel",
    headers={
    "Content-Type": "application/x-www-form-urlencoded",
    },
    json={"orderid": "JRJ5UEXS", "key": "string"},
)
data = res.json()

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	req, _ := http.NewRequest("POST", "https://numestri.com/api/v1/sms/cancel", strings.NewReader(`{"orderid":"JRJ5UEXS","key":"string"}`))
	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

PHP

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://numestri.com/api/v1/sms/cancel');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/x-www-form-urlencoded']);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"orderid":"JRJ5UEXS","key":"string"}');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Ruby

require 'net/http'
require 'uri'

uri = URI('https://numestri.com/api/v1/sms/cancel')
req = Net::HTTP::Post.new(uri)
req['Content-Type'] = 'application/x-www-form-urlencoded'
req.body = '{"orderid":"JRJ5UEXS","key":"string"}'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
  http.request(req)
end
puts res.body

Java

import java.net.URI;
import java.net.http.*;
import java.net.http.HttpRequest.BodyPublishers;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://numestri.com/api/v1/sms/cancel"))
    .header("Content-Type", "application/x-www-form-urlencoded")
    .method("POST", BodyPublishers.ofString("{\"orderid\":\"JRJ5UEXS\",\"key\":\"string\"}"))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Responses

200 Cancelled and refunded.

Example

{
  "success": {},
  "message": "string"
}

Schema

successrequired

messagestringrequired

400 Missing orderid (Error), or the order cannot be cancelled: already refunded, a code already arrived, or refused (SimpleFailure).

Example

{
  "success": 0,
  "errors": [
    {
      "message": "You are missing a required parameter for this request.",
      "param": "country",
      "description": "Country code from /api/v1/catalog/platforms/{platform}/countries, e.g. US"
    }
  ]
}

Error

successrequired

errorsobject[]required

Show child parameters

messagestringrequired

paramstring

The parameter at fault, when there is one.

descriptionstring

What the parameter should contain.

{
  "success": 0,
  "errors": [
    {
      "message": "You are missing a required parameter for this request.",
      "param": "country",
      "description": "Country code from /api/v1/catalog/platforms/{platform}/countries, e.g. US"
    }
  ]
}

SimpleFailure

successrequired

messagestringrequired

{
  "success": 0,
  "message": "We could not find this order!"
}

403 The API key is not valid.

Example

{
  "success": 0,
  "errors": [
    {
      "message": "You are missing a required parameter for this request.",
      "param": "country",
      "description": "Country code from /api/v1/catalog/platforms/{platform}/countries, e.g. US"
    }
  ]
}

Schema

successrequired

errorsobject[]required

Show child parameters

messagestringrequired

paramstring

The parameter at fault, when there is one.

descriptionstring

What the parameter should contain.

404 No such order of yours.

Example

{
  "success": 0,
  "message": "We could not find this order!"
}

Schema

successrequired

messagestringrequired

409 Too early to cancel: the same call works once the wait is over.

Example

{
  "success": 0,
  "message": "This number can be cancelled in 40 seconds. Try again then.",
  "type": "CANCEL_TOO_EARLY",
  "code": "CANCEL_TOO_EARLY",
  "retry_after": 40
}

Schema

successrequired

messagestringrequired

typerequired

coderequired

retry_afterinteger

Seconds until a cancellation can be tried again, when known.

429 Over the rate limit (32 requests per second per account by default). Wait Retry-After seconds.

Example

{
  "success": 0,
  "errors": [
    {
      "message": "You are missing a required parameter for this request.",
      "param": "country",
      "description": "Country code from /api/v1/catalog/platforms/{platform}/countries, e.g. US"
    }
  ]
}

Schema

successrequired

errorsobject[]required

Show child parameters

messagestringrequired

paramstring

The parameter at fault, when there is one.

descriptionstring

What the parameter should contain.

500 Something went wrong on our side.

Example

{
  "success": 0,
  "errors": [
    {
      "message": "You are missing a required parameter for this request.",
      "param": "country",
      "description": "Country code from /api/v1/catalog/platforms/{platform}/countries, e.g. US"
    }
  ]
}

Schema

successrequired

errorsobject[]required

Show child parameters

messagestringrequired

paramstring

The parameter at fault, when there is one.

descriptionstring

What the parameter should contain.

POSThttps://numestri.com/api/v1/sms/resend

Request the SMS again

Ask for another SMS on the same number. This creates a NEW order: poll the returned order_id, not the one you passed in.

Some resends are charged (charge says how much). Safe to retry: send an Idempotency-Key header (or idempotency_key parameter) and a repeat returns the first resend instead of paying for another.

Resends count towards the per-account purchase limit (60 a minute by default); over it is a 429 with Retry-After.

Also accepts GET, with the same parameters in the query string.

Parameters

Idempotency-Keystringheader

Request body application/x-www-form-urlencoded

orderidstringrequired

The order to resend.

idempotency_keystring

Same as the Idempotency-Key header, for clients that cannot set headers (e.g. GET). The header wins when both are sent.

keystring

Your API key, if you send it in the body rather than a header or the query string.

{
  "orderid": "JRJ5UEXS",
  "idempotency_key": "3f1c2a9e-8d4b-4c61-9a57-0b6f2e1d7c34",
  "key": "string"
}

Code samples

cURL

curl -X POST "https://numestri.com/api/v1/sms/resend" \
  -H "Idempotency-Key: <value>" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d '{"orderid":"JRJ5UEXS","idempotency_key":"3f1c2a9e-8d4b-4c61-9a57-0b6f2e1d7c34","key":"string"}'

TypeScript

const res = await fetch('https://numestri.com/api/v1/sms/resend', {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<value>',
    'Content-Type': 'application/x-www-form-urlencoded',
  },
  body: JSON.stringify({"orderid":"JRJ5UEXS","idempotency_key":"3f1c2a9e-8d4b-4c61-9a57-0b6f2e1d7c34","key":"string"}),
});
const data = await res.json();

Python

import requests

res = requests.request(
    "POST",
    "https://numestri.com/api/v1/sms/resend",
    headers={
    "Idempotency-Key": "<value>",
    "Content-Type": "application/x-www-form-urlencoded",
    },
    json={"orderid": "JRJ5UEXS", "idempotency_key": "3f1c2a9e-8d4b-4c61-9a57-0b6f2e1d7c34", "key": "string"},
)
data = res.json()

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	req, _ := http.NewRequest("POST", "https://numestri.com/api/v1/sms/resend", strings.NewReader(`{"orderid":"JRJ5UEXS","idempotency_key":"3f1c2a9e-8d4b-4c61-9a57-0b6f2e1d7c34","key":"string"}`))
	req.Header.Set("Idempotency-Key", "<value>")
	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

PHP

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://numestri.com/api/v1/sms/resend');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Idempotency-Key: <value>', 'Content-Type: application/x-www-form-urlencoded']);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"orderid":"JRJ5UEXS","idempotency_key":"3f1c2a9e-8d4b-4c61-9a57-0b6f2e1d7c34","key":"string"}');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Ruby

require 'net/http'
require 'uri'

uri = URI('https://numestri.com/api/v1/sms/resend')
req = Net::HTTP::Post.new(uri)
req['Idempotency-Key'] = '<value>'
req['Content-Type'] = 'application/x-www-form-urlencoded'
req.body = '{"orderid":"JRJ5UEXS","idempotency_key":"3f1c2a9e-8d4b-4c61-9a57-0b6f2e1d7c34","key":"string"}'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
  http.request(req)
end
puts res.body

Java

import java.net.URI;
import java.net.http.*;
import java.net.http.HttpRequest.BodyPublishers;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://numestri.com/api/v1/sms/resend"))
    .header("Idempotency-Key", "<value>")
    .header("Content-Type", "application/x-www-form-urlencoded")
    .method("POST", BodyPublishers.ofString("{\"orderid\":\"JRJ5UEXS\",\"idempotency_key\":\"3f1c2a9e-8d4b-4c61-9a57-0b6f2e1d7c34\",\"key\":\"string\"}"))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Responses

200 The new order (or, replayed under the same Idempotency-Key, the first one, with Idempotent-Replayed: true).

Example

{
  "success": {},
  "message": "Your number has been requested again!",
  "order_id": "QRXWQWZK",
  "charge": 0
}

Schema

successrequired

messagestringrequired

order_idstringrequired

A NEW order id. Poll this one, not the original.

chargenumberrequired

What the resend cost, in dollars, as a number.

400 Missing orderid, a malformed Idempotency-Key, or this order cannot be resent.

Example

{
  "success": 0,
  "errors": [
    {
      "message": "You are missing a required parameter for this request.",
      "param": "country",
      "description": "Country code from /api/v1/catalog/platforms/{platform}/countries, e.g. US"
    }
  ]
}

Error

successrequired

errorsobject[]required

Show child parameters

messagestringrequired

paramstring

The parameter at fault, when there is one.

descriptionstring

What the parameter should contain.

{
  "success": 0,
  "errors": [
    {
      "message": "You are missing a required parameter for this request.",
      "param": "country",
      "description": "Country code from /api/v1/catalog/platforms/{platform}/countries, e.g. US"
    }
  ]
}

SimpleFailure

successrequired

messagestringrequired

{
  "success": 0,
  "message": "We could not find this order!"
}

402 Insufficient balance for a charged resend.

Example

{
  "success": 0,
  "message": "We could not find this order!"
}

Schema

successrequired

messagestringrequired

403 The API key is not valid.

Example

{
  "success": 0,
  "errors": [
    {
      "message": "You are missing a required parameter for this request.",
      "param": "country",
      "description": "Country code from /api/v1/catalog/platforms/{platform}/countries, e.g. US"
    }
  ]
}

Schema

successrequired

errorsobject[]required

Show child parameters

messagestringrequired

paramstring

The parameter at fault, when there is one.

descriptionstring

What the parameter should contain.

404 No such order of yours.

Example

{
  "success": 0,
  "message": "We could not find this order!"
}

Schema

successrequired

messagestringrequired

409 Nothing available to resend to (SimpleFailure), or A request with this Idempotency-Key is still in progress (Error, param: idempotency_key): retry in a few seconds.

Example

{
  "success": 0,
  "errors": [
    {
      "message": "You are missing a required parameter for this request.",
      "param": "country",
      "description": "Country code from /api/v1/catalog/platforms/{platform}/countries, e.g. US"
    }
  ]
}

Error

successrequired

errorsobject[]required

Show child parameters

messagestringrequired

paramstring

The parameter at fault, when there is one.

descriptionstring

What the parameter should contain.

{
  "success": 0,
  "errors": [
    {
      "message": "You are missing a required parameter for this request.",
      "param": "country",
      "description": "Country code from /api/v1/catalog/platforms/{platform}/countries, e.g. US"
    }
  ]
}

SimpleFailure

successrequired

messagestringrequired

{
  "success": 0,
  "message": "We could not find this order!"
}

422 This Idempotency-Key was already used for a different request (Error, param: idempotency_key).

Example

{
  "success": 0,
  "errors": [
    {
      "message": "You are missing a required parameter for this request.",
      "param": "country",
      "description": "Country code from /api/v1/catalog/platforms/{platform}/countries, e.g. US"
    }
  ]
}

Schema

successrequired

errorsobject[]required

Show child parameters

messagestringrequired

paramstring

The parameter at fault, when there is one.

descriptionstring

What the parameter should contain.

429 Over the API rate limit or the per-account purchase limit. Wait Retry-After seconds.

Example

{
  "success": 0,
  "errors": [
    {
      "message": "You are missing a required parameter for this request.",
      "param": "country",
      "description": "Country code from /api/v1/catalog/platforms/{platform}/countries, e.g. US"
    }
  ]
}

Error

successrequired

errorsobject[]required

Show child parameters

messagestringrequired

paramstring

The parameter at fault, when there is one.

descriptionstring

What the parameter should contain.

{
  "success": 0,
  "errors": [
    {
      "message": "You are missing a required parameter for this request.",
      "param": "country",
      "description": "Country code from /api/v1/catalog/platforms/{platform}/countries, e.g. US"
    }
  ]
}

SimpleFailure

successrequired

messagestringrequired

{
  "success": 0,
  "message": "We could not find this order!"
}

500 Something went wrong on our side.

Example

{
  "success": 0,
  "errors": [
    {
      "message": "You are missing a required parameter for this request.",
      "param": "country",
      "description": "Country code from /api/v1/catalog/platforms/{platform}/countries, e.g. US"
    }
  ]
}

Schema

successrequired

errorsobject[]required

Show child parameters

messagestringrequired

paramstring

The parameter at fault, when there is one.

descriptionstring

What the parameter should contain.

502 Supply error.

Example

{
  "success": 0,
  "message": "We could not find this order!"
}

Schema

successrequired

messagestringrequired

503 Supply temporarily unavailable.

Example

{
  "success": 0,
  "message": "We could not find this order!"
}

Schema

successrequired

messagestringrequired

Updated Oct 16, 2026

Was this page helpful?