API documentation
Introduction
Base URL, authentication and the shape of requests and responses in Watsy API v1.
The Watsy API is a small REST interface: one request sends a verification code, a second one checks what the user typed. We generate the code, pick the channel and handle delivery and billing.
Base URL
https://watsy.me/v1- Requests and responses are JSON. Send
Content-Type: application/jsonwith any body. Bodies are limited to 16KB. - Fields are snake_case. Unknown fields return
400 validation_failed. - Money is in Iraqi dinars. Fields ending in
_milliare integers in milli-IQD (1 IQD = 1000). - Times are ISO 8601 in UTC.
- Responses are never cached (
Cache-Control: no-store).
Authentication
Every request needs a project key in the Authorization header. Create keys in your project under API keys; a key is shown once, when you create it.
Authorization: Bearer wsy_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx| Key | Prefix | Behaviour |
|---|---|---|
| Live | wsy_live_ | Really sends and charges the wallet |
| Test | wsy_test_ | Never sends or charges; registered test numbers only. See Test keys |
The API is server-to-server only and has no CORS support. Never ship a key inside a mobile app, a web page or a public repository. A missing or revoked key returns 401 unauthenticated.
Request id
Every response carries an X-Request-Id header. Quote it when you contact support. You can send your own X-Request-Id (8 to 64 characters from A-Z a-z 0-9 . _ : -) and we echo it back; otherwise we generate one like req_….
Endpoints
| Method | Path | What it does |
|---|---|---|
POST | /v1/verify | Start a verification |
POST | /v1/verify/{id}/check | Check a code |
GET | /v1/verify/{id} | Get a verification |
POST | /v1/verify/{id}/cancel | Cancel a verification |
GET | /v1/messages | List messages |
GET | /v1/balance | Get balance |