FarazSMS SMS web service — REST API and SDK documentation

Official documentation for the FarazSMS (IranPayamak) SMS REST API: pattern send, one-time passwords (OTP), bulk and quick send, delivery reports, phonebook and wallet. Base URL: https://api.iranpayamak.com — authentication with the Api-Key header (key from the panel, case-sensitive; no login flow).

Official SDKs: pip install farazsms · npm install farazsms · composer require farazsms/php · composer require farazsms/laravel · dotnet add package FarazSMS · go get github.com/ghaffari273/farazsms-go.

Guides and tools (written in Persian): SDKs and client libraries · error and delivery-status reference · task recipes · glossary · send over a plain URL · Node-RED · webhook gateway · OpenAPI and Postman

Web services by category (64 endpoints)

ارسال پیامک — 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.
• POST /ws/v1/sms/simple — Send Simple SMS — Write your own text and send it to one or many numbers — the simplest way to start and to smoke-test your integration. Good for announcements and bulk marketing. Messages pass human moderation first, so delivery can take minutes; for verification codes and anything that must arrive in under 5 seconds, use Pattern send.
• 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 /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/sms/bank — Send to Number Bank — Targeted send to a Number Bank (ready-made numbers by trade/region) without owning a phonebook.
• POST /ws/v1/sms/postal/send — Send Postal Code SMS
• 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.
• POST /ws/v1/sms/voice/calculate-cost — Calculate Voice Message Cost
• 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.
• 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.
• 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.
• PUT /ws/v1/patterns/{code} — Edit Pattern — Edit an existing pattern's text or variables (may require re-approval).
• GET /ws/v1/patterns/{code} — Get Pattern Details — View one pattern's details (variable names and count) so your send matches it exactly.
• DELETE /ws/v1/patterns/{code} — Delete Pattern — Permanently delete one of your own patterns by its code — for clearing out test and retired patterns.

گزارش و دریافت — 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.
• 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.
• POST /ws/v1/phone_book_attribute — Create New Phonebook Attribute — Create a custom column/attribute (e.g. birthdate or national code) for contacts.
• 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.
• GET /ws/v1/ticket/file/download — Download Ticket Attached File — Download a file attached to a ticket message.
• POST /ws/v1/ticket/reply — Replay to 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).
• GET /ws/v1/number_bank/{number_bank_id} — Get Number Bank Details — Full detail of one number bank — title, province, city and attached files.
• POST /ws/v1/sms/calculate-cost — Calculate Send SMS Cost — Estimate the cost of a send (e.g. a postal-code send) before you run it.
• 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.

For AI agents: llms.txt · llms-full.txt · OpenAPI.

مستندات فارسی