Renting a number

A rental keeps one number for a fixed term and receives every message sent to it, for as long as the term lasts. Two kinds:

• General — receives from any sender.

• Reserved for a platform — a number set aside for one platform (WhatsApp, say), for when a platform will only accept its own.

Find what you can rent

These three calls are public: no API key needed. Without one they show public list prices; send your key to see your account's own prices, which is what a rental will charge you. A wrong key is refused with 403. See Authentication.

1. Countries

   curl https://numestri.com/api/v1/rental/retrieve_all

   { "success": 1, "data": [ { "id": "US", "name": "United States" } ] }

2. Platforms with reserved numbers (optional)

   curl "https://numestri.com/api/v1/rental/retrieve_platforms?id=US"

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

3. Terms, prices and options

   Add service for a reserved number; leave it out for a general one.

   curl "https://numestri.com/api/v1/rental/retrieve_pricing?id=US&service=whatsapp"

   {
     "success": 1,
     "country": "US",
     "service": { "id": "whatsapp", "name": "WhatsApp" },
     "pricing": { "7": "4.94", "30": "12.35" },
     "plans": [
       {
         "days": 7, "cost": "4.94", "cost_in_cents": 494, "quality": null, "in_stock": true, "renewable": true,
         "options": [
           { "option": "Qm3tV8xLs0PaWd2E", "provider": "prv_k3Jd9QmXa2", "rank": 1, "cost": "4.94", "in_stock": true, "renewable": true }
         ]
       }
     ]
   }

   renewable says whether the term can be extended on the same number later. Check it before you rent a number you mean to keep. extend (the same map as pricing) is what another term costs.

   A country with nothing to rent — or nothing reserved for that platform there — is a 404 with param: "id", pointing you back to retrieve_all or retrieve_platforms. An unknown service id is a 400.

Rent it

Renting, and everything after it, needs an API key.

curl https://numestri.com/api/v1/purchase/rental -H "Authorization: Bearer $NUMESTRI_KEY" \
  -d id=US -d days=7 -d service=whatsapp

{
  "success": 1,
  "rental_code": "SNBW9MPY",
  "phonenumber": "15550109876",
  "service_id": "whatsapp",
  "days": 7,
  "expiration_date": 1792736400,
  "renewable": true,
  "can_extend": true,
  "can_reset": true
}

Read its messages

curl "https://numestri.com/api/v1/rental/retrieve_messages?rental_code=SNBW9MPY" -H "Authorization: Bearer $NUMESTRI_KEY"

{
  "success": 1,
  "messages": [
    {
      "sender": "WhatsApp",
      "message": "Your code is 553-311",
      "code": "553311"
    }
  ]
}

Rentals receive whole messages; code is the verification code we found in it. For hands-off delivery, add a webhook — every message fires rental.received.

Keep, fix or return it