Rentals

Create a long-term rental

Reserves a dedicated phone number for a fixed duration (3, 7, 14, or 30 days). All incoming SMS messages are collected and accessible via GET /v1/rentals/{id}. Idempotent by Idempotency-Key.

Price over cap

LTR pricing can drift. If the lowest available price exceeds your max_price_cents ceiling at request time, the API returns 409 PRICE_OVER_CAP with both values in the error details:

{
  "success": false,
  "error": {
    "code": "PRICE_OVER_CAP",
    "details": {
      "max_price_cents": 1500,
      "available_price_cents": 1750
    }
  }
}

No partial state is created and no funds are touched. Decide locally whether to retry with a higher cap or surface the price to the user.

Duration

duration must be one of 3D, 7D, 14D, or 30D. Only country="us" is currently supported.

Auto-renew

Set auto_renew: true to automatically charge the same duration shortly before paid_until. Toggle at any time via POST /v1/rentals/{id}/auto_renew. If the balance cannot cover the renewal in time, auto-renew is turned off and rental.auto_renew_disabled fires.

post/rentals

Request

  • Base URL: https://dashboard.voidmob.com/api/v1
  • URL: https://dashboard.voidmob.com/api/v1/rentals
  • Auth: HTTP bearer

Headers

Idempotency-Keystring required
Example:7c4f08c2-2a4f-4c8e-a1d2-9c2b9c8f7e10

Client-supplied key (any string, up to 255 chars) that scopes idempotent replay for write requests. Required on every POST, PATCH, and DELETE. Replays with the same key + same body return the cached response; same key with a different body returns IDEMPOTENCY_CONFLICT. Headers are case-insensitive; both Idempotency-Key and idempotency-key work.

Request body

service_idstring required

Opaque public service identifier.

duration'3D' | '7D' | '14D' | '30D' required

Rental period. Must be one of 3D/7D/14D/30D.

countrystring

ISO-3166-1 alpha-2, lowercased. Only us is supported.

auto_renewboolean

Automatically renew the rental for the same duration at expiry.

max_price_centsinteger

Optional price ceiling. Drift within the cap charges silently; drift above the cap returns 409 PRICE_OVER_CAP with the current available price in the error details so callers can decide whether to retry with a higher cap. Omit to require an exact match to the current catalog price.

webhook_endpoint_idstring

Webhook endpoint identifier.

Example request

{
  "service_id": "svc_telegram",
  "webhook_endpoint_id": "whep_01HXYZ123ABC"
}

Response

Rental created. status is active immediately.

successtrue required

Example response

{
  "data": {
    "id": "ren_01HXYZ123ABC",
    "display_id": "SMS7K4P2N",
    "phone_number": "+15551234567",
    "service_id": "svc_telegram",
    "service_name": "Telegram",
    "country": "us",
    "duration": "7D",
    "charged_price_cents": 2500,
    "next_renewal_price_cents": 2500,
    "payment_due": {
      "amount_cents": 1499
    },
    "re_rent_available": true,
    "re_rent_price_cents": 2500,
    "messages": [
      {
        "id": "msg_01HXYZ123ABC",
        "code": "123456",
        "text": "Your verification code is 123456."
      }
    ]
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.