On this page

GhostSMS API

Beta

Buy numbers, read the codes they receive, and be told when they arrive — from your own software.

3 min read

Everything you can do on the website, you can do over HTTP: buy a number for one code, rent one for longer, read what arrives, and get your money back when nothing does.

The API is in beta. It is safe to build on — the compatibility rules hold inside v1 — but it is young, new fields and events arrive quickly, and what integrators tell us is what hardens it. What beta means.

https://api.ghostsms.io/v1

What you work with

Activations are one-time numbers. You buy one for a service and a country, a code arrives, and the number is finished. Most integrations only need these.

Rentals are numbers you keep for a set period. They receive as many messages as you like, can be extended, and can be cancelled inside their refund window.

Both come with prices you can read before you buy, and both refund themselves when no message ever arrives.

Getting access

Every account has API access; there is nothing to apply for. Keys are created on the Developers page of the dashboard, and every request carries one:

Authorization: Bearer gsk_Ab3dEf6hIj9k_...

A key carries the scopes you gave it, is shown once, and can be revoked without touching the others. Your website sign-in token is not accepted here — see Authentication.

What to expect from it

  • Money is an integer number of cents with its currency: {"amount": 62, "currency": "USD"}. No floats.
  • Times are UTC instants, 2026-09-18T10:35:00Z.
  • Lists are cursor-paged, newest first: pass next_cursor back as cursor.
  • Purchases need an Idempotency-Key, so a retry cannot buy twice. See Idempotency.
  • Every failure is an RFC 9457 problem with a stable code and a request_id. See Errors.
  • You do not have to poll. Register an endpoint and we post the code to you, signed. See Events.

The contract itself

The reference in this section is generated from the OpenAPI document the API publishes, so it cannot describe an API we do not serve. You can fetch the same document — no key required — and point an SDK generator or Postman at it:

GET https://api.ghostsms.io/v1/openapi.json

It is served with an ETag, so a poller that already has the current version gets a 304 rather than the whole document again.

Where to go next

  • Quick start — buy a number and read its code, in three calls.
  • API reference — every endpoint, its parameters and its responses.
  • Help centre — the same tasks done by hand, for the people on your team who are not integrating.