Activations

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

https://api.ghostsms.iov1openapi.json

The activation 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
client_referencestring
created_attimestamp
expires_attimestamp
cancel_available_attimestamp
no_code_available_attimestamp
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": "…"
  },
  "client_reference": "…",
  "created_at": "2026-09-18T10:35:00Z",
  "expires_at": "2026-09-18T10:35:00Z",
  "cancel_available_at": "2026-09-18T10:35:00Z",
  "no_code_available_at": "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

waiting_for_codeBought and live. Give the number to the service you are verifying.
code_receivedAt least one message has arrived; read it from messages.
completedThe window closed after a code had arrived. Terminal.
refundedNo code ever arrived, or you reported one missing with no replacement left. The price went back. Terminal.
cancelledYou cancelled before any message arrived. The price went back. Terminal.

GET /v1/activations

scopeactivations:read

List activations, newest first

Query parameters

limitinteger
cursorstring
client_referencestring

Returns

objectstring
dataarray of activation: objectstring
idstring
statusstring
serviceservice
countrystring
phone_numberstring
priceapimoney
client_referencestring
created_attimestamp
expires_attimestamp
cancel_available_attimestamp
no_code_available_attimestamp
messages_countinteger
messagesarray of message
has_moreboolean
next_cursorstring

curl https://api.ghostsms.io/v1/activations \
  -H "Authorization: Bearer $GHOSTSMS_KEY"

200

{
  "object": "activation",
  "data": [
    {
      "object": "activation",
      "id": "…",
      "status": "…",
      "service": "…",
      "country": "…",
      "phone_number": "…",
      "price": "…",
      "client_reference": "…",
      "created_at": "2026-09-18T10:35:00Z",
      "expires_at": "2026-09-18T10:35:00Z",
      "cancel_available_at": "2026-09-18T10:35:00Z",
      "no_code_available_at": "2026-09-18T10:35:00Z",
      "messages_count": 0,
      "messages": []
    }
  ],
  "has_more": false,
  "next_cursor": "…"
}

POST /v1/activations

scopeactivations:write

Buy an activation. 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

servicestringRequired
countrystringRequired
client_referencestring
quote_tokenstring
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.
409duplicate_pending_activation: An activation for this service and country with the same client_reference is still waiting for its code. Use No code? on it, or send a different client_reference.
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/activations \
  -X POST \
  -H "Authorization: Bearer $GHOSTSMS_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"service":"your-service","country":"your-country"}'

GET /v1/activations/{id}

scopeactivations:read

Retrieve an activation with its most recent messages

Returns

objectstring
idstring
statusstring
serviceservice: idstring
namestring
countrystring
phone_numberstring
priceapimoney: amountinteger
currencystring
client_referencestring
created_attimestamp
expires_attimestamp
cancel_available_attimestamp
no_code_available_attimestamp
messages_countinteger
messagesarray of message: objectstring
idstring
received_attimestamp
fromstring
textstring
codestring

curl https://api.ghostsms.io/v1/activations/{id} \
  -H "Authorization: Bearer $GHOSTSMS_KEY"

200

{
  "object": "activation",
  "id": "…",
  "status": "…",
  "service": {
    "id": "…",
    "name": "…"
  },
  "country": "…",
  "phone_number": "…",
  "price": {
    "amount": 0,
    "currency": "…"
  },
  "client_reference": "…",
  "created_at": "2026-09-18T10:35:00Z",
  "expires_at": "2026-09-18T10:35:00Z",
  "cancel_available_at": "2026-09-18T10:35:00Z",
  "no_code_available_at": "2026-09-18T10:35:00Z",
  "messages_count": 0,
  "messages": [
    {
      "object": "activation",
      "id": "…",
      "received_at": "2026-09-18T10:35:00Z",
      "from": "…",
      "text": "…",
      "code": "…"
    }
  ]
}

POST /v1/activations/{id}/cancel

scopeactivations:write

Cancel an activation still waiting for its code; 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.
409cancel_try_again: The cancellation could not be confirmed. Nothing was refunded yet; try again shortly.
409code_already_received: A message has already arrived on this number, so it can no longer be cancelled or replaced.
409not_active: This activation or rental has already ended.
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/activations/{id}/cancel \
  -X POST \
  -H "Authorization: Bearer $GHOSTSMS_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

POST /v1/activations/{id}/no-code

scopeactivations:write

No code arrived: replace the number, or refund if it cannot be replaced. 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.

What this refuses

409not_yet_available: This action is not available yet. See retry_after_seconds.
409code_already_received: A message has already arrived on this number, so it can no longer be cancelled or replaced.
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/activations/{id}/no-code \
  -X POST \
  -H "Authorization: Bearer $GHOSTSMS_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

GET /v1/activations/{id}/messages

scopeactivations:read

List an activation'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/activations/{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": "…"
}

POST /v1/activations/{id}/number-rejected

scopeactivations:write

The service refused the number: replace it, or refund. 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.

What this refuses

409not_active: This activation or rental has already ended.
409code_already_received: A message has already arrived on this number, so it can no longer be cancelled or replaced.
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/activations/{id}/number-rejected \
  -X POST \
  -H "Authorization: Bearer $GHOSTSMS_KEY" \
  -H "Idempotency-Key: $(uuidgen)"