# 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%`
- `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

## 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 63 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