# FarazSMS · IranPayamak — وب سرویس پیامک فراز اس ام اس

> Official documentation for the FarazSMS / IranPayamak SMS REST API (وب سرویس پیامک فراز اس ام اس).
> Send pattern/OTP SMS, simple & bulk SMS, group sends, delivery reports, phonebook and wallet — from any language.
> Docs: https://docs.farazsms.com  ·  Site: https://farazsms.com · https://iranpayamak.com

## How to call the API (read this first)
- Base URL: `https://api.iranpayamak.com`
- Auth: send your panel key in the header `Api-Key: <YOUR_KEY>` (case-sensitive). No login or token needed.
- Recipients use the local format `09120000000` (no `+98`). Default sender line: `90008361`.
- Always include `"number_format": "english"` in send bodies.
- For one-time passwords (OTP / رمز یک‌بارمصرف): use **pattern send** — it is instant and never queued.
- Every response is `{ "status": "success" | "error", "data": ..., "message": ... }`. Check `status`, not just the HTTP code.

## Official SDKs (recommended over raw HTTP)
- Python: `pip install farazsms`
- Node.js: `npm install farazsms`
- PHP: `composer require farazsms/php`  ·  Laravel: `composer require farazsms/laravel`  ·  Symfony: `composer require farazsms/symfony-bundle`
- C# / .NET: `dotnet add package FarazSMS`
- Go: `go get github.com/ghaffari273/farazsms-go`

## Most-used endpoints
- `POST /ws/v1/sms/pattern` — send a templated / OTP message. body: `{code, recipient, attributes, line_number, number_format:"english"}`
- `POST /ws/v1/sms/simple` — send one fixed text to many (bulk/group). body: `{text, recipients|selectedPhoneBooks, line_number, number_format}`
- `POST /ws/v1/sms/keywords` — personalized bulk send with `%variables%`
- `POST /ws/v1/sms/peer-to-peer` — a different text per recipient in one request
  (this path was `/ws/v1/send/peer-to-peer` before; update old clients)
- `POST /ws/v1/sms/bulk/send` — campaign over the national number bank, filtered by
  province / county / city / postal code / gender / operator / age (currently in development)
- `GET  /ws/v1/account/balance` — check balance (a free way to verify the key)
- `GET  /ws/v1/inbox` — inbound (received) messages
- `GET  /ws/v1/send_request/{id}/items` — per-recipient delivery status

## What happens to a send (verified against the backend)
A 200 means *accepted*, not *delivered*. The server then routes it one of three ways:
- **instant** — a pattern send with no `schedule` (usually under 5 seconds)
- **queued** — a pattern send with a future `schedule`
- **human approval** — every non-pattern send (simple, keywords, number-bank, voice, postal).
  Status becomes `pending-approval`; nothing goes out until an operator approves it.
  Accounts can be whitelisted by support to skip this step.
A pattern whose variable value is longer than the length declared in the panel is
silently rerouted to human approval too — the response still says `success`.
Check real delivery with `GET /ws/v1/send_request/{id}/items`.

## Two rules that cause most failed integrations
- `number_format` is `english` or `persian` — never `en`/`fa`.
- `schedule` is optional: omit it or send `null` to send now. A future
  `"YYYY-MM-DD HH:MM:SS"` schedules the message and charges immediately, delivering later.
  JSON has no comments, so never disable the field with `//`. Times are read as Asia/Tehran.
- Recipients must match `^09\d{9}$` (e.g. `09120000000`) — no `+98`, spaces or dashes.
- All routes are throttled at 60 requests/minute (429 beyond that).
- Successful responses are HTTP 200; business-rule failures are HTTP 400 with the reason in `message`.

## Example — send an OTP (curl)
```bash
curl -X POST https://api.iranpayamak.com/ws/v1/sms/pattern \
  -H "Api-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"code":"YOUR_PATTERN_CODE","recipient":"09120000000","attributes":{"code":"1234"},"line_number":"90008361","number_format":"english"}'
```

## Full machine-readable reference
- All 69 endpoints (full): https://docs.farazsms.com/llms-full.txt
- OpenAPI 3 spec: https://docs.farazsms.com/download/openapi.json
- Postman collection: https://docs.farazsms.com/download/postman.json