Rentals

Embed

<a href="https://numestri.com/docs/ref-rentals"><img src="https://numestri.com/docs/_api/public/orgs/25229885-9620-4c08-bd2e-a0d0d74ac8b6/spaces/ef21e0c3-966d-4b03-b6d2-e66d449835d4/pages/8ec479eb-2d8f-4f1d-aceb-ed23ab344344/social-card.svg?v=3e7ae33eec8b" alt="Rentals" width="600" height="315"></a>

GEThttps://numestri.com/api/v1/rental/retrieve_all

Countries with rentals

Every country a long-term number can be rented in, by ISO code. Price a country with /rental/retrieve_pricing.

No API key needed. Without one you get public list prices, rate-limited per IP address. Send your key to get the prices for your account (which can differ from the public list) and the per-account limit; an invalid key is still refused with 403.

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/rental/retrieve_all"

TypeScript

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

Python

import requests

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

package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://numestri.com/api/v1/rental/retrieve_all", 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/rental/retrieve_all');
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/rental/retrieve_all')
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/rental/retrieve_all"))
    .GET()
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Responses

200 Rental countries.

Example

{
  "success": {},
  "data": [
    {
      "id": "string",
      "name": "string"
    }
  ]
}

Schema

success

dataNamedId[]

Show child parameters

idstringrequired

namestringrequired

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.

GEThttps://numestri.com/api/v1/rental/retrieve_platforms

Platforms with reserved rentals in a country

Platforms with numbers reserved for them in a country, sorted by name, each with its lowest rental price. Pass an id as service to /rental/retrieve_pricing and /purchase/rental.

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

Parameters

idstringqueryrequired

ISO country code from /rental/retrieve_all.

Code samples

cURL

curl -X GET "https://numestri.com/api/v1/rental/retrieve_platforms?id="

TypeScript

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

Python

import requests

res = requests.request(
    "GET",
    "https://numestri.com/api/v1/rental/retrieve_platforms?id=",
)
data = res.json()

package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://numestri.com/api/v1/rental/retrieve_platforms?id=", 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/rental/retrieve_platforms?id=');
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/rental/retrieve_platforms?id=')
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/rental/retrieve_platforms?id="))
    .GET()
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Responses

200 Platforms and their lowest price.

Example

{
  "success": 1,
  "country": "US",
  "data": [
    {
      "id": "whatsapp",
      "name": "WhatsApp",
      "from_price": "3.90",
      "from_price_cents": 390
    }
  ]
}

Schema

successrequired

countrystringrequired

dataobject[]required

Show child parameters

idstring

namestring

from_pricestring

US dollars, as a fixed two-decimal string.

from_price_centsinteger

The same amount in integer US cents.

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.

402 Insufficient balance (type: BALANCE_ERROR, code: INSUFFICIENT_BALANCE).

Example

{
  "success": 0,
  "message": "That duration is not available. Choose one of: 7, 30 days.",
  "type": "PRICE_NOT_FOUND",
  "code": "INVALID_DAYS"
}

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), a stale option (OPTION_GONE) or a provider with no offer (PROVIDER_UNAVAILABLE), all type: OUT_OF_STOCK; or not available for this number (UNSUPPORTED).

Example

{
  "success": 0,
  "message": "That duration is not available. Choose one of: 7, 30 days.",
  "type": "PRICE_NOT_FOUND",
  "code": "INVALID_DAYS"
}

Schema

successrequired

messagestringrequired

Human-readable, safe to show.

typestringrequired

codestringrequired

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.

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

Example

{
  "success": 0,
  "message": "That duration is not available. Choose one of: 7, 30 days.",
  "type": "PRICE_NOT_FOUND",
  "code": "INVALID_DAYS"
}

Schema

successrequired

messagestringrequired

Human-readable, safe to show.

typestringrequired

codestringrequired

GEThttps://numestri.com/api/v1/rental/retrieve_pricing

Rental terms and prices for a country

Durations available for a country and what each costs. Without service, a general number that receives from anyone; with it, a number reserved for that platform. plans lists every provider's offer per term as anonymous options, cheapest first: pass one as option to /purchase/rental.

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

Parameters

idstringqueryrequired

ISO country code from /rental/retrieve_all.

servicestringquery

Exact platform id from /rental/retrieve_platforms, for a reserved number. Unknown ids are rejected with 400.

Code samples

cURL

curl -X GET "https://numestri.com/api/v1/rental/retrieve_pricing?id=&service="

TypeScript

const res = await fetch('https://numestri.com/api/v1/rental/retrieve_pricing?id=&service=', {
  method: 'GET',
});
const data = await res.json();

Python

import requests

res = requests.request(
    "GET",
    "https://numestri.com/api/v1/rental/retrieve_pricing?id=&service=",
)
data = res.json()

package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://numestri.com/api/v1/rental/retrieve_pricing?id=&service=", 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/rental/retrieve_pricing?id=&service=');
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/rental/retrieve_pricing?id=&service=')
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/rental/retrieve_pricing?id=&service="))
    .GET()
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Responses

200 Terms and prices.

Example

{
  "success": 1,
  "country": "GB",
  "service": null,
  "pricing": {
    "7": "41.88",
    "30": "82.38"
  },
  "extend": {
    "7": "41.88",
    "30": "82.38"
  },
  "plans": [
    {
      "days": 7,
      "cost": "41.88",
      "cost_in_cents": 4188,
      "quality": "good",
      "success_rate": 90,
      "in_stock": true,
      "renewable": true,
      "options": [
        {
          "option": "Qm3tV8xLs0PaW1cE",
          "provider": "prv_k3Jd9QmXa2",
          "rank": 1,
          "cost": "41.88",
          "cost_in_cents": 4188,
          "quality": "good",
          "success_rate": 90,
          "in_stock": true,
          "renewable": true
        },
        {
          "option": "Hd9eW2kRn5YcT7bM",
          "provider": "prv_Vb7nR2sYq0",
          "rank": 2,
          "cost": "47.10",
          "cost_in_cents": 4710,
          "quality": null,
          "success_rate": null,
          "in_stock": true,
          "renewable": false
        }
      ]
    }
  ]
}

Schema

successrequired

countrystringrequired

serviceNamedIdrequired

The platform when service was given; otherwise null.

Show child parameters

idstringrequired

namestringrequired

pricingobjectrequired

Days to price in dollars.

extendobjectrequired

Same as pricing: extending costs the same as the term.

plansRentalPlan[]required

Show child parameters

daysintegerrequired

coststringrequired

The best price for this term.

cost_in_centsintegerrequired

The same amount in integer US cents.

qualitystringrequired

Quality band from real orders on this exact platform and country. null until there are enough orders to rate.

excellent | good | fair | poor

success_rateintegerrequired

Observed success rate in percent, rounded to the nearest 5. null with fewer than 5 orders.

in_stockbooleanrequired

renewablebooleanrequired

optionsRentalOption[]required

Every provider's offer for this term.

Show child parameters

optionstringrequired

Pass as option to /purchase/rental to rent exactly this offer at this price.

providerstringrequired

Anonymous, stable provider id. Never a supplier name.

rankintegerrequired

coststringrequired

US dollars, as a fixed two-decimal string.

cost_in_centsintegerrequired

The same amount in integer US cents.

qualitystringrequired

Quality band from real orders on this exact platform and country. null until there are enough orders to rate.

excellent | good | fair | poor

success_rateintegerrequired

Observed success rate in percent, rounded to the nearest 5. null with fewer than 5 orders.

in_stockbooleanrequired

renewablebooleanrequired

400 Missing id, or unknown service.

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.

402 Insufficient balance (type: BALANCE_ERROR, code: INSUFFICIENT_BALANCE).

Example

{
  "success": 0,
  "message": "That duration is not available. Choose one of: 7, 30 days.",
  "type": "PRICE_NOT_FOUND",
  "code": "INVALID_DAYS"
}

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.

404 No rentals are available for that country (and platform) (param: id).

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), a stale option (OPTION_GONE) or a provider with no offer (PROVIDER_UNAVAILABLE), all type: OUT_OF_STOCK; or not available for this number (UNSUPPORTED).

Example

{
  "success": 0,
  "message": "That duration is not available. Choose one of: 7, 30 days.",
  "type": "PRICE_NOT_FOUND",
  "code": "INVALID_DAYS"
}

Schema

successrequired

messagestringrequired

Human-readable, safe to show.

typestringrequired

codestringrequired

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.

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

Example

{
  "success": 0,
  "message": "That duration is not available. Choose one of: 7, 30 days.",
  "type": "PRICE_NOT_FOUND",
  "code": "INVALID_DAYS"
}

Schema

successrequired

messagestringrequired

Human-readable, safe to show.

typestringrequired

codestringrequired

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

Rent a number

Rent a number for a fixed term; it receives unlimited messages for the whole period.

No option or provider: whichever offer is cheapest for the term, failing over if it cannot deliver.
provider: only that provider, its cheapest offer for the term; fails if it has none.
option (from /rental/retrieve_pricing): exactly that offer at its listed price, or a failure — never a substitute.

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

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

idstringrequired

Uppercase ISO country code from /rental/retrieve_all; anything else is a 400.

daysintegerrequired

Term length, one of the days from /rental/retrieve_pricing; any other is INVALID_DAYS (400).

servicestring

Exact platform id, for a number reserved for it. Omit for a general number.

optionstring

An option id from /rental/retrieve_pricing for this term.

providerstring

A provider id: only that provider, its cheapest offer for the term.

max_pricestring

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

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.

{
  "id": "GB",
  "days": 7,
  "service": "string",
  "option": "string",
  "provider": "prv_k3Jd9QmXa2",
  "max_price": "45.00",
  "idempotency_key": "3f1c2a9e-8d4b-4c61-9a57-0b6f2e1d7c34",
  "key": "string"
}

Code samples

cURL

curl -X POST "https://numestri.com/api/v1/purchase/rental" \
  -H "Idempotency-Key: <value>" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d '{"id":"GB","days":7,"service":"string","option":"string","provider":"prv_k3Jd9QmXa2","max_price":"45.00","idempotency_key":"3f1c2a9e-8d4b-4c61-9a57-0b6f2e1d7c34","key":"string"}'

TypeScript

const res = await fetch('https://numestri.com/api/v1/purchase/rental', {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<value>',
    'Content-Type': 'application/x-www-form-urlencoded',
  },
  body: JSON.stringify({"id":"GB","days":7,"service":"string","option":"string","provider":"prv_k3Jd9QmXa2","max_price":"45.00","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/rental",
    headers={
    "Idempotency-Key": "<value>",
    "Content-Type": "application/x-www-form-urlencoded",
    },
    json={"id": "GB", "days": 7, "service": "string", "option": "string", "provider": "prv_k3Jd9QmXa2", "max_price": "45.00", "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/rental", strings.NewReader(`{"id":"GB","days":7,"service":"string","option":"string","provider":"prv_k3Jd9QmXa2","max_price":"45.00","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/rental');
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, '{"id":"GB","days":7,"service":"string","option":"string","provider":"prv_k3Jd9QmXa2","max_price":"45.00","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/rental')
req = Net::HTTP::Post.new(uri)
req['Idempotency-Key'] = '<value>'
req['Content-Type'] = 'application/x-www-form-urlencoded'
req.body = '{"id":"GB","days":7,"service":"string","option":"string","provider":"prv_k3Jd9QmXa2","max_price":"45.00","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/rental"))
    .header("Idempotency-Key", "<value>")
    .header("Content-Type", "application/x-www-form-urlencoded")
    .method("POST", BodyPublishers.ofString("{\"id\":\"GB\",\"days\":7,\"service\":\"string\",\"option\":\"string\",\"provider\":\"prv_k3Jd9QmXa2\",\"max_price\":\"45.00\",\"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 rental.

Example

{
  "success": {},
  "message": "string",
  "expiry": 0,
  "rental_code": "SNBW9MPY",
  "phonenumber": "44839572864",
  "country": "United Kingdom",
  "country_code": "GB",
  "service": null,
  "service_id": null,
  "days": 7,
  "auto_extend": 0,
  "cancelled": 0,
  "expiration_date": 1792548000,
  "expires_in": 601200,
  "cost": "41.88",
  "cost_in_cents": 4188,
  "renewable": true,
  "can_extend": true,
  "can_reset": true
}

Schema

success

messagestring

expiryinteger

Unix seconds; same as expiration_date.

rental_codestringrequired

phonenumberstringrequired

countrystringrequired

country_codestringrequired

servicestringrequired

Platform name for a reserved number; null for a general number.

service_idstringrequired

Platform id for a reserved number; null for a general number.

daysintegerrequired

Total term in days, including extensions.

auto_extendintegerrequired

0 | 1

cancelledintegerrequired

0 | 1

expiration_dateintegerrequired

Unix seconds when the term ends.

expires_inintegerrequired

Seconds left in the term.

coststringrequired

What the rental originally cost.

cost_in_centsintegerrequired

The same amount in integer US cents.

renewablebooleanrequired

Whether the term can be renewed.

can_extendbooleanrequired

Whether /rental/extend works on this number.

can_resetbooleanrequired

Whether /rental/reset works on this number.

400 Missing or invalid parameter (Error, param names it), or the term is not offered (INVALID_DAYS) or the price is above max_price (PRICE_ABOVE_MAX), both RentalFailure with type: PRICE_NOT_FOUND.

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

RentalFailure

successrequired

messagestringrequired

Human-readable, safe to show.

typestringrequired

codestringrequired

{
  "success": 0,
  "message": "That duration is not available. Choose one of: 7, 30 days.",
  "type": "PRICE_NOT_FOUND",
  "code": "INVALID_DAYS"
}

402 Insufficient balance (type: BALANCE_ERROR, code: INSUFFICIENT_BALANCE).

Example

{
  "success": 0,
  "message": "That duration is not available. Choose one of: 7, 30 days.",
  "type": "PRICE_NOT_FOUND",
  "code": "INVALID_DAYS"
}

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), a stale option (OPTION_GONE) or a provider with no offer (PROVIDER_UNAVAILABLE), all type: OUT_OF_STOCK; or not available for this number (UNSUPPORTED).

Example

{
  "success": 0,
  "message": "That duration is not available. Choose one of: 7, 30 days.",
  "type": "PRICE_NOT_FOUND",
  "code": "INVALID_DAYS"
}

Schema

successrequired

messagestringrequired

Human-readable, safe to show.

typestringrequired

codestringrequired

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.

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

Example

{
  "success": 0,
  "message": "That duration is not available. Choose one of: 7, 30 days.",
  "type": "PRICE_NOT_FOUND",
  "code": "INVALID_DAYS"
}

Schema

successrequired

messagestringrequired

Human-readable, safe to show.

typestringrequired

codestringrequired

GEThttps://numestri.com/api/v1/rental/retrieve

Your rentals

Every rental of yours still inside its term (not cancelled, not yet expired), newest first.

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/rental/retrieve"

TypeScript

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

Python

import requests

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

package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://numestri.com/api/v1/rental/retrieve", 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/rental/retrieve');
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/rental/retrieve')
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/rental/retrieve"))
    .GET()
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Responses

200 Your rentals.

Example

[
  {
    "rental_code": "SNBW9MPY",
    "phonenumber": "44839572864",
    "country": "United Kingdom",
    "country_code": "GB",
    "service": null,
    "service_id": null,
    "days": 7,
    "auto_extend": 0,
    "cancelled": 0,
    "expiration_date": 1792548000,
    "expires_in": 601200,
    "cost": "41.88",
    "cost_in_cents": 4188,
    "renewable": true,
    "can_extend": true,
    "can_reset": true
  }
]

Schema

rental_codestringrequired

phonenumberstringrequired

countrystringrequired

country_codestringrequired

servicestringrequired

Platform name for a reserved number; null for a general number.

service_idstringrequired

Platform id for a reserved number; null for a general number.

daysintegerrequired

Total term in days, including extensions.

auto_extendintegerrequired

0 | 1

cancelledintegerrequired

0 | 1

expiration_dateintegerrequired

Unix seconds when the term ends.

expires_inintegerrequired

Seconds left in the term.

coststringrequired

What the rental originally cost.

cost_in_centsintegerrequired

The same amount in integer US cents.

renewablebooleanrequired

Whether the term can be renewed.

can_extendbooleanrequired

Whether /rental/extend works on this number.

can_resetbooleanrequired

Whether /rental/reset works on this number.

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.

GEThttps://numestri.com/api/v1/rental/retrieve_messages

A rental's messages

Every message received on a rented number. Pulls from supply first, so polling this sees a message as soon as it lands; if that pull fails, the messages already held are returned with synced: false rather than an error. code is recovered from the full text.

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

Parameters

rental_codestringqueryrequired

The rental code returned when you rented the number.

Code samples

cURL

curl -X GET "https://numestri.com/api/v1/rental/retrieve_messages?rental_code="

TypeScript

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

Python

import requests

res = requests.request(
    "GET",
    "https://numestri.com/api/v1/rental/retrieve_messages?rental_code=",
)
data = res.json()

package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://numestri.com/api/v1/rental/retrieve_messages?rental_code=", 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/rental/retrieve_messages?rental_code=');
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/rental/retrieve_messages?rental_code=')
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/rental/retrieve_messages?rental_code="))
    .GET()
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Responses

200 The messages.

Example

{
  "success": 1,
  "rental_code": "SNBW9MPY",
  "synced": true,
  "messages": [
    {
      "ID": "msg_1",
      "sender": "Telegram",
      "message": "Login code: 88213",
      "code": "88213",
      "timestamp": "2026-10-14T01:42:11.000Z"
    }
  ]
}

Schema

successrequired

rental_codestringrequired

syncedbooleanrequired

false when supply could not be reached just now: messages is what we already held.

messagesRentalMessage[]required

Show child parameters

IDstringrequired

senderstringrequired

messagestringrequired

codestringrequired

The code recovered from the text, when one was found.

timestampstringrequired

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.

402 Insufficient balance (type: BALANCE_ERROR, code: INSUFFICIENT_BALANCE).

Example

{
  "success": 0,
  "message": "That duration is not available. Choose one of: 7, 30 days.",
  "type": "PRICE_NOT_FOUND",
  "code": "INVALID_DAYS"
}

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.

404 No rental with that code belongs to you (param: rental_code).

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), a stale option (OPTION_GONE) or a provider with no offer (PROVIDER_UNAVAILABLE), all type: OUT_OF_STOCK; or not available for this number (UNSUPPORTED).

Example

{
  "success": 0,
  "message": "That duration is not available. Choose one of: 7, 30 days.",
  "type": "PRICE_NOT_FOUND",
  "code": "INVALID_DAYS"
}

Schema

successrequired

messagestringrequired

Human-readable, safe to show.

typestringrequired

codestringrequired

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.

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

Example

{
  "success": 0,
  "message": "That duration is not available. Choose one of: 7, 30 days.",
  "type": "PRICE_NOT_FOUND",
  "code": "INVALID_DAYS"
}

Schema

successrequired

messagestringrequired

Human-readable, safe to show.

typestringrequired

codestringrequired

POSThttps://numestri.com/api/v1/rental/extend

Extend a rental

Buy another term on the same number, at today's price from the same provider. Check can_extend and renewable first; days must equal the rental's own term length.

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

Request body application/x-www-form-urlencoded

rental_codestringrequired

The rental code returned when you rented the number.

daysintegerrequired

Days to add: the rental's own term length.

keystring

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

{
  "rental_code": "SNBW9MPY",
  "days": 7,
  "key": "string"
}

Code samples

cURL

curl -X POST "https://numestri.com/api/v1/rental/extend" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d '{"rental_code":"SNBW9MPY","days":7,"key":"string"}'

TypeScript

const res = await fetch('https://numestri.com/api/v1/rental/extend', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
  },
  body: JSON.stringify({"rental_code":"SNBW9MPY","days":7,"key":"string"}),
});
const data = await res.json();

Python

import requests

res = requests.request(
    "POST",
    "https://numestri.com/api/v1/rental/extend",
    headers={
    "Content-Type": "application/x-www-form-urlencoded",
    },
    json={"rental_code": "SNBW9MPY", "days": 7, "key": "string"},
)
data = res.json()

package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://numestri.com/api/v1/rental/extend", strings.NewReader(`{"rental_code":"SNBW9MPY","days":7,"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/rental/extend');
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, '{"rental_code":"SNBW9MPY","days":7,"key":"string"}');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Ruby

require 'net/http'
require 'uri'

uri = URI('https://numestri.com/api/v1/rental/extend')
req = Net::HTTP::Post.new(uri)
req['Content-Type'] = 'application/x-www-form-urlencoded'
req.body = '{"rental_code":"SNBW9MPY","days":7,"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/rental/extend"))
    .header("Content-Type", "application/x-www-form-urlencoded")
    .method("POST", BodyPublishers.ofString("{\"rental_code\":\"SNBW9MPY\",\"days\":7,\"key\":\"string\"}"))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Responses

200 The extended rental.

Example

{
  "success": {},
  "message": "string",
  "extension_cost": "41.88",
  "extension_cost_in_cents": 4188,
  "rental_code": "SNBW9MPY",
  "phonenumber": "44839572864",
  "country": "United Kingdom",
  "country_code": "GB",
  "service": null,
  "service_id": null,
  "days": 7,
  "auto_extend": 0,
  "cancelled": 0,
  "expiration_date": 1792548000,
  "expires_in": 601200,
  "cost": "41.88",
  "cost_in_cents": 4188,
  "renewable": true,
  "can_extend": true,
  "can_reset": true
}

Schema

success

messagestring

extension_coststring

What this extension cost.

extension_cost_in_centsinteger

The same amount in integer US cents.

rental_codestringrequired

phonenumberstringrequired

countrystringrequired

country_codestringrequired

servicestringrequired

Platform name for a reserved number; null for a general number.

service_idstringrequired

Platform id for a reserved number; null for a general number.

daysintegerrequired

Total term in days, including extensions.

auto_extendintegerrequired

0 | 1

cancelledintegerrequired

0 | 1

expiration_dateintegerrequired

Unix seconds when the term ends.

expires_inintegerrequired

Seconds left in the term.

coststringrequired

What the rental originally cost.

cost_in_centsintegerrequired

The same amount in integer US cents.

renewablebooleanrequired

Whether the term can be renewed.

can_extendbooleanrequired

Whether /rental/extend works on this number.

can_resetbooleanrequired

Whether /rental/reset works on this number.

400 Missing or invalid parameter (Error), the number cannot be extended (UNSUPPORTED), or days is not its term (INVALID_DAYS, type: PRICE_NOT_FOUND).

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

RentalFailure

successrequired

messagestringrequired

Human-readable, safe to show.

typestringrequired

codestringrequired

{
  "success": 0,
  "message": "That duration is not available. Choose one of: 7, 30 days.",
  "type": "PRICE_NOT_FOUND",
  "code": "INVALID_DAYS"
}

402 Insufficient balance (type: BALANCE_ERROR, code: INSUFFICIENT_BALANCE).

Example

{
  "success": 0,
  "message": "That duration is not available. Choose one of: 7, 30 days.",
  "type": "PRICE_NOT_FOUND",
  "code": "INVALID_DAYS"
}

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.

404 No rental with that code belongs to you (param: rental_code).

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), a stale option (OPTION_GONE) or a provider with no offer (PROVIDER_UNAVAILABLE), all type: OUT_OF_STOCK; or not available for this number (UNSUPPORTED).

Example

{
  "success": 0,
  "message": "That duration is not available. Choose one of: 7, 30 days.",
  "type": "PRICE_NOT_FOUND",
  "code": "INVALID_DAYS"
}

Schema

successrequired

messagestringrequired

Human-readable, safe to show.

typestringrequired

codestringrequired

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.

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

Example

{
  "success": 0,
  "message": "That duration is not available. Choose one of: 7, 30 days.",
  "type": "PRICE_NOT_FOUND",
  "code": "INVALID_DAYS"
}

Schema

successrequired

messagestringrequired

Human-readable, safe to show.

typestringrequired

codestringrequired

POSThttps://numestri.com/api/v1/rental/reset

Reset a rental's inbound route

Reload the inbound route, which revives a rented number that has quietly stopped receiving. Not every number supports it: check can_reset.

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

Request body application/x-www-form-urlencoded

rental_codestringrequired

The rental code returned when you rented the number.

keystring

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

{
  "rental_code": "SNBW9MPY",
  "key": "string"
}

Code samples

cURL

curl -X POST "https://numestri.com/api/v1/rental/reset" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d '{"rental_code":"SNBW9MPY","key":"string"}'

TypeScript

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

Python

import requests

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

package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://numestri.com/api/v1/rental/reset", strings.NewReader(`{"rental_code":"SNBW9MPY","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/rental/reset');
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, '{"rental_code":"SNBW9MPY","key":"string"}');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Ruby

require 'net/http'
require 'uri'

uri = URI('https://numestri.com/api/v1/rental/reset')
req = Net::HTTP::Post.new(uri)
req['Content-Type'] = 'application/x-www-form-urlencoded'
req.body = '{"rental_code":"SNBW9MPY","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/rental/reset"))
    .header("Content-Type", "application/x-www-form-urlencoded")
    .method("POST", BodyPublishers.ofString("{\"rental_code\":\"SNBW9MPY\",\"key\":\"string\"}"))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Responses

200 Reset.

Example

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

Schema

successrequired

messagestringrequired

400 Missing rental_code, or this number does not support a reset.

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

RentalFailure

successrequired

messagestringrequired

Human-readable, safe to show.

typestringrequired

codestringrequired

{
  "success": 0,
  "message": "That duration is not available. Choose one of: 7, 30 days.",
  "type": "PRICE_NOT_FOUND",
  "code": "INVALID_DAYS"
}

402 Insufficient balance (type: BALANCE_ERROR, code: INSUFFICIENT_BALANCE).

Example

{
  "success": 0,
  "message": "That duration is not available. Choose one of: 7, 30 days.",
  "type": "PRICE_NOT_FOUND",
  "code": "INVALID_DAYS"
}

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.

404 No rental with that code belongs to you (param: rental_code).

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), a stale option (OPTION_GONE) or a provider with no offer (PROVIDER_UNAVAILABLE), all type: OUT_OF_STOCK; or not available for this number (UNSUPPORTED).

Example

{
  "success": 0,
  "message": "That duration is not available. Choose one of: 7, 30 days.",
  "type": "PRICE_NOT_FOUND",
  "code": "INVALID_DAYS"
}

Schema

successrequired

messagestringrequired

Human-readable, safe to show.

typestringrequired

codestringrequired

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.

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

Example

{
  "success": 0,
  "message": "That duration is not available. Choose one of: 7, 30 days.",
  "type": "PRICE_NOT_FOUND",
  "code": "INVALID_DAYS"
}

Schema

successrequired

messagestringrequired

Human-readable, safe to show.

typestringrequired

codestringrequired

POSThttps://numestri.com/api/v1/rental/refund

Give a rental back

Cancel a rental. A refund is only possible inside a short window and generally only before any message has arrived; the rental is released either way, and the response says what was actually credited (possibly 0.00).

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

Request body application/x-www-form-urlencoded

rental_codestringrequired

The rental code returned when you rented the number.

keystring

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

{
  "rental_code": "SNBW9MPY",
  "key": "string"
}

Code samples

cURL

curl -X POST "https://numestri.com/api/v1/rental/refund" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d '{"rental_code":"SNBW9MPY","key":"string"}'

TypeScript

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

Python

import requests

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

package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://numestri.com/api/v1/rental/refund", strings.NewReader(`{"rental_code":"SNBW9MPY","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/rental/refund');
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, '{"rental_code":"SNBW9MPY","key":"string"}');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Ruby

require 'net/http'
require 'uri'

uri = URI('https://numestri.com/api/v1/rental/refund')
req = Net::HTTP::Post.new(uri)
req['Content-Type'] = 'application/x-www-form-urlencoded'
req.body = '{"rental_code":"SNBW9MPY","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/rental/refund"))
    .header("Content-Type", "application/x-www-form-urlencoded")
    .method("POST", BodyPublishers.ofString("{\"rental_code\":\"SNBW9MPY\",\"key\":\"string\"}"))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Responses

200 Cancelled; what was refunded.

Example

{
  "success": 1,
  "message": "Rental cancelled and 41.88 refunded.",
  "refunded": "41.88",
  "refunded_in_cents": 4188
}

Schema

successrequired

messagestringrequired

refundedstringrequired

US dollars, as a fixed two-decimal string.

refunded_in_centsintegerrequired

The same amount in integer US cents.

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 rental with that code belongs to you (param: rental_code).

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.

Updated Oct 16, 2026

Was this page helpful?