On this page

Rentals

Beta

6 endpoints, each naming the scope its key must carry.

https://api.ghostsms.iov1openapi.json

The rental object

Every endpoint below returns this shape, whole or in a list. Money is an integer number of cents with its currency; times are UTC instants.

objectstring
idstring
statusstring
serviceservice
idstring
namestring
countrystring
phone_numberstring
priceapimoney
amountinteger
currencystring
durationstring
client_referencestring
created_attimestamp
expires_attimestamp
extended_attimestamp
cancel_available_untiltimestamp
messages_countinteger
messagesarray of message
objectstring
idstring
received_attimestamp
fromstring
textstring
codestring
Example
{
  "object": "activation",
  "id": "…",
  "status": "…",
  "service": {
    "id": "…",
    "name": "…"
  },
  "country": "…",
  "phone_number": "…",
  "price": {
    "amount": 0,
    "currency": "…"
  },
  "duration": "…",
  "client_reference": "…",
  "created_at": "2026-09-18T10:35:00Z",
  "expires_at": "2026-09-18T10:35:00Z",
  "extended_at": "2026-09-18T10:35:00Z",
  "cancel_available_until": "2026-09-18T10:35:00Z",
  "messages_count": 0,
  "messages": [
    {
      "object": "activation",
      "id": "…",
      "received_at": "2026-09-18T10:35:00Z",
      "from": "…",
      "text": "…",
      "code": "…"
    }
  ]
}

status, in order

  1. waiting_for_codeLive and receiving. Messages accumulate for as long as the rental runs.
  2. code_receivedAt least one message has arrived. The rental keeps running.
  3. completedThe rental passed its expires_at. Terminal — nothing marks it earlier.
  4. refundedCancelled inside the refund window; the price went back. Terminal.

GET /v1/rentals

scoperentals:read

List rentals, newest first

Query parameters

limitinteger
cursorstring
client_referencestring

Returns

objectstring
dataarray of rental
objectstring
idstring
statusstring
serviceservice
countrystring
phone_numberstring
priceapimoney
durationstring
client_referencestring
created_attimestamp
expires_attimestamp
extended_attimestamp
cancel_available_untiltimestamp
messages_countinteger
messagesarray of message
has_moreboolean
next_cursorstring
curl https://api.ghostsms.io/v1/rentals \
  -H "Authorization: Bearer $GHOSTSMS_KEY"
200
{
  "object": "activation",
  "data": [
    {
      "object": "activation",
      "id": "…",
      "status": "…",
      "service": "…",
      "country": "…",
      "phone_number": "…",
      "price": "…",
      "duration": "…",
      "client_reference": "…",
      "created_at": "2026-09-18T10:35:00Z",
      "expires_at": "2026-09-18T10:35:00Z",
      "extended_at": "2026-09-18T10:35:00Z",
      "cancel_available_until": "2026-09-18T10:35:00Z",
      "messages_count": 0,
      "messages": []
    }
  ],
  "has_more": false,
  "next_cursor": "…"
}

POST /v1/rentals

scoperentals:write

Rent a number. Requires an Idempotency-Key.

Headers

Idempotency-KeystringRequired
A key you generate per attempt. Retrying with the same key returns the first outcome instead of buying again.

Body

countrystringRequired
duration_hoursintegerRequired
client_referencestring
max_priceinteger

What this refuses

402insufficient_balance
The balance does not cover the price. Nothing was charged.
403daily_spend_limit_reached
This purchase would take today's API spending over the account's daily limit. Nothing was charged.
409price_above_maximum
The price is higher than the max_price sent with the request. Nothing was charged.
409number_unavailable
No number could be bought for this right now. Nothing was charged; it may succeed if retried later.
400idempotency_key_required
This request spends money or changes a number. Send an Idempotency-Key header, unique per operation, so a retry after a timeout cannot do it twice.
422idempotency_key_reused
This Idempotency-Key was already used for a different request. Use a new key for a new operation.
409idempotency_request_in_progress
The first request with this Idempotency-Key has not finished. Retry with the same key shortly.

Plus the refusals every endpoint shares — see Errors.

curl https://api.ghostsms.io/v1/rentals \
  -X POST \
  -H "Authorization: Bearer $GHOSTSMS_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"country":"your-country","duration_hours":0}'

GET /v1/rentals/{id}

scoperentals:read

Retrieve a rental with its most recent messages

Returns

objectstring
idstring
statusstring
serviceservice
idstring
namestring
countrystring
phone_numberstring
priceapimoney
amountinteger
currencystring
durationstring
client_referencestring
created_attimestamp
expires_attimestamp
extended_attimestamp
cancel_available_untiltimestamp
messages_countinteger
messagesarray of message
objectstring
idstring
received_attimestamp
fromstring
textstring
codestring
curl https://api.ghostsms.io/v1/rentals/{id} \
  -H "Authorization: Bearer $GHOSTSMS_KEY"
200
{
  "object": "activation",
  "id": "…",
  "status": "…",
  "service": {
    "id": "…",
    "name": "…"
  },
  "country": "…",
  "phone_number": "…",
  "price": {
    "amount": 0,
    "currency": "…"
  },
  "duration": "…",
  "client_reference": "…",
  "created_at": "2026-09-18T10:35:00Z",
  "expires_at": "2026-09-18T10:35:00Z",
  "extended_at": "2026-09-18T10:35:00Z",
  "cancel_available_until": "2026-09-18T10:35:00Z",
  "messages_count": 0,
  "messages": [
    {
      "object": "activation",
      "id": "…",
      "received_at": "2026-09-18T10:35:00Z",
      "from": "…",
      "text": "…",
      "code": "…"
    }
  ]
}

POST /v1/rentals/{id}/cancel

scoperentals:write

Cancel a rental inside its refund window; the price is refunded

Headers

Idempotency-KeystringRequired
A key you generate per attempt. Retrying with the same key returns the first outcome instead of buying again.

What this refuses

409cancel_window_closed
This rental can no longer be cancelled for a refund. It stays yours until it expires.
409cancel_refused
The supplier refused to take the number back. It stays active and nothing was refunded.
409not_active
This activation or rental has already ended.
409request_conflict
The request conflicts with the current state of this activation or rental. Retrieve it and try again.
400idempotency_key_required
This request spends money or changes a number. Send an Idempotency-Key header, unique per operation, so a retry after a timeout cannot do it twice.

Plus the refusals every endpoint shares — see Errors.

curl https://api.ghostsms.io/v1/rentals/{id}/cancel \
  -X POST \
  -H "Authorization: Bearer $GHOSTSMS_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

POST /v1/rentals/{id}/extend

scoperentals:write

Extend a rental. Requires an Idempotency-Key.

Headers

Idempotency-KeystringRequired
A key you generate per attempt. Retrying with the same key returns the first outcome instead of buying again.

Body

duration_hoursintegerRequired
max_priceinteger

What this refuses

402insufficient_balance
The balance does not cover the price. Nothing was charged.
403daily_spend_limit_reached
This purchase would take today's API spending over the account's daily limit. Nothing was charged.
409not_active
This activation or rental has already ended.
409request_conflict
The request conflicts with the current state of this activation or rental. Retrieve it and try again.
400idempotency_key_required
This request spends money or changes a number. Send an Idempotency-Key header, unique per operation, so a retry after a timeout cannot do it twice.

Plus the refusals every endpoint shares — see Errors.

curl https://api.ghostsms.io/v1/rentals/{id}/extend \
  -X POST \
  -H "Authorization: Bearer $GHOSTSMS_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"duration_hours":0}'

GET /v1/rentals/{id}/messages

scoperentals:read

List a rental's messages, newest first

Query parameters

limitinteger
cursorstring

Returns

objectstring
dataarray of message
objectstring
idstring
received_attimestamp
fromstring
textstring
codestring
has_moreboolean
next_cursorstring
curl https://api.ghostsms.io/v1/rentals/{id}/messages \
  -H "Authorization: Bearer $GHOSTSMS_KEY"
200
{
  "object": "activation",
  "data": [
    {
      "object": "activation",
      "id": "…",
      "received_at": "2026-09-18T10:35:00Z",
      "from": "…",
      "text": "…",
      "code": "…"
    }
  ],
  "has_more": false,
  "next_cursor": "…"
}