# SMSZ

> Virtual phone numbers for SMS verification. Buy a single-use number for one
> verification code, or rent a number for days to months. REST API with
> webhooks for incoming messages.

Base URL: https://www.smsz.net/api/v1
Auth: `Authorization: Bearer smsz_live_...` (create keys in the account menu at https://www.smsz.net)

## Documentation

- [Full API documentation (Markdown)](https://www.smsz.net/api/llms-full.txt): every guide and endpoint in one file
- [OpenAPI 3.1 specification](https://www.smsz.net/api/v1/openapi.json): machine-readable, unauthenticated
- [API documentation (HTML)](https://www.smsz.net/api): the same content as a web page

## Endpoints

- `GET /ping` — Verify your API key
- `GET /account` — Retrieve your account
- `GET /transactions` — List transactions
- `GET /countries` — List countries
- `GET /services` — List services
- `GET /pricing/activations` — Live activation prices
- `GET /pricing/rentals` — Live rental offers
- `POST /activations` — Buy an activation
- `GET /activations` — List activations
- `GET /activations/{id}` — Retrieve an activation
- `GET /activations/{id}/messages` — Poll for the code
- `POST /activations/{id}/cancel` — Cancel an activation
- `POST /activations/{id}/finish` — Finish an activation
- `POST /rentals` — Order a rental
- `GET /rentals` — List rentals
- `GET /rentals/{id}` — Retrieve a rental
- `GET /rentals/{id}/messages` — List rental messages
- `POST /rentals/{id}/extend` — Extend a rental
- `POST /rentals/{id}/cancel` — Cancel a rental
- `POST /webhooks/endpoints` — Create a webhook endpoint
- `GET /webhooks/endpoints` — List webhook endpoints
- `GET /webhooks/endpoints/{id}` — Retrieve a webhook endpoint
- `PATCH /webhooks/endpoints/{id}` — Update a webhook endpoint
- `DELETE /webhooks/endpoints/{id}` — Delete a webhook endpoint
- `POST /webhooks/endpoints/{id}/test` — Send a test event
- `GET /webhooks/deliveries` — List deliveries
- `GET /events` — List events

## Notes

- All amounts are USD; purchases are charged against an account balance.
- Send `Idempotency-Key` on purchases so retries cannot double-charge.
- Webhooks are signed with HMAC-SHA256 as `SMSZ-Signature: t=<ts>,v1=<hex>` over `{ts}.{body}`.
- There is no test mode: a successful purchase spends real balance.