Numbers

Insertar

<a href="https://numestri.com/docs/es/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.

Parámetros

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.

Cuerpo de la solicitud application/x-www-form-urlencoded

servicestringobligatorio

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

countrystringobligatorio

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"
}

Ejemplos de código

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());

Respuestas

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

Ejemplo

{
  "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
}

Esquema

successobligatorio

numberintegerobligatorio

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

ccstringobligatorio

Country calling code.

phonenumberstringobligatorio

The national number, without the country code.

order_idstringobligatorio

Poll this with /sms/check.

countrystringobligatorio

country_codestringobligatorio

servicestringobligatorio

service_idstringobligatorio

poolinteger

Always null; kept for compatibility.

expires_inintegerobligatorio

Seconds until the order expires.

expirationintegerobligatorio

Unix seconds when the order expires.

messagestringobligatorio

coststringobligatorio

US dollars, as a fixed two-decimal string.

cost_in_centsintegerobligatorio

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).

Ejemplo

{
  "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

successobligatorio

errorsobject[]obligatorio

Mostrar parámetros secundarios

messagestringobligatorio

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

successobligatorio

messagestringobligatorio

Human-readable, safe to show.

typestringobligatorio

codestringobligatorio

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

402 Insufficient balance (type: BALANCE_ERROR).

Ejemplo

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

Esquema

successobligatorio

messagestringobligatorio

Human-readable, safe to show.

typestringobligatorio

codestringobligatorio

403 The API key is not valid.

Ejemplo

{
  "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"
    }
  ]
}

Esquema

successobligatorio

errorsobject[]obligatorio

Mostrar parámetros secundarios

messagestringobligatorio

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).

Ejemplo

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

Esquema

successobligatorio

messagestringobligatorio

Human-readable, safe to show.

typestringobligatorio

codestringobligatorio

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

Ejemplo

{
  "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

successobligatorio

errorsobject[]obligatorio

Mostrar parámetros secundarios

messagestringobligatorio

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

successobligatorio

messagestringobligatorio

Human-readable, safe to show.

typestringobligatorio

codestringobligatorio

{
  "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.

Ejemplo

{
  "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"
    }
  ]
}

Esquema

successobligatorio

errorsobject[]obligatorio

Mostrar parámetros secundarios

messagestringobligatorio

paramstring

The parameter at fault, when there is one.

descriptionstring

What the parameter should contain.

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

Ejemplo

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

Esquema

successobligatorio

messagestringobligatorio

Human-readable, safe to show.

typestringobligatorio

codestringobligatorio

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.

Parámetros

orderidstringqueryobligatorio

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

Ejemplos de código

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());

Respuestas

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

Ejemplo

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

Code received

statusobligatorio

smsstringobligatorio

The code.

full_smsstringobligatorio

The whole message.

expirationintegerobligatorio

Unix seconds.

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

Refunded

statusobligatorio

messageobligatorio

resendobligatorio

expirationintegerobligatorio

time_leftintegerobligatorio

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

Any other state

statusintegerobligatorio

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

resendobligatorio

expirationintegerobligatorio

Unix seconds.

time_leftintegerobligatorio

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.

Ejemplo

{
  "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"
    }
  ]
}

Esquema

successobligatorio

errorsobject[]obligatorio

Mostrar parámetros secundarios

messagestringobligatorio

paramstring

The parameter at fault, when there is one.

descriptionstring

What the parameter should contain.

403 The API key is not valid.

Ejemplo

{
  "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"
    }
  ]
}

Esquema

successobligatorio

errorsobject[]obligatorio

Mostrar parámetros secundarios

messagestringobligatorio

paramstring

The parameter at fault, when there is one.

descriptionstring

What the parameter should contain.

404 No such order of yours.

Ejemplo

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

Esquema

successobligatorio

messagestringobligatorio

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

Ejemplo

{
  "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"
    }
  ]
}

Esquema

successobligatorio

errorsobject[]obligatorio

Mostrar parámetros secundarios

messagestringobligatorio

paramstring

The parameter at fault, when there is one.

descriptionstring

What the parameter should contain.

500 Something went wrong on our side.

Ejemplo

{
  "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"
    }
  ]
}

Esquema

successobligatorio

errorsobject[]obligatorio

Mostrar parámetros secundarios

messagestringobligatorio

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.

Ejemplos de código

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());

Respuestas

200 Your open orders.

Ejemplo

[
  {
    "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
  }
]

Esquema

timestampstringobligatorio

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

coststringobligatorio

US dollars, as a fixed two-decimal string.

order_codestringobligatorio

phonenumberstringobligatorio

The full number, with country code.

codestringobligatorio

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

full_codestringobligatorio

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

short_namestringobligatorio

ISO country code.

servicestringobligatorio

statusstringobligatorio

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.

expiryintegerobligatorio

Unix seconds.

time_leftintegerobligatorio

Seconds left.

ready_at_estimateintegerobligatorio

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

Ejemplo

{
  "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"
    }
  ]
}

Esquema

successobligatorio

errorsobject[]obligatorio

Mostrar parámetros secundarios

messagestringobligatorio

paramstring

The parameter at fault, when there is one.

descriptionstring

What the parameter should contain.

403 The API key is not valid.

Ejemplo

{
  "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"
    }
  ]
}

Esquema

successobligatorio

errorsobject[]obligatorio

Mostrar parámetros secundarios

messagestringobligatorio

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.

Ejemplo

{
  "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"
    }
  ]
}

Esquema

successobligatorio

errorsobject[]obligatorio

Mostrar parámetros secundarios

messagestringobligatorio

paramstring

The parameter at fault, when there is one.

descriptionstring

What the parameter should contain.

500 Something went wrong on our side.

Ejemplo

{
  "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"
    }
  ]
}

Esquema

successobligatorio

errorsobject[]obligatorio

Mostrar parámetros secundarios

messagestringobligatorio

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.

Cuerpo de la solicitud application/x-www-form-urlencoded

orderidstringobligatorio

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"
}

Ejemplos de código

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());

Respuestas

200 Cancelled and refunded.

Ejemplo

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

Esquema

successobligatorio

messagestringobligatorio

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

Ejemplo

{
  "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

successobligatorio

errorsobject[]obligatorio

Mostrar parámetros secundarios

messagestringobligatorio

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

successobligatorio

messagestringobligatorio

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

403 The API key is not valid.

Ejemplo

{
  "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"
    }
  ]
}

Esquema

successobligatorio

errorsobject[]obligatorio

Mostrar parámetros secundarios

messagestringobligatorio

paramstring

The parameter at fault, when there is one.

descriptionstring

What the parameter should contain.

404 No such order of yours.

Ejemplo

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

Esquema

successobligatorio

messagestringobligatorio

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

Ejemplo

{
  "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
}

Esquema

successobligatorio

messagestringobligatorio

typeobligatorio

codeobligatorio

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.

Ejemplo

{
  "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"
    }
  ]
}

Esquema

successobligatorio

errorsobject[]obligatorio

Mostrar parámetros secundarios

messagestringobligatorio

paramstring

The parameter at fault, when there is one.

descriptionstring

What the parameter should contain.

500 Something went wrong on our side.

Ejemplo

{
  "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"
    }
  ]
}

Esquema

successobligatorio

errorsobject[]obligatorio

Mostrar parámetros secundarios

messagestringobligatorio

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.

Parámetros

Idempotency-Keystringheader

Cuerpo de la solicitud application/x-www-form-urlencoded

orderidstringobligatorio

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"
}

Ejemplos de código

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());

Respuestas

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

Ejemplo

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

Esquema

successobligatorio

messagestringobligatorio

order_idstringobligatorio

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

chargenumberobligatorio

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

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

Ejemplo

{
  "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

successobligatorio

errorsobject[]obligatorio

Mostrar parámetros secundarios

messagestringobligatorio

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

successobligatorio

messagestringobligatorio

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

402 Insufficient balance for a charged resend.

Ejemplo

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

Esquema

successobligatorio

messagestringobligatorio

403 The API key is not valid.

Ejemplo

{
  "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"
    }
  ]
}

Esquema

successobligatorio

errorsobject[]obligatorio

Mostrar parámetros secundarios

messagestringobligatorio

paramstring

The parameter at fault, when there is one.

descriptionstring

What the parameter should contain.

404 No such order of yours.

Ejemplo

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

Esquema

successobligatorio

messagestringobligatorio

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.

Ejemplo

{
  "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

successobligatorio

errorsobject[]obligatorio

Mostrar parámetros secundarios

messagestringobligatorio

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

successobligatorio

messagestringobligatorio

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

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

Ejemplo

{
  "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"
    }
  ]
}

Esquema

successobligatorio

errorsobject[]obligatorio

Mostrar parámetros secundarios

messagestringobligatorio

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.

Ejemplo

{
  "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

successobligatorio

errorsobject[]obligatorio

Mostrar parámetros secundarios

messagestringobligatorio

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

successobligatorio

messagestringobligatorio

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

500 Something went wrong on our side.

Ejemplo

{
  "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"
    }
  ]
}

Esquema

successobligatorio

errorsobject[]obligatorio

Mostrar parámetros secundarios

messagestringobligatorio

paramstring

The parameter at fault, when there is one.

descriptionstring

What the parameter should contain.

502 Supply error.

Ejemplo

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

Esquema

successobligatorio

messagestringobligatorio

503 Supply temporarily unavailable.

Ejemplo

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

Esquema

successobligatorio

messagestringobligatorio

Actualizado 16 oct 2026

¿Te resultó útil esta página?