# FarazSMS · IranPayamak — full web-service reference for LLMs
> وب سرویس پیامک فراز اس ام اس. Base URL: https://api.iranpayamak.com — Auth: header `Api-Key` (key from the panel, case-sensitive). Recipients use 09xxxxxxxxx (no +98). Default sender line 90008361.
> Official SDKs: `pip install farazsms` · `npm install farazsms` · `composer require farazsms/php` · `dotnet add package FarazSMS` · `go get github.com/ghaffari273/farazsms-go`
> For OTP use pattern send (POST /ws/v1/sms/pattern) — instant, never queued.

## ارسال پیامک (Send SMS)
_Start here. For OTP use Pattern send — the fastest path._

- `POST /ws/v1/sms/pattern` — Send Pattern-Based SMS — Send a templated message (OTP, verification codes, transaction alerts). Fastest path and never queued — use this for one-time codes.
  - required: code, line_number, number_format, recipient
- `POST /ws/v1/sms/simple` — Send Simple SMS from Phonebook — Send one fixed text to a list of numbers or a phonebook. For announcements and bulk campaigns (goes through the queue).
  - required: text, line_number, number_format
- `POST /ws/v1/sms/keywords` — Send SMS with Variables — Bulk personalized send; variables (e.g. the contact's name) sit inside `%...%` in the text.
- `POST /v1/send/keyword-file` — Send SMS with Variables from Excel — The same variable send, but each recipient's data comes from an Excel/CSV file — for large volumes.
- `POST /ws/v1/lbs` — Create New LBS Request — Create a location-based campaign; messages people who are within a chosen area and time window.
- `GET /ws/v1/lbs` — Get LBS Requests List — List your location-based campaigns to track their status.
- `PUT /ws/v1/lbs/{lbsId}` — Edit LBS Request — Edit a location-based campaign before it runs (text, area, filters).
- `GET /ws/v1/lbs/{lbsId}` — Show Single LBS Request Details — View the full details of one location-based campaign by its id.
- `PATCH /ws/v1/lbs/{lbsId}/cancel` — Cancel LBS Request — Cancel a location-based campaign before it sends.
- `POST /ws/v1/send/peer-to-peer` — Send Peer-to-Peer SMS — Peer-to-peer send: a different text per recipient group — fully personalized messages in one call.
- `POST /ws/v1/send/peer-to-peer-file` — Send Peer-to-Peer SMS from Excel — The same peer-to-peer, but the text/recipient pairs come from an Excel file.
- `POST /ws/v1/sms/bank` — Send to Number Bank — Targeted send to a Number Bank (ready-made numbers by trade/region) without owning a phonebook.
  - required: text, line_number, number_format
- `POST /ws/v1/sms/sample` — Send Sample SMS — Send a sample only to yourself, to test the text and sender line before a bulk campaign.
- `POST /ws/v1/sms/simple-file` — Send Simple SMS from Excel — Send a fixed text with the recipient list from an Excel file — for large lists.
- `GET /ws/v1/sms/voice/download-file` — Download Uploded Voice Message File — Re-download an uploaded voice file by its `file_id`.
- `POST /ws/v1/sms/voice/send` — Send Voice Message — Send a voice call (recorded message) to recipients; the audio must be uploaded first.
  - required: file_id
- `POST /ws/v1/sms/voice/upload-file` — Upload Voice Message File — Upload a voice file and get a `file_id` — the prerequisite of a voice send.

## مدیریت پترن (Patterns)
_Create & manage patterns — prerequisite of pattern send._

- `POST /ws/v1/patterns` — Create New Pattern — Create a new pattern (template) with variables; the prerequisite of pattern send. Needs approval after creation.
  - required: text, description, share, website, category, vars
- `GET /ws/v1/patterns` — Get List of User's Patterns — List your account's patterns; find a pattern's `code` here to send with it.
  - required: text, shared, website
- `PUT /ws/v1/patterns/{code}` — Edit Pattern — Edit an existing pattern's text or variables (may require re-approval).
  - required: text, shared, website
- `GET /ws/v1/patterns/{code}` — Get Pattern Details — View one pattern's details (variable names and count) so your send matches it exactly.
  - required: text, shared, website

## گزارش و دریافت (Reports & Inbox)
_After sending: delivery status and inbound messages._

- `GET /ws/v1/inbox` — Get Paged Inbox Messages — Read inbound messages (customer replies); poll this periodically to make the conversation two-way.
- `GET /ws/v1/send_request` — Get Send Requests — List all your sends with their overall status (queued, sent, rejected…); filter with `status`.
- `GET /ws/v1/send_request/{send_request_id}` — Show Send Request Details — View the details of one specific send by its id.
- `GET /ws/v1/send_request/{send_request_id}/items` — Get Send Request Items — Per-recipient delivery status inside one send (delivered, failed, blacklisted…).

## دفترتلفن و مخاطبین (Phonebook & Contacts)
_Manage contacts & groups for bulk sends._

- `GET /example/phone-book/{phone_book}/data.xlsx` — Get Bulk Excel Sample — Download that phonebook's sample Excel; fill the columns to match it — prerequisite of Excel import.
- `POST /ws/v1/phone_book` — Create New Phonebook — Create a new phonebook to group your contacts.
  - required: title
- `GET /ws/v1/phone_book` — Get Phonebooks — List your phonebooks and their ids.
- `PUT /ws/v1/phone_book/{id}` — Update Phonebook — Rename or change the columns of an existing phonebook.
  - required: title
- `POST /ws/v1/phone_book_attribute` — Create New Phonebook Attribute — Create a custom column/attribute (e.g. birthdate or national code) for contacts.
  - required: title, type
- `GET /ws/v1/phone_book_attribute` — Get Phonebook Attributes — List your defined attributes and their ids (to use when adding contacts).
- `POST /ws/v1/phone_book_data` — Add New Contact — Add a single contact to a phonebook.
- `GET /ws/v1/phone_book_data` — Get Phonebook Contacts — Get a phonebook's contacts with search and pagination.
- `POST /ws/v1/phone_book_data/bulk-upsert` — Add Bulk Contact — Bulk add/update contacts in a single call (up to 500 contacts).
- `POST /ws/v1/phone_book_data/excel-upsert` — Add Excel Contact — Import contacts from an Excel file, with no count limit.
- `DELETE /ws/v1/phone_book_data/{id}` — Delete Contact — Delete a contact by id (irreversible).

## حساب و کیف‌پول (Account & Wallet)
_Balance, charge, profile, lines and orders. (Balance = a free key test)_

- `GET /ws/v1/account/balance` — Account Balance — Check your balance; the best free test to confirm your API key works.
- `POST /ws/v1/account/wallet/charge` — Charge wallet — Charge your wallet (creates a payable order).
- `GET /ws/v1/account/profile` — Profile — Get your account profile (name and details).
- `POST /ws/v1/account/register` — Register — Register an account via the API (not needed just to send SMS).
- `POST /ws/v1/account/update` — update — Update your account information.
- `GET /ws/v1/lines/accessible` — Lines — List your usable sender lines; take the `line_number` value from here.
- `POST /ws/v1/orders/apply-discount` — Apply Discount on Order — Apply a discount code to an order before payment.
- `POST /ws/v1/orders/cancel` — Cancel an Order — Cancel an unpaid order.
- `POST /ws/v1/orders/pay` — Pay Created Order — Pay a created order (e.g. a wallet charge).

## پشتیبانی (Tickets)
_Support communication via API._

- `POST /ws/v1/ticket` — Create New Ticket — Open a new support ticket.
- `GET /ws/v1/ticket` — Get List of Tickets — List your support tickets (filter by status and department).
- `POST /ws/v1/ticket/closed` — Close Ticket — Close a ticket.
  - required: ticket_id
- `GET /ws/v1/ticket/file/download` — Download Ticket Attached File — Download a file attached to a ticket message.
- `POST /ws/v1/ticket/replay` — Replay to Ticket — Reply to an existing ticket.
- `GET /ws/v1/ticket/{id}` — Show Ticket Conversations — View a ticket's full conversation.

## مرجع و ابزار (Reference & Tools)
_Helper data: geo, genders, cost calc, number banks._

- `GET /cities` — Get Cities List of Provinces — List a province's cities (for targeted-send filters).
- `GET /provinces` — Get Provinces List — List provinces; with `has_any_banks`, only those that have a number bank.
- `GET /ws/v1/number_bank` — Get List of Avalibale Banks — List the available number banks for targeted sending (filter by province/city).
- `POST /ws/v1/sms/calculate-cost` — Send Postal Code SMS — Estimate the cost of a send (e.g. a postal-code send) before you run it.
  - required: text, number_format, line_id, schedule, filters
- `GET /ws/v1/sms/postal/get-available-lines` — Get Available Lines — Returns the lines allowed for postal-code sending.
- `GET /ws/v1/sms/postal/get-genders` — Get Genders List — Gender options for postal-code send filters.
- `GET /ws/v1/sms/postal/get-receiver-count` — Get Receiver Counts — Estimate the recipient count before a postal-code send, based on filters (postal code, gender, age range, prefix).

## ورود و حساب پنل (Panel Login & Account)
_These are for panel sign-in; NOT required to call the web services._

- `POST /ws/v1/auth/login` — Login — Logs a user into the panel (not API access). Use the Api-Key for API calls, not this.
- `POST /ws/v1/auth/logout` — Logout — Ends a panel session; unrelated to the web services.
- `POST /ws/v1/auth/register` — Register — Registers a panel user; not needed to use the APIs.
- `GET /ws/v1/auth/show_register_form` — Show Register Form — Returns the fields required by the panel's register form.
- `POST /ws/v1/auth/verify-2fa` — Verify 2fa — Verifies the two-factor code during panel login.