HomaCRM External API
The HomaCRM External API provides programmatic access to your HomaCRM portal. Send SMS messages, manage contacts, create support tickets, and integrate with your business applications.
https://www.HomaCRM.com/api/v1/external
curl samples use the value below —
replace it with the token from your portal (Settings → API).
a1B2c3D4e5F6g7H8-i9J0k1L2m3N4o5P6-q7R8s9T0u1V2w3X4
Who Can Use This API?
This API is available to all HomaCRM portal users with a valid API token. The Main Admin of each portal can generate and manage API tokens from the portal settings.
What Can You Do?
- Send SMS messages to your customers
- Manage your contact database (phonebook), deals and leads
- Create, reply to and follow up on support tickets
- Check your SMS credit balance
- Access message delivery reports
- Read warehouse inventory, invoices & payments, production orders and payroll summaries
Available Services
The API is organized into modules. Each module provides specific functionality.
Messaging
Send SMS, view reports, check credit, manage sender numbers
AvailableDrafts
Create and manage pre-written message templates
AvailableCRM
Manage contacts, groups, and customer information
AvailableSupport
Create tickets, track issues, manage support requests
AvailableFinance
Invoices with balances, payments, and the chart of accounts (read-only)
AvailableWarehouse
Products, categories, and live inventory levels (read-only)
AvailableProduction
Manufacturing orders with progress and BOM formulas (read-only)
AvailablePayroll
Periods, calculation runs (aggregate totals) and employee roster (read-only)
AvailableQuick Start Guide
Follow these steps to make your first API call.
Get Your API Token
Log in to your HomaCRM portal as Main Admin. Go to Settings > API Token and click Generate Token. Copy and save your token securely.
Test Your Connection
Make a request to verify your token is working:
curl -X GET "https://www.HomaCRM.com/api/v1/external/auth/verify" \
-H "Authorization: a1B2c3D4e5F6g7H8-i9J0k1L2m3N4o5P6-q7R8s9T0u1V2w3X4" \
-H "Accept: application/json"
Send Your First Message
Send an SMS message to test the messaging API:
curl -X POST "https://www.HomaCRM.com/api/v1/external/messaging/send" \
-H "Authorization: a1B2c3D4e5F6g7H8-i9J0k1L2m3N4o5P6-q7R8s9T0u1V2w3X4" \
-H "Content-Type: application/json" \
-d '{
"recipient": "09123456789",
"message": "سلام، سفارش شما ثبت شد. کد پیگیری: 987654",
"senderId": 42,
"serverType": 1
}'
Check the Response
A successful response looks like this:
{
"success": true,
"data": {
"messageId": 184920315,
"recipient": "09123456789",
"status": "queued",
"deliveryCode": 0,
"creditUsed": 1
},
"meta": {
"requestId": "req_abc123xyz"
}
}
Authentication
All API requests require authentication using your API token.
Sending Your Token
Include your token in the request header using one of these methods:
Method 1: Authorization Header (Recommended)
Authorization: a1B2c3D4e5F6g7H8-i9J0k1L2m3N4o5P6-q7R8s9T0u1V2w3X4
Method 2: X-API-Key Header
X-API-Key: a1B2c3D4e5F6g7H8-i9J0k1L2m3N4o5P6-q7R8s9T0u1V2w3X4
curl -X GET "https://www.HomaCRM.com/api/v1/external/auth/verify" \
-H "X-API-Key: a1B2c3D4e5F6g7H8-i9J0k1L2m3N4o5P6-q7R8s9T0u1V2w3X4" \
-H "Accept: application/json"
Verify Token Endpoint
Verify your token and get user information and permissions.
Example
curl -X GET "https://www.HomaCRM.com/api/v1/external/auth/verify" \
-H "Authorization: a1B2c3D4e5F6g7H8-i9J0k1L2m3N4o5P6-q7R8s9T0u1V2w3X4" \
-H "Accept: application/json"
Response
{
"success": true,
"data": {
"portalCode": "10003385",
"userId": 10042,
"isMainAdmin": true,
"scopes": [
"messaging:send",
"messaging:credit:read",
"messaging:numbers:read",
"messaging:reports:read",
"messaging:drafts:read",
"messaging:drafts:write",
"crm:contacts:read",
"crm:contacts:write",
"support:tickets:read",
"support:tickets:write"
]
}
}
Messaging
Send SMS messages, check credit balance, and view message reports.
Send Message
Send a single SMS message to one recipient. The server resolves the operator line from senderId and/or referenceId; see the table below.
Request Body
| Field | Type | Required | Valid values / constraints | Description |
|---|---|---|---|---|
recipient | string | Yes | Normalizes to 09XXXXXXXXX (11 digits). Also accepts forms like 98912…, +98912…, 00989…. | Destination mobile. |
message | string | Yes | Max 600 characters (API enforced). | SMS text. |
senderId | number or string | No | Line reference: one of your portal's active lines, either its ID from GET /messaging/numbers (e.g. 42) or the line number itself (e.g. 9890003259; 98…, +98… and 0098… forms are accepted).Black List: -11, or 99, or 100 (mapped to Black List).A value that matches one of your lines is always sent from that line. Otherwise the message still goes out — through the Black List path if the value looks like an Iranian mobile or is not a valid ID, or from your portal's default line for an unknown ID — and the response carries senderWarning. | Preferred way to choose the sending line. If set to a positive integer, referenceId in the body is ignored. |
referenceId | number | No | Integer > 0 (e.g. 5001) = same meaning as a positive senderId line ref. -11 = Black List. Omit or use Black List only if WhoIS for the portal is approved. | Use when you do not send a usable senderId. Ignored if senderId is a positive integer. |
serverType | number | No | Default 1 (typical dedicated-line send). If the request ends up on the Black List path (no valid line ref), the API sets serverType to 99 internally regardless of this field. | Operator / route hint passed to the SMS service for non–Black-List sends. |
otp_domain | string | No | Your site's hostname (e.g. shop.example.com). A one-time-code text (exactly one 4–8 digit number plus «کد», «رمز», code or OTP) gets a last line @domain #code after «لغو11», so iPhone and Android Chrome suggest the code. Omitted ⇒ taken from the default WordPress User-Agent (WordPress/x.y; https://www.site.tld ⇒ site.tld); neither ⇒ text unchanged. An existing line of that shape is not duplicated. | Adds about 20 characters; a text near 70 characters becomes two pages. |
Default behaviour: If both senderId and referenceId are missing or do not resolve to a positive line ID (and not Black List), the request uses the Black List path (serverType forced to 99), which requires an approved WhoIS profile for the portal.
Example — send via a dedicated line (from /messaging/numbers)
curl -X POST "https://www.HomaCRM.com/api/v1/external/messaging/send" \
-H "Authorization: a1B2c3D4e5F6g7H8-i9J0k1L2m3N4o5P6-q7R8s9T0u1V2w3X4" \
-H "Content-Type: application/json" \
-d '{
"recipient": "09129876543",
"message": "کد تأیید شما: 847291. اعتبار ۵ دقیقه.",
"senderId": 42,
"serverType": 1
}'
Example — same line using referenceId only (no senderId)
curl -X POST "https://www.HomaCRM.com/api/v1/external/messaging/send" \
-H "Authorization: a1B2c3D4e5F6g7H8-i9J0k1L2m3N4o5P6-q7R8s9T0u1V2w3X4" \
-H "Content-Type: application/json" \
-d '{
"recipient": "09129876543",
"message": "کد تأیید شما: 847291. اعتبار ۵ دقیقه.",
"referenceId": 42,
"serverType": 1
}'
Response
{
"success": true,
"data": {
"messageId": 184920315,
"recipient": "09129876543",
"status": "queued",
"deliveryCode": 0,
"creditUsed": 1
},
"meta": {
"requestId": "req_7f3a9c21b4e8"
}
}
Get Credit Balance
Get your current SMS credit balance.
Example
curl -X GET "https://www.HomaCRM.com/api/v1/external/messaging/credit" \
-H "Authorization: a1B2c3D4e5F6g7H8-i9J0k1L2m3N4o5P6-q7R8s9T0u1V2w3X4" \
-H "Accept: application/json"
Response
{
"success": true,
"data": {
"balance": 1250000,
"balanceToman": 125000,
"currency": "Rial",
"estimatedMessages": 62500,
"lastUpdated": "2026-05-09T12:34:56.789Z"
}
}
Get Sender Numbers
Get list of available sender numbers for your portal.
Example
curl -X GET "https://www.HomaCRM.com/api/v1/external/messaging/numbers" \
-H "Authorization: a1B2c3D4e5F6g7H8-i9J0k1L2m3N4o5P6-q7R8s9T0u1V2w3X4" \
-H "Accept: application/json"
Outbox Report
Get sent messages report with pagination.
Query Parameters
| Parameter | Type | Constraints | Description |
|---|---|---|---|
page | number | Integer ≥ 1 (default 1) | Page index. |
pageSize | number | Integer 1–100 (default 20) | Rows per page. |
dateFrom | string | Parseable date, e.g. 2026-05-01 | Filter sent at ≥ start of day. |
dateTo | string | Parseable date (end of day applied) | Filter sent at ≤ end of day. |
Example
curl -G "https://www.HomaCRM.com/api/v1/external/messaging/reports/outbox" \
-H "Authorization: a1B2c3D4e5F6g7H8-i9J0k1L2m3N4o5P6-q7R8s9T0u1V2w3X4" \
-H "Accept: application/json" \
--data-urlencode "page=1" \
--data-urlencode "pageSize=25" \
--data-urlencode "dateFrom=2026-05-01" \
--data-urlencode "dateTo=2026-05-09"
Get One Sent Message
Look up one sent SMS by the messageId that POST /messaging/send returned. Read-only; scope messaging:reports:read. Only messages of the token's portal are visible: an id that is not in this portal returns 404 (E3001), never another portal's data.
Path & Query Parameters
| Parameter | Type | Constraints | Description |
|---|---|---|---|
messageId | string (path) | Positive integer, up to 19 digits | The messageId from the send response. |
by | string | messageId (default) or id | Use id to look up by the row id that reports/delivery-log returns. |
Status: sent means the operator accepted the message. delivered appears only after the operator sends a delivery report; delivery reports are not guaranteed (some operators or handsets never send one), so a message can stay sent even when it arrived. failed means the operator reported it as not delivered. statusCode is the raw operator code. sentAt is server local time (Tehran), without a zone suffix.
Limits: a messageId lookup searches the portal's newest 200,000 sent messages (older ones: use reports/delivery-log and ?by=id), and at most 60 messageId lookups per minute per portal are answered (?by=id is not limited). A messageId of the form unverified-… (send accepted without an operator record id) is not a record id and always returns 404.
Errors: 400 E2003 invalid id or by; 404 E3001 not found in this portal (or not a record id); 409 E3003 portal moved to the new SMS node (report not available yet); 429 E1004 too many messageId lookups this minute.
Example
curl "https://www.HomaCRM.com/api/v1/external/messaging/reports/outbox/7739012845" \
-H "Authorization: a1B2c3D4e5F6g7H8-i9J0k1L2m3N4o5P6-q7R8s9T0u1V2w3X4" \
-H "Accept: application/json"
{
"success": true,
"data": {
"id": "48211903",
"messageId": "7739012845",
"recipient": "09121234567",
"message": "Your code is 4821",
"sentAt": "2026-11-15T10:30:12",
"status": "delivered",
"statusCode": 1,
"units": 1,
"programId": null,
"sentboxId": null
},
"meta": { "requestId": "req_abc123xyz" }
}
Inbox Report
Get received messages report.
Query Parameters
| Parameter | Type | Constraints | Description |
|---|---|---|---|
page | number | Integer ≥ 1 (default 1) | Page index. |
pageSize | number | Integer 1–100 (default 20) | Rows per page. |
dateFrom | string | Parseable date, e.g. 2026-05-01 | Filter received at ≥ start of day. |
dateTo | string | Parseable date (end of day applied) | Filter received at ≤ end of day. |
search | string | Any substring (SQL LIKE %search%) | Match sender mobile or message body. |
Example
curl -G "https://www.HomaCRM.com/api/v1/external/messaging/reports/inbox" \
-H "Authorization: a1B2c3D4e5F6g7H8-i9J0k1L2m3N4o5P6-q7R8s9T0u1V2w3X4" \
-H "Accept: application/json" \
--data-urlencode "page=1" \
--data-urlencode "pageSize=20" \
--data-urlencode "dateFrom=2026-05-01" \
--data-urlencode "dateTo=2026-05-09" \
--data-urlencode "search=0912"
Connecting accounting and POS software to Homa SMS
This section covers software such as Holoo, Parmis, Mahak, Negin, Dasht/Sepidar, and other products that let you configure a “custom web service”, “dedicated URL”, or “generic SMS provider” in their messaging settings.
The modern /messaging/send endpoint accepts JSON in the body and the token in a
header, but many accounting packages can only call a simple URL with username, password, and
query parameters PortalCode, ServerType, to, and
text. The /messaging/gateway endpoint accepts that legacy contract.
https://www.HomaCRM.com/api/v1/external/messaging/gateway,
username = API token, portal code = PortalCode, server type =
ServerType, recipient = to, message body = text.
Gateway endpoint
Send a single SMS using simple web-service parameters. Parameter names are case-insensitive; several aliases are accepted for each field.
| Parameter | Aliases | Required | Description |
|---|---|---|---|
username | user, uname | Yes | Portal API token. |
password | pass, apikey, api_key, apiKey, key, token | Alternative | API token when the software expects a separate password field. |
PortalCode | portalcode, portal_code | Recommended | Portal code, e.g. 10003385. |
ServerType | servertype, server_type | Recommended | Server/line type; e.g. 100 for public send / blacklist. |
to | mobile, recipient, receiver, phone | Yes | Recipient mobile; normalized to 09XXXXXXXXX. |
text | message, msg, body, content | Yes | Message text (max 600 characters). |
from | sender, line, number, senderid, sender_id | No | Sender line number (optional). |
format | output, response | No | text (default) or json. |
Software field → gateway parameter mapping
| Field in software | Gateway parameter | Value |
|---|---|---|
| Username (UserName) | username | API token |
| Portal code (PortalCode) | PortalCode | Portal code, e.g. 10003385 |
| Server type (ServerType) | ServerType | e.g. 100 |
| Recipient (To) | to | Recipient mobile number |
| Message text (Message) | text | SMS body |
Response format
By default the response is plain text: on success a positive
message ID is returned; on error a value less than or equal to
zero (0 = auth error, -2 = missing required field,
-4 = invalid number, -1 = send failure). Append
?format=json to receive the standard JSON envelope used elsewhere in this API.
Example — GET
curl -G "https://www.HomaCRM.com/api/v1/external/messaging/gateway" \
--data-urlencode "username=a1B2c3D4e5F6g7H8-i9J0k1L2m3N4o5P6-q7R8s9T0u1V2w3X4" \
--data-urlencode "PortalCode=10003385" \
--data-urlencode "ServerType=100" \
--data-urlencode "to=09129876543" \
--data-urlencode "text=Hello, your order is registered. Tracking code: 987654"
Example — POST (form)
curl -X POST "https://www.HomaCRM.com/api/v1/external/messaging/gateway" \
-d "username=a1B2c3D4e5F6g7H8-i9J0k1L2m3N4o5P6-q7R8s9T0u1V2w3X4" \
-d "PortalCode=10003385" \
-d "ServerType=100" \
-d "to=09129876543" \
-d "text=Your verification code: 847291"
Response (text)
184920315
Response (?format=json)
{
"success": true,
"data": {
"messageId": 184920315,
"recipient": "09129876543",
"status": "queued",
"deliveryCode": 10001,
"creditUsed": 1
},
"meta": { "requestId": "req_7f3a9c21b4e8" }
}
Common integration patterns
| Pattern | Homa connection |
|---|---|
| Custom web service / dedicated URL | Direct connection via this gateway. |
| SMS plugin with fixed providers | Direct only if a custom URL option exists; otherwise a dedicated adapter is required. |
| Corporate API / ERP | Prefer a dedicated adapter built on the Homa REST API. |
Software compatibility matrix
| Software | Typical status | Connection method | Notes |
|---|---|---|---|
| Holoo | Direct test possible when custom provider is supported | Custom web service | If URL and parameter names are configurable, this gateway is enough. |
| Holoo APEX | Version-dependent | Custom web service or adapter | If only fixed providers are listed, a dedicated adapter is needed. |
| Parmis | Official SMS module / gateway | SMS module or custom URL | Direct connection works only when the panel accepts a custom web service. |
| Mahak | Official SMS messenger plugin | Plugin or custom URL | If the plugin only supports fixed providers, HomaCRM must be added to the list or an adapter written. |
| Negin | Product-specific | Custom web service | Exact product name and version should be verified. |
| Dasht (Hamkaran System) | Official SMS subsystem | SMS subsystem or adapter | Direct connection only if the subsystem/plugin exposes a custom URL. |
| Sepidar | Plugin review required | Plugin / dedicated adapter | Many installations use fixed provider lists. |
| Rahkaran (Hamkaran System) | Adapter project usually required | Custom API / integration | For enterprise ERP, a simple URL setup is usually insufficient. |
| Shayegan, Ghyas, Ferdad, Arian System, Tadbir, Peyvast, Rafe | Depends on version and SMS module | Custom web service or adapter | Direct when to and text parameters are configurable. |
| Hesabfa, Chortke, and cloud accounting apps | Often API-driven or locked to built-in SMS | API / adapter | Check whether the service allows choosing a custom SMS panel. |
Holoo
On Holoo versions that support a custom SMS provider or web service, the usual path is Management settings → Provider settings. Create a new gateway and map parameter names as in the table below.
| Holoo field | Value |
|---|---|
| Panel name | HomaCRM (any label) |
| Site URL | https://www.HomaCRM.com/api/v1/external/messaging/gateway |
| Username | API token |
| UserName → parameter | username |
| PortalCode → parameter | PortalCode |
| ServerType → parameter | ServerType |
| To → parameter | to |
| Message → parameter | text |
Parmis, Mahak, Negin, and similar products
When messaging settings include a “custom / generic web service” option, use the values below. For Parmis and Mahak, first confirm the installed build is not limited to an official SMS module only.
| Field | Value |
|---|---|
| Web service URL | https://www.HomaCRM.com/api/v1/external/messaging/gateway |
| Username | API token |
| ServerType parameter | ServerType |
| Recipient parameter | to |
| Message parameter | text |
| PortalCode parameter | PortalCode |
Generic / custom web service (other software)
Any product that lets you define “web service URL + custom parameters” can connect
to Homa using the pattern below. The software sends GET or POST with
these parameters:
https://www.HomaCRM.com/api/v1/external/messaging/gateway?username={token}&PortalCode={portalCode}&ServerType={serverType}&to={mobile}&text={message}
Drafts
Manage pre-written message templates (drafts) for quick sending.
List Drafts
Get list of saved message drafts.
Query Parameters
| Parameter | Type | Constraints | Description |
|---|---|---|---|
page | number | Integer ≥ 1 (default 1) | Page index. |
pageSize | number | Integer 1–100 (default 20) | Rows per page. |
groupId | number | Positive integer (list category / ListCode) | Filter drafts in one group. |
search | string | Substring search | Matches Title or Message. |
Example
curl -G "https://www.HomaCRM.com/api/v1/external/messaging/drafts" \
-H "Authorization: a1B2c3D4e5F6g7H8-i9J0k1L2m3N4o5P6-q7R8s9T0u1V2w3X4" \
-H "Accept: application/json" \
--data-urlencode "page=1" \
--data-urlencode "pageSize=20" \
--data-urlencode "groupId=3" \
--data-urlencode "search=تخفیف"
Create Draft
Create a new message draft.
Request Body
| Field | Type | Required | Valid values / constraints | Description |
|---|---|---|---|---|
title | string | Yes | Max 500 characters | Draft title. |
message | string | Yes | Max 1000 characters | Template text (SMS page count derived on save). |
groupId | number | No | Positive integer or omit | ListCode / category. |
language | number | No | 1 = Persian, 2 = English (default: auto-detect from message text) | Stored language flag. |
Example
curl -X POST "https://www.HomaCRM.com/api/v1/external/messaging/drafts" \
-H "Authorization: a1B2c3D4e5F6g7H8-i9J0k1L2m3N4o5P6-q7R8s9T0u1V2w3X4" \
-H "Content-Type: application/json" \
-d '{
"title": "یادآوری قرار ملاقات",
"message": "کاربر گرامی، قرار شما فردا ساعت ۱۰ صبح در دفتر مرکزی است. اگر به تأخیر افتادید حتماً اطلاع دهید.",
"groupId": 3,
"language": 1
}'
Get Draft
Get a specific draft by ID.
Path
| Segment | Constraints | Description |
|---|---|---|
id | Positive integer (e.g. 10042) | Draft primary key in Portal_Messages. |
Example
curl -X GET "https://www.HomaCRM.com/api/v1/external/messaging/drafts/10042" \
-H "Authorization: a1B2c3D4e5F6g7H8-i9J0k1L2m3N4o5P6-q7R8s9T0u1V2w3X4" \
-H "Accept: application/json"
Update Draft
Request Body (partial update)
| Field | Type | Required | Valid values / constraints | Description |
|---|---|---|---|---|
title | string | No | Max 500 chars if present | New title. |
message | string | No | Max 1000 chars; updates SMS page count | New body. |
groupId | number | No | Positive integer | ListCode. |
language | number | No | 1 or 2 | Override language when updating message. |
At least one field must be supplied; otherwise the API returns “No fields to update”.
Example
curl -X PUT "https://www.HomaCRM.com/api/v1/external/messaging/drafts/10042" \
-H "Authorization: a1B2c3D4e5F6g7H8-i9J0k1L2m3N4o5P6-q7R8s9T0u1V2w3X4" \
-H "Content-Type: application/json" \
-d '{
"title": "یادآوری قرار ملاقات (ویرایش)",
"message": "قرار شما روز پنجشنبه ساعت ۹ بهجای ۱۰ برگزار میشود.",
"groupId": 3,
"language": 1
}'
Delete Draft
Delete a draft permanently.
Example
curl -X DELETE "https://www.HomaCRM.com/api/v1/external/messaging/drafts/10042" \
-H "Authorization: a1B2c3D4e5F6g7H8-i9J0k1L2m3N4o5P6-q7R8s9T0u1V2w3X4" \
-H "Accept: application/json"
Automated Scenarios (سناریو)
Read-only visibility of automated SMS scenarios: sequences of items attached to an audience (lead
category or contact group). Use these endpoints to see why a scenario does not send — nothing
here sends or edits. Scope: messaging:scenarios:read. The portal is always the token's portal
(or the acting portal from X-Homa-Portal).
List Scenarios
Query Parameters
| Param | Type | Description |
|---|---|---|
active | boolean | Optional — true only active, false only inactive. |
page, pageSize | number | Pagination; pageSize max 50. |
Each row: id, title, isActive, audience
(leadCategory / contactList resolved to
{ id, kind, title, memberCount, latestMemberAt } — latestMemberAt is when the newest
lead entered a lead category, null for other kinds),
itemCount, activeItemCount, smsItemCount,
runCountTotal (sum of item Runtimes) and lastMatchingSendAt
(newest sent-box row whose text equals an item body, last 180 days — heuristic).
Example
curl -G "https://www.HomaCRM.com/api/v1/external/messaging/scenarios" \
--data-urlencode "active=true" \
-H "Authorization: a1B2c3D4e5F6g7H8-i9J0k1L2m3N4o5P6-q7R8s9T0u1V2w3X4" \
-H "Accept: application/json"
Get Scenario
The list row plus items[], scenario findings[] and notes[].
Item fields
| Field | Description |
|---|---|
timing.mode | 1 = full interval (وقفه کامل): delayDays/delayHours/delayMinutes after the contact enters the audience · 2 = half interval (نیمهوقفه): delayDays + fixed time of day · 3 = fixed time (زمان ثابت): date + time. Also modeKey, modeLabelFa, summaryFa. |
sms, email, isActive, body | Channel flags and content. |
sender | Sender line resolved from the portal numbers: referenceType, referenceId, number, isBlackList, active, whoisStatus, blackListActive, mask. |
runCount | Recommender_Items.Runtimes — execution counter maintained by the sending worker, which lives outside this codebase (0 = never ran). |
lastMatchingSend | Newest Negin..Portal_SentBoxNew row with the same text in the last 180 days (sentBoxId, startedAt, programId, userId, referenceStr, comments, sentCount, totalCount, finished, statusOnClose), or null. Heuristic; labelled as such. |
findings[] | Read-only diagnostics (Persian): inactive, no channel, empty body, zero delay, missing time/date, past fixed time never run, sender line missing/inactive, sender line without an approved WhoIS status, never ran, ran without a matching send. |
Errors
E2003 invalid id · E3001 not found in this portal · E1003 missing scope.
Example
curl -X GET "https://www.HomaCRM.com/api/v1/external/messaging/scenarios/318" \
-H "Authorization: a1B2c3D4e5F6g7H8-i9J0k1L2m3N4o5P6-q7R8s9T0u1V2w3X4" \
-H "Accept: application/json"
Bulk Programs and Homa Audiences
Prepare a bulk SMS program (campaign) from the API with the same rules as the portal wizard. A program is
created, never started (playing: false); sending is a separate, explicit
POST /messaging/bulk. No phone number is ever returned — only counts, ids and names.
Create Program
Scope: messaging:bulk:create. (GET /messaging/programs lists programs with
messaging:bulk:read.) The message gets the same «لغو11» policy as the wizard (added on a normal
line, removed on a Mask line). With dryRun: true only the estimate is returned and nothing is stored.
Portals that send through the new SMS node answer 409 (NODE_PORTAL_UNSUPPORTED):
create those programs in the portal wizard for now.
Body
| Field | Type | Description |
|---|---|---|
title | string, 1–200 | Program title. |
message | string, 2–1000 | SMS text. |
senderId | number | An id from GET /messaging/numbers: -11 = Black List, otherwise an active, approved line of the portal. A line number is not accepted here. |
source | object | One of: { "type": "group", "groupIds": [..] } (ids from GET /crm/contacts/groups) · { "type": "mybank", "bankIds": [..] } (ids from audiences/options?kind=mybank_categories) · { "type": "system_bank", "bankCategory": 3|4|6, "int1": n, "selectedIds": [..], "postalFilter": "…" }. Any other type is 400. |
blacklistMode | 0|1|2 | Optional; the wizard's «exclude recipients of earlier programs». 2 + blacklistProgramIds = only those programs. |
justDelivered | boolean | Optional; wizard filter. |
dryRun | boolean | true = estimate only. |
system_bank: bankCategory 6 (jobs) — int1 = the bankId of the chosen rows, selectedIds = row ids from kind=job_categories_by_banks;
3 (cities / postal code) — int1 = the first selected id, selectedIds from kind=city_regions_by_banks and/or postalFilter;
4 (gender / age) — int1 = 50 gender or 51 age, selectedIds from kind=gender / kind=age.
Example
curl -X POST "https://www.HomaCRM.com/api/v1/external/messaging/programs" \
-H "Authorization: a1B2c3D4e5F6g7H8-i9J0k1L2m3N4o5P6-q7R8s9T0u1V2w3X4" \
-H "Content-Type: application/json" \
-d '{
"title": "معرفی مجموعهٔ پاییزه",
"message": "مجموعهٔ پاییزهٔ ما رسید. فهرست و قیمت: example.com/fall",
"senderId": 42,
"source": { "type": "system_bank", "bankCategory": 6, "int1": 1204, "selectedIds": [88213, 88214] },
"dryRun": true
}'
Response
{
"success": true,
"data": {
"dryRun": true,
"programId": null,
"playing": false,
"preparing": false,
"totalCount": 1840,
"totalCountIsEstimate": true,
"approximate": false,
"messageParts": 2,
"totalPages": 3680,
"costRial": 920000,
"costToman": 92000,
"balanceToman": 450000,
"hasEnoughCredit": true,
"senderId": 42,
"isMask": false,
"message": "…\nلغو11",
"messageAsSent": "…\nلغو11"
}
}
Without dryRun the answer is 201 with programId and preparing: true; the recipient list is
built in the background and the final totalCount appears on GET /messaging/programs/{id}.
Errors: E2003 invalid body / sender · E2001 zero audience (ZERO_AUDIENCE), estimate rejected, or node portal (409) · E1003 missing scope.
Audience Options
Scope: messaging:audiences:read. kind: job_provinces, job_categories,
job_categories_by_banks (needs banks), city_provinces, city_regions,
city_regions_by_banks (needs banks), gender, age, mybank_categories.
Optional provinces / banks = comma-separated ids. Items: { id, label, count, bankId?, lastUpdate? }.
Example
curl -G "https://www.HomaCRM.com/api/v1/external/messaging/audiences/options" \
--data-urlencode "kind=job_categories_by_banks" \
--data-urlencode "banks=1204" \
-H "Authorization: a1B2c3D4e5F6g7H8-i9J0k1L2m3N4o5P6-q7R8s9T0u1V2w3X4"
Audience Estimate
Scope: messaging:audiences:read. Body: { source, blacklistMode?, blacklistProgramIds?, justDelivered? }
(same source as Create Program). Returns { count, approximate } only; nothing is stored.
Example
curl -X POST "https://www.HomaCRM.com/api/v1/external/messaging/audiences/estimate" \
-H "Authorization: a1B2c3D4e5F6g7H8-i9J0k1L2m3N4o5P6-q7R8s9T0u1V2w3X4" \
-H "Content-Type: application/json" \
-d '{ "source": { "type": "system_bank", "bankCategory": 4, "int1": 50, "selectedIds": [2] } }'
CRM / Contacts
Manage your contact database (phonebook) and contact groups.
List Contacts
Get paginated list of contacts.
Query Parameters
| Parameter | Type | Constraints | Description |
|---|---|---|---|
page | number | Integer ≥ 1 (default 1) | Page index. |
pageSize | number | Integer 1–100 (default 20) | Rows per page. |
search | string | Substring (LIKE on name, company, mobiles) | Free-text filter. |
groupId | number | Maps to Category column | Only contacts in that group. |
Example
curl -G "https://www.HomaCRM.com/api/v1/external/crm/contacts" \
-H "Authorization: a1B2c3D4e5F6g7H8-i9J0k1L2m3N4o5P6-q7R8s9T0u1V2w3X4" \
-H "Accept: application/json" \
--data-urlencode "page=1" \
--data-urlencode "pageSize=30" \
--data-urlencode "search=رضا" \
--data-urlencode "groupId=5"
Create Contact
Create a new contact.
Request Body
| Field | Type | Required | Valid values / constraints | Description |
|---|---|---|---|---|
mobile | string | Yes | Must normalize to 09XXXXXXXXX; duplicate Mobile per portal → 409 | Primary mobile. |
firstName | string | No | Stored as NVARCHAR | First name. |
lastName | string | No | — | Last name. |
email | string | No | — | Email. |
companyName | string | No | — | Company title. |
groupId | number | No | Integer; Category | Contact group. |
mobile2 | string | No | Same mobile rules as mobile if provided | Second mobile. |
mobile3 | string | No | — | Third mobile. |
phone | string | No | Landline / tel | Stored in Tell. |
nationalCode | string | No | — | National ID. |
address | string | No | — | Postal address. |
city | number | No | Portal city dictionary ID | City. |
province | number | No | Portal province dictionary ID | Province. |
notes | string | No | — | Tozihat field. |
Example
curl -X POST "https://www.HomaCRM.com/api/v1/external/crm/contacts" \
-H "Authorization: a1B2c3D4e5F6g7H8-i9J0k1L2m3N4o5P6-q7R8s9T0u1V2w3X4" \
-H "Content-Type: application/json" \
-d '{
"mobile": "09121112233",
"firstName": "رضا",
"lastName": "کریمی",
"companyName": "فروشگاه نمونه آریا",
"email": "reza.karimi@example.com",
"mobile2": "09123334455",
"mobile3": "",
"phone": "02188776655",
"nationalCode": "0123456789",
"address": "تهران، خیابان ولیعصر، پلاک ۱۲۳، واحد ۴",
"city": 1001,
"province": 8,
"groupId": 5,
"notes": "مشتری وفادار؛ ترجیح تماس صبحها"
}'
Get Contact
Get a specific contact by ID.
Path
| Segment | Constraints | Description |
|---|---|---|
id | Positive integer (e.g. 55019) | ID in the portal customers table. |
Example
curl -X GET "https://www.HomaCRM.com/api/v1/external/crm/contacts/55019" \
-H "Authorization: a1B2c3D4e5F6g7H8-i9J0k1L2m3N4o5P6-q7R8s9T0u1V2w3X4" \
-H "Accept: application/json"
Update Contact
Update contact fields. Only keys you send are applied.
Request Body (partial)
| Field | Type | Valid values / constraints | Description |
|---|---|---|---|
firstName | string | — | First name. |
lastName | string | — | Last name. |
companyName | string | — | Company. |
mobile | string | Digits normalized (prefer 09…) | Primary mobile. |
mobile2 | string | — | Second mobile. |
mobile3 | string | — | Third mobile. |
phone | string | — | Landline (Tell). |
email | string | — | Email. |
address | string | — | Address. |
groupId | number | Integer | Category / group. |
notes | string | — | Notes (Tozihat). |
isActive | boolean | true / false | Soft-active flag. |
nationalCode, city, and province are not updated by this endpoint (create only).
Example
curl -X PUT "https://www.HomaCRM.com/api/v1/external/crm/contacts/55019" \
-H "Authorization: a1B2c3D4e5F6g7H8-i9J0k1L2m3N4o5P6-q7R8s9T0u1V2w3X4" \
-H "Content-Type: application/json" \
-d '{
"firstName": "رضا",
"lastName": "کریمی",
"companyName": "فروشگاه نمونه آریا (شعبه شمال)",
"mobile": "09121112233",
"mobile2": "09123334455",
"phone": "02188776655",
"email": "reza.karimi@example.com",
"address": "تهران، میدان تجریش، برومند ۹",
"groupId": 5,
"notes": "آخرین خرید: ۱۴۰۴/۰۲/۱۵",
"isActive": true
}'
Delete Contact
Delete (deactivate) a contact.
Example
curl -X DELETE "https://www.HomaCRM.com/api/v1/external/crm/contacts/55019" \
-H "Authorization: a1B2c3D4e5F6g7H8-i9J0k1L2m3N4o5P6-q7R8s9T0u1V2w3X4" \
-H "Accept: application/json"
List Contact Groups
Get list of contact groups/categories.
Example
curl -X GET "https://www.HomaCRM.com/api/v1/external/crm/contacts/groups" \
-H "Authorization: a1B2c3D4e5F6g7H8-i9J0k1L2m3N4o5P6-q7R8s9T0u1V2w3X4" \
-H "Accept: application/json"
Update Contact Group
Update an existing contact group. Scope: crm:groups:write.
Delete Contact Group
Delete a contact group. Use query moveMembersToGroupId to relocate members before deletion, or force=true to delete members without invoices (destructive). Scope: crm:groups:write.
Example
curl -X DELETE "https://www.HomaCRM.com/api/v1/external/crm/contacts/groups/6?moveMembersToGroupId=3" \
-H "Authorization: a1B2c3D4e5F6g7H8-i9J0k1L2m3N4o5P6-q7R8s9T0u1V2w3X4" \
-H "Accept: application/json"
List Pipelines
Get sales pipelines with their stages. Call this before creating a deal to obtain valid pipelineId and stageId. Scope: crm:deals:read.
Example
curl -X GET "https://www.HomaCRM.com/api/v1/external/crm/pipelines" \
-H "Authorization: a1B2c3D4e5F6g7H8-i9J0k1L2m3N4o5P6-q7R8s9T0u1V2w3X4" \
-H "Accept: application/json"
List Deals
Get paginated deals. Scope: crm:deals:read.
Query Parameters
| Parameter | Type | Description |
|---|---|---|
pipelineId | number | Filter by pipeline |
stageId | number | Filter by stage |
status | string | Filter by status (e.g. open, won, lost) |
search | string | Text search on the title |
page, pageSize | number | Pagination (pageSize max 100) |
Create Deal
Create a new deal. Scope: crm:deals:write.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
title | string | Yes | Deal title |
pipelineId | number | Yes | Pipeline ID (from List Pipelines) |
stageId | number | Yes | Stage ID within that pipeline |
amount | number | No | Deal value |
contactId | number | No | Linked contact |
Example
curl -X POST "https://www.HomaCRM.com/api/v1/external/crm/deals" \
-H "Authorization: a1B2c3D4e5F6g7H8-i9J0k1L2m3N4o5P6-q7R8s9T0u1V2w3X4" \
-H "Content-Type: application/json" \
-d '{
"title": "قرارداد سالانه فروشگاه نمونه",
"pipelineId": 1,
"stageId": 12,
"amount": 250000000
}'
Update Deal
Update an existing deal. Scope: crm:deals:write.
Delete Deal
Soft-delete a deal. Returns 204 No Content. Scope: crm:deals:write.
List Leads
Get paginated sales leads. Supports search, page, pageSize. Scope: crm:leads:read.
Create Lead
Register a new lead. All fields are optional, but include at least one identity field (title, firstName, lastName, companyName, mobile, or email). Scope: crm:leads:write.
Example
curl -X POST "https://www.HomaCRM.com/api/v1/external/crm/leads" \
-H "Authorization: a1B2c3D4e5F6g7H8-i9J0k1L2m3N4o5P6-q7R8s9T0u1V2w3X4" \
-H "Content-Type: application/json" \
-d '{
"firstName": "مریم",
"lastName": "احمدی",
"mobile": "09351234567",
"notes": "آشنایی در نمایشگاه"
}'
Update Lead
Update an existing lead. Scope: crm:leads:write.
Delete Lead
Soft-delete a lead. Returns 204 No Content. Scope: crm:leads:write.
List Automations (read-only)
Automations of the CRM module: name, triggerType
(lead_created, deal_stage_changed, ticket_created, contract_expiring),
isActive, runCount, lastRunAt and runs
(loggedRunCount, failedCount, lastRunAt, lastStatus from the run log, or
null when nothing was ever logged — the execution engine is not part of this API). Query:
search, isActive, triggerType, page,
pageSize. Scope: crm:automations:read.
Get Automation (read-only)
One automation with conditions, actions and recentRuns[]
(status, triggerRefType, triggerRefId, result, error,
createdAt; newest first, runsLimit ≤ 50, default 10). Scope: crm:automations:read.
Support / Tickets
Create and manage support tickets.
List Tickets
Get list of your support tickets.
Query Parameters
| Parameter | Type | Description |
|---|---|---|
page | number | Page number |
pageSize | number | Items per page (max 100) |
status | string | Filter: open, in_progress, closed |
Example
curl -G "https://www.HomaCRM.com/api/v1/external/support/tickets" \
-H "Authorization: a1B2c3D4e5F6g7H8-i9J0k1L2m3N4o5P6-q7R8s9T0u1V2w3X4" \
-H "Accept: application/json" \
--data-urlencode "page=1" \
--data-urlencode "pageSize=15" \
--data-urlencode "status=open"
Create Ticket
Create a new support ticket.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
title | string | Yes | Ticket title (max 200) |
description | string | Yes | Detailed description |
priority | number | No | Integer 1–4 only (1=normal, 2=important, 3=urgent, 4=critical); other values are rejected |
Example
curl -X POST "https://www.HomaCRM.com/api/v1/external/support/tickets" \
-H "Authorization: a1B2c3D4e5F6g7H8-i9J0k1L2m3N4o5P6-q7R8s9T0u1V2w3X4" \
-H "Content-Type: application/json" \
-d '{
"title": "خطا در وبهوک ارسال پیامک",
"description": "هر شب ساعت ۲۳:۱۰ درخواست POST به آدرس https://api.customer.example/hooks/sms با کد ۵۲۴ برمیگردد. شناسه درخواست نمونه: req_7f3a9c. لطفاً لاگ سمت سرور را بررسی کنید.",
"priority": 3
}'
Get Ticket
Get ticket details including comments.
Example
curl -X GET "https://www.HomaCRM.com/api/v1/external/support/tickets/12840" \
-H "Authorization: a1B2c3D4e5F6g7H8-i9J0k1L2m3N4o5P6-q7R8s9T0u1V2w3X4" \
-H "Accept: application/json"
Reply to Ticket
Add a reply to an existing ticket.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
content | string | Yes | Reply content (max 5000) |
Example
curl -X POST "https://www.HomaCRM.com/api/v1/external/support/tickets/12840/reply" \
-H "Authorization: a1B2c3D4e5F6g7H8-i9J0k1L2m3N4o5P6-q7R8s9T0u1V2w3X4" \
-H "Content-Type: application/json" \
-d '{
"content": "با سلام، فایروال سرور ما فقط IP های 185.143.x.x را مجاز کرده بود؛ رنج جدید شما را اضافه کردیم. لطفاً دوباره تست کنید و در صورت تکرار خطا، زمان دقیق (با timezone) را ارسال کنید."
}'
Ticket Actions (Follow-up / Request a Call)
Record an action on a ticket: request a follow-up (optionally urgent — raises the ticket priority) or request a phone callback. Closed tickets do not accept actions.
Request Body — followup
| Field | Type | Required | Description |
|---|---|---|---|
action | string | Yes | "followup" |
note | string | No | Optional note (max 2000) |
urgent | boolean | No | When true, the ticket priority is raised |
Request Body — request_call
| Field | Type | Required | Description |
|---|---|---|---|
action | string | Yes | "request_call" |
phone | string | Yes | Iranian mobile in 09xxxxxxxxx format |
preferredTime | string | No | Preferred time window (free text) |
note | string | No | Optional note (max 2000) |
Example
curl -X POST "https://www.HomaCRM.com/api/v1/external/support/tickets/12840/actions" \
-H "Authorization: a1B2c3D4e5F6g7H8-i9J0k1L2m3N4o5P6-q7R8s9T0u1V2w3X4" \
-H "Content-Type: application/json" \
-d '{
"action": "followup",
"note": "این مشکل جلوی راهاندازی ما را گرفته، لطفاً در اولویت بررسی شود.",
"urgent": true
}'
Warehouse
Read-only access to the product catalog, categories and live stock levels. Scopes: warehouse:products:read, warehouse:inventory:read.
List Products
Paginated product list. Query: search, categoryId, page, pageSize (max 100).
Example
curl -G "https://www.HomaCRM.com/api/v1/external/warehouse/products" \
-H "Authorization: a1B2c3D4e5F6g7H8-i9J0k1L2m3N4o5P6-q7R8s9T0u1V2w3X4" \
-H "Accept: application/json" \
--data-urlencode "search=لپتاپ" \
--data-urlencode "pageSize=20"
List Categories
Portal product categories with ID, name, warehouse ID, priority and active status.
Get Inventory
Live stock levels (net of confirmed in/out logs). Query: productId, search, page, pageSize.
Example
curl -G "https://www.HomaCRM.com/api/v1/external/warehouse/inventory" \
-H "Authorization: a1B2c3D4e5F6g7H8-i9J0k1L2m3N4o5P6-q7R8s9T0u1V2w3X4" \
-H "Accept: application/json" \
--data-urlencode "search=لپتاپ"
Finance
Invoices, payments and the chart of accounts. Read scopes: finance:invoices:read, finance:payments:read, finance:accounts:read; write scopes: finance:invoices:write, finance:payments:write. Every create and edit accepts an Idempotency-Key header (or requestId in the body; 8–128 chars of letters, digits, . _ : -): repeating the same key with the same content returns the first result (200, idempotentReplay: true) and creates nothing new; the same key with different content answers 409 IDEMPOTENCY_KEY_REUSED; a failed request stores nothing, so it can be retried with the same key.
List Invoices
Invoices with total, paid and remaining amounts.
Query Parameters
| Parameter | Type | Description |
|---|---|---|
search | string | Text search on invoice number / customer |
status | string | draft, ready, settled, balance (has remaining balance), credit |
dateFrom, dateTo | string | Date range, YYYY-MM-DD (Gregorian) |
page, pageSize | number | Pagination (pageSize max 100) |
Example
curl -G "https://www.HomaCRM.com/api/v1/external/finance/invoices" \
-H "Authorization: a1B2c3D4e5F6g7H8-i9J0k1L2m3N4o5P6-q7R8s9T0u1V2w3X4" \
-H "Accept: application/json" \
--data-urlencode "status=balance" \
--data-urlencode "dateFrom=2026-06-01"
Get Invoice
Invoice header plus line items (quantity, unit price, discount, line total) and payments. Sensitive internal fields are omitted.
List Payments
Payments and receipts. Query: search, invoiceId, customerId, direction=receive|pay, method=bank|cash|cheque, dateFrom, dateTo, page, pageSize (max 200). Each record has a direction of pay or receive, a methodLabel and the customerId. meta.totals = {receivedTotal, paidTotal, net} over the whole filtered set, in rial. Example: GET /finance/payments?customerId=7&direction=receive returns {"data":[{"id":88,"invoiceId":1201,"customerId":7,"amount":12500000,"methodLabel":"cash","direction":"receive","date":"2026-06-16T10:00:00.000Z"}],"meta":{"totalCount":1,"totals":{"receivedTotal":12500000,"paidTotal":0,"net":12500000}}}.
Record a Payment
Scope finance:payments:write. Body: amount (rial), operation receive|pay, method bank|cash|cheque (bankId for bank, chequeId for cheque, fundId for cash), invoiceId or customerId, date, comments, tagNumber. A near-identical payment within 60 seconds answers 409. Example: {"amount":12500000,"operation":"receive","method":"cash","invoiceId":1201,"requestId":"pay-1201-0001"} returns 201 {"id":90,"invoiceId":1201,"amount":12500000,"direction":"receive","method":"cash","invoiceStatus":"2"}.
Create an Invoice
Scope finance:invoices:write. Body: customerId, items[] (1–100: productId, quantity, optional unitPrice (defaults to the price list), discountPercent, taxPercent, comments), invoiceDiscount, comments, date, status draft|ready, type: 1 sale (default), 2 purchase, 3 sale return, 5 purchase return (official type 4 is not accepted). Example: {"customerId":4521,"type":2,"items":[{"productId":310,"quantity":2,"unitPrice":5000000}],"requestId":"po-2026-0042"} returns 201 {"id":1305,"serial":412,"customerId":4521,"status":"draft","total":10000000}.
Edit an Invoice
Scope finance:invoices:write. Edits a draft or ready invoice with the same rules as the Homa invoice form. Body (any subset): customerId, date, comments, invoiceDiscount, reference, status draft|ready, items[]. items replaces the lines: a line with id (from GET) is updated and keeps its price unless unitPrice is sent, a line without id is added at the price list price, an existing line left out is removed. Errors: 404 INVOICE_NOT_FOUND, PRODUCT_NOT_FOUND, CUSTOMER_NOT_FOUND; 409 INVOICE_LOCKED (checked), INVOICE_NOT_EDITABLE (settled, on balance or official), INVOICE_HAS_COMPANIONS; 403 PRICE_CHANGE_DENIED (changing the price of an existing line needs access code 351); 422 ITEM_NOT_IN_INVOICE. Deleting or cancelling invoices is not available through the API. Example: {"comments":"corrected","items":[{"id":5001,"productId":310,"quantity":3},{"productId":311,"quantity":1}]} returns {"id":1305,"serial":412,"status":"draft","total":15000000,"itemsCount":2,"itemIds":[5001,5002],"unit":"rial"}.
Chart of Accounts Tree
Three-level accounting coding hierarchy: group → total (کل) → secondary (معین).
Accounting: Documents, Balances and Statements
Accounting documents (سند حسابداری), account balances and the main statements. Scopes: finance:documents:read (documents and balances) and finance:reports:read (trial balance, income statement, balance sheet). The portal always comes from the token. Amounts are in rial ("currency": "IRR", "unit": "rial"). Every range accepts Gregorian dateFrom/dateTo (YYYY-MM-DD), Jalali jalaliFrom/jalaliTo (YYYY/MM/DD) or a Jalali fiscalYear (for example 1404); responses carry both calendars.
List accounting documents. Query: the date range, serial, search, accountId or accountCode (documents that touch the account), draft=exclude|only|all (default exclude), auto=all|only|exclude, page, pageSize (max 200). Scope finance:documents:read. Example: GET /finance/documents?jalaliFrom=1404/12/01&jalaliTo=1404/12/29&accountCode=1101 returns {"documents":[{"id":41,"serial":"7","date":"2026-03-01","dateJalali":"1404/12/10","title":"سند فروش","amount":5000000,"isDraft":false,"isAuto":false,"itemsCount":2}],"currency":"IRR","unit":"rial"} with meta pagination.
Raw ledger lines (ریزِ اسناد) to build any report or statement from: line date (Gregorian and Jalali), document serial, the account at all three levels (group, kol, moein with id, code, title), floating-detail ids (refs), description, debit, credit. Query: the date range (by line date), accountId or accountCode at any level, customerId, personId, bankId, cashId, serial, search, draft, auto, order=asc|desc, page, pageSize (max 1000). totals cover the whole filtered set, not just the page. Scope finance:documents:read. Example: GET /finance/documents/lines?fiscalYear=1404&accountCode=1101&pageSize=200 returns {"lines":[{"id":7,"documentId":41,"serial":"12","dateJalali":"1404/12/10","description":"شرح","debit":1000,"credit":0,"group":{"code":"11"},"kol":{"code":"1101"},"moein":{"code":"110101"},"refs":{"customerId":null,"bankId":8}}],"totals":{"debit":9000,"credit":9000,"difference":0},"unit":"rial"}.
Create a manual accounting document. Body: date (YYYY-MM-DD) or dateJalali, optional time, title, comments, isDraft, and lines[] (2–500) each with accountCode or accountId (leaf/moein account), whole-rial debit or credit (one side only), comment and, where the account has a floating detail, customerId / personId / bankId / cashId matching its kind. Debit must equal credit unless isDraft. Errors: 400 validation; 422 ACCOUNT_NOT_FOUND, ACCOUNT_NOT_LEAF, ACCOUNT_INACTIVE, DETAIL_REQUIRED, DETAIL_NOT_ALLOWED, DETAIL_NOT_FOUND; 409 FISCAL_YEAR_LOCKED. Scope finance:documents:write (a read-only token never writes). The portal always comes from the token. Idempotency: send an Idempotency-Key header (or requestId in the body; 8–128 chars of letters, digits, . _ : -). Repeating the same key with the same content returns the first result (200, idempotentReplay: true) and never creates a second document; the same key with different content answers 409 IDEMPOTENCY_KEY_REUSED. Failed requests store nothing, so they can be retried with the same key. Example: {"dateJalali":"1404/12/10","title":"سند آزمایشی","lines":[{"accountCode":"110101","debit":1000},{"accountCode":"410101","credit":1000}],"requestId":"doc-2026-0001"} returns 201 {"documentId":51,"serial":17,"linesCount":2,"totals":{"debit":1000,"credit":1000,"balanced":true},"unit":"rial"}.
One accounting document with its lines (account, debit, credit, floating-detail ids) and a balanced check. Scope finance:documents:read. Example: GET /finance/documents/41 returns {"document":{"id":41,"serial":"7","dateJalali":"1404/12/10","title":"سند فروش"},"items":[{"id":1,"accountCode":"1101","debit":5000000,"credit":0,"refs":{"customerId":null}},{"id":2,"accountCode":"4101","debit":0,"credit":5000000}],"totals":{"debit":5000000,"credit":5000000,"balanced":true},"unit":"rial"}.
Replace the header and lines of a manual document (same body as POST). 404 if absent; 409 DOCUMENT_READONLY for automatic documents, DOCUMENT_LINKED when payments, cheques or invoices point at it, DOCUMENT_FINAL when you try to turn a final document back into a draft, FISCAL_YEAR_LOCKED for a closed year. Drafts are excluded from every balance until they are finalized in the Homa app. Deleting or voiding documents is not available through the API. Scope finance:documents:write. Example: {"dateJalali":"1404/12/10","title":"سند اصلاحشده","lines":[{"accountCode":"110101","debit":1200},{"accountCode":"410101","credit":1200}]} returns {"documentId":41,"serial":7,"linesCount":2,"previous":{"linesCount":2,"debit":1000,"credit":1000},"unit":"rial"}.
One document with all its lines (account code and title, debit, credit, linked customer/person/bank/cash/payment/cheque/invoice ids) and totals.balanced. Scope finance:documents:read.
Opening balance, debit/credit turnover and closing balance per account — the same numbers as the account review screen (drafts excluded). Query: the date range, level=tree|group|kol|moein, balanceScope=all|range (range = turnover of the range only), search, includeZero. Scope finance:documents:read. Example: GET /finance/accounts/balances?fiscalYear=1404&level=kol returns {"accounts":[{"id":11,"code":"1101","title":"موجودی نقد","opening":0,"debit":1700,"credit":500,"balance":1200}],"unit":"rial"}.
Trial balance (تراز آزمایشی) at level=moein|kol|group with closing debit/credit columns, totals and balanced. Query: the date range, balanceScope, includeZero. Scope finance:reports:read. Example: GET /finance/reports/trial-balance?fiscalYear=1404&level=moein returns {"rows":[{"code":"110101","title":"صندوق","debit":1700,"credit":500,"closingDebit":1200,"closingCredit":0}],"totals":{"debit":1700,"credit":1700,"closingDebit":1200,"closingCredit":1200},"balanced":true,"unit":"rial"}.
Income statement (سود و زیان), the same report as the in-app screen. Query: fiscalYear (+ optional month 1-12) or a date range. Scope finance:reports:read. Example: GET /finance/reports/income-statement?fiscalYear=1404&month=3 returns the same statement as the Homa screen: {"summary":[],"income":{"rows":[],"total":0},"costs":{"rows":[],"total":0},"finalBenefit":0,"unit":"rial"}.
Balance sheet (ترازنامه) as of asOf / asOfJalali (default today). fourColumn is Homa's own account-browse balance as a four-column trial balance at group, kol and moein level (turnoverDebit, turnoverCredit, balanceDebit, balanceCredit, cumulative up to the date). The response also splits balance-sheet accounts split by the sign of their balance (debit = assets, credit = liabilities and equity) plus the accumulated profit of profit-and-loss accounts. A simple reproducible definition, not a statutory statement. Scope finance:reports:read. Example: GET /finance/reports/balance-sheet?asOfJalali=1404/12/29 returns {"asOf":"2026-03-20","fourColumn":{"moein":{"rows":[{"code":"110101","turnoverDebit":1700,"turnoverCredit":500,"balanceDebit":1200,"balanceCredit":0}],"balanced":true}},"assets":{"total":1200},"currentProfit":1200,"unit":"rial"}.
Treasury: Banks, Funds, Cheques and Transfers
Bank accounts, cash funds and cheques. Scopes: finance:treasury:read (reads) and finance:treasury:write (transfers; administrator tokens only by default). Balances and ledgers use the same ledger rows as the account review; positive = money held. Amounts are rial.
Bank accounts (account numbers masked to the last 4 digits). Query: activeOnly. Example response: {"data":[{"id":3,"title":"ملت","accountNumber":"****1234","branchTitle":"مرکزی","isActive":true}]}.
Cash funds (صندوق). Query: activeOnly. Example response: {"data":[{"id":2,"title":"صندوق مرکزی","comments":null,"isActive":true}]}.
Cheques. Query: type=received|issued, position (comma list: inventory, in_collection_bank, collected, uncollected_relatives, uncollected_payable_docs, returned_receivable, spent_receivable, void, expensed, petty_cash, cashier, no_document, supplier), customerId, bankId, search, dueFrom/dueTo, regFrom/regTo (YYYY-MM-DD), page, pageSize (max 200). Each cheque has positionKey and positionLabel (where it is now; status is an internal number). meta.totals.totalAmount covers the whole filter. Example: GET /finance/treasury/cheques?type=received&position=in_collection_bank returns {"data":[{"id":45,"type":"received","positionKey":"in_collection_bank","positionLabel":"درجریان وصول-نزد بانک","chequeNumber":"123456","amount":50000000,"customerName":"علی رضایی","dueDate":"2026-07-10T00:00:00.000Z"}],"meta":{"totalCount":1,"totals":{"totalAmount":50000000}}}.
Balance of every bank account and cash fund. Query: asOf / asOfJalali (default all time), kind=bank|fund|all. Example response: {"accounts":[{"kind":"bank","id":3,"title":"ملت","debit":9000,"credit":4000,"balance":5000},{"kind":"fund","id":2,"title":"صندوق مرکزی","debit":1500,"credit":300,"balance":1200}],"totals":{"banks":5000,"funds":1200,"all":6200},"unit":"rial"}.
Ledger of one bank account (and /finance/treasury/funds/{id}/ledger for a fund): opening balance, lines with document serial, cheque and payment ids and a running balance, closing balance. Query: the date range (dateFrom/dateTo, jalaliFrom/jalaliTo or fiscalYear), page, pageSize (max 1000). 404 if the id is not in your portal. Example: GET /finance/treasury/banks/3/ledger?fiscalYear=1404 returns {"account":{"kind":"bank","id":3,"title":"ملت"},"summary":{"openingBalance":0,"debit":9000,"credit":4000,"closingBalance":5000},"lines":[{"dateJalali":"1404/12/10","documentSerial":"7","debit":9000,"credit":0,"runningBalance":9000}],"unit":"rial"}.
Ledger of one cash fund; same query and response shape as the bank ledger with account.kind = fund. Example: GET /finance/treasury/funds/2/ledger?jalaliFrom=1404/12/01 returns {"account":{"kind":"fund","id":2,"title":"صندوق مرکزی"},"summary":{"openingBalance":0,"debit":1500,"credit":300,"closingBalance":1200},"lines":[{"dateJalali":"1404/12/05","documentSerial":"3","debit":1500,"credit":0,"runningBalance":1500}],"unit":"rial"}.
Scope finance:treasury:write. Moves money between two bank accounts or cash funds by posting a balanced two-line accounting document (debit the destination, credit the source). Body: from and to as {"type":"bank"|"fund","id":N}, amount (whole rial), date or dateJalali, optional time and comment. Errors: 400 validation (same account both sides, non-positive amount); 422 DETAIL_NOT_FOUND (bank or fund not in your portal), TREASURY_ACCOUNT_NOT_CONFIGURED; 409 FISCAL_YEAR_LOCKED. Idempotency-Key header (or requestId in the body) is required: without it the call answers 400 IDEMPOTENCY_KEY_REQUIRED, so a client retry can never move money twice. A repeat returns the first transfer (200, idempotentReplay); the same key with different content answers 409. Example: {"from":{"type":"fund","id":2},"to":{"type":"bank","id":3},"amount":5000000,"dateJalali":"1404/12/10","comment":"واریز به بانک","requestId":"xfer-2026-0001"} returns 201 {"documentId":52,"serial":18,"linesCount":2,"amount":5000000,"from":{"type":"fund","id":2},"to":{"type":"bank","id":3},"unit":"rial"}. Cheque life-cycle operations (collect, bounce, endorse) are not available yet.
Counterparties: Balances, Statement and Aging
Customers and suppliers (طرفحساب) with the same definition as Homa's persons sub-ledger. Positive balance = the counterparty owes us. Scope finance:reports:read. Amounts are rial.
Balance per counterparty. Query: asOf / asOfJalali (default today), direction=debtor|creditor|all, minAbsBalance, search (name, company, mobile), includeZero, sort=balance_desc|balance_asc|name|last_activity, page, pageSize (max 500). totals (debtors, creditors, net) cover the whole filter. Example response: {"counterparties":[{"customerId":7,"name":"علی رضایی","debit":1000,"credit":100,"balance":900,"direction":"debtor","lastActivityJalali":"1404/12/10"}],"totals":{"debtors":900,"creditors":200,"net":700},"unit":"rial"}
Statement of one counterparty: opening balance, lines with document serial, invoice serial and running balance, closing balance. Query: the date range (dateFrom/dateTo, jalaliFrom/jalaliTo or fiscalYear), page, pageSize (max 1000). 404 if the id is not in your portal. Example: GET /finance/counterparties/7/statement?fiscalYear=1404 returns {"summary":{"openingBalance":500,"debit":300,"credit":100,"closingBalance":700},"lines":[{"dateJalali":"1404/12/10","documentSerial":"7","invoiceSerial":"88","debit":300,"credit":0,"runningBalance":800}]}.
Receivables aging: open debit per counterparty by age. Credits are applied to the oldest debits first; leftover credit is unappliedCredit. Query: asOf / asOfJalali, buckets (ascending day boundaries, default 30,60,90, 1-6 values), search, limit (max 500). Example response: {"buckets":[{"label":"0-30","amount":250},{"label":"31-60","amount":0},{"label":"61-90","amount":0},{"label":"91+","amount":0}],"totalReceivable":250,"unappliedCredit":40,"counterparties":[{"customerId":7,"buckets":[250,0,0,0],"total":250}],"unit":"rial"}
Production
Read-only access to manufacturing orders and BOM formulas. Scopes: production:orders:read, production:formulas:read.
List Production Orders
Manufacturing orders with planned/produced quantities and status. Query: status, search, page, pageSize.
Get Production Order
Full order detail including child operations/steps. Cost-related fields are intentionally not exposed.
List Formulas (BOM)
Production formulas with output product and components. Query: search, page, pageSize.
Payroll
Read-only access to payroll periods, calculation runs and the employee roster. Scopes: payroll:periods:read, payroll:runs:read, payroll:employees:read.
List Periods
Payroll periods. Query: year, status, page, pageSize.
List Calculation Runs
Calculation runs with employee count and aggregate gross/deductions/net totals. Query: periodId, status, page, pageSize.
Get Run Summary
Aggregate totals for a single run — individual payslip lines are intentionally omitted.
List Employees
Active employee roster with summary identity fields only: id, firstName, lastName, fullName, isActive, payrollStatus (no salary, national code or bank data). There is no name, code or status field. Query: search, page, pageSize.
{ "success": true, "data": [ { "id": 168991, "firstName": "Sara", "lastName": "Ahmadi", "fullName": "Sara Ahmadi", "isActive": true, "payrollStatus": null } ], "meta": { "page": 1, "pageSize": 20, "totalCount": 1, "totalPages": 1, "hasMore": false } }
GET /payroll/employees/{id} returns the same fields plus username and mobile. To create a user or an employee, the portal main admin uses POST /admin/users below; everyone else uses the panel (/settings/users).
Portal Users & Employees (main admin only)
Only the active main admin of the same portal can use these endpoints: the token needs admin:users:read / admin:users:write (main-admin and Homa Copilot mirror tokens of a main admin have them), and the caller's HR row is checked live on every request (MainAdmin = 1, active). Acting on another portal with X-Homa-Portal is refused (403 / E1009). Any other caller gets 403 / E1003. Every create, activate, deactivate and password change, and every refused write, is written to an audit log; if the log is unreachable no write is made (503 / E9002). Passwords are never returned or logged. A new user has no roles; assign access in the panel (/settings/users).
All users (with login) and employees (without login) of the portal, active and inactive. Query: search (name, username, mobile), isActive (true/false), isUser (true/false), page, pageSize (max 100). Fields: id, username (null for employees), firstName, lastName, fullName, nickName, mobile, extension, isUser, isActive, isMainAdmin.
Example
curl "https://www.HomaCRM.com/api/v1/external/admin/users?isActive=false" \
-H "Authorization: a1B2c3D4e5F6g7H8-i9J0k1L2m3N4o5P6-q7R8s9T0u1V2w3X4"
{ "success": true, "data": [ { "id": 168991, "username": "sara", "firstName": "Sara", "lastName": "Ahmadi", "fullName": "Sara Ahmadi", "nickName": "Sara", "mobile": "09121234567", "extension": "12", "isUser": true, "isActive": false, "isMainAdmin": false } ], "meta": { "page": 1, "pageSize": 20, "totalCount": 1, "totalPages": 1, "hasMore": false } }
Create a portal user or an employee. Body fields (anything else is rejected with 422, nothing is created): firstName*, lastName*, nickName, mobile, extension, isUser (default true: can log in), isActive (default true), and for users username* (unique in the portal, no spaces) and optional password (6–128 characters). Without a password the user sets one through «forgot password» with an SMS code to their own mobile, or the admin sets it later with PATCH /admin/users/{id}. An employee (isUser: false) takes no username or password. Main admins cannot be created here. Errors: 409 / E3002 username taken, 422 / E2002, E2003 invalid body.
Example
curl -X POST "https://www.HomaCRM.com/api/v1/external/admin/users" \
-H "Authorization: a1B2c3D4e5F6g7H8-i9J0k1L2m3N4o5P6-q7R8s9T0u1V2w3X4" \
-H "Content-Type: application/json" \
-d '{ "firstName": "Mina", "lastName": "Rahimi", "username": "mina", "password": "••••••", "mobile": "09121234567" }'
{ "success": true, "data": { "user": { "id": 168992, "username": "mina", "firstName": "Mina", "lastName": "Rahimi", "fullName": "Mina Rahimi", "nickName": "Mina Rahimi", "mobile": "09121234567", "extension": null, "isUser": true, "isActive": true, "isMainAdmin": false }, "passwordSet": true, "accessNote": "New users start with no roles; assign access in the panel (/settings/users)." } }
One user or employee of the portal (same fields as the list). 404 / E3001 when the id is not in this portal.
Example
curl "https://www.HomaCRM.com/api/v1/external/admin/users/168992" \
-H "Authorization: a1B2c3D4e5F6g7H8-i9J0k1L2m3N4o5P6-q7R8s9T0u1V2w3X4"
Activate / deactivate (isActive) and/or set the password (password, users only). Other fields are rejected with 422; change them in the panel. The only active main admin of the portal cannot be deactivated, a main admin cannot deactivate themselves through the API, and no main admin's password can be set here (panel only). Both fields sent together are written in one update. Sending the current state changes nothing. The response shows changes.isActive as before / after.
Example
curl -X PATCH "https://www.HomaCRM.com/api/v1/external/admin/users/168992" \
-H "Authorization: a1B2c3D4e5F6g7H8-i9J0k1L2m3N4o5P6-q7R8s9T0u1V2w3X4" \
-H "Content-Type: application/json" \
-d '{ "isActive": false }'
{ "success": true, "data": { "user": { "id": 168992, "username": "mina", "isActive": false, "...": "..." }, "changes": { "isActive": { "before": true, "after": false, "changed": true } } } }
System
System status and information endpoints.
API Status
Get current API status and service availability.
Example
curl -X GET "https://www.HomaCRM.com/api/v1/external/system/status" \
-H "Authorization: a1B2c3D4e5F6g7H8-i9J0k1L2m3N4o5P6-q7R8s9T0u1V2w3X4" \
-H "Accept: application/json"
Available Packages
Get list of available API modules and their status.
Example
curl -X GET "https://www.HomaCRM.com/api/v1/external/system/packages" \
-H "Authorization: a1B2c3D4e5F6g7H8-i9J0k1L2m3N4o5P6-q7R8s9T0u1V2w3X4" \
-H "Accept: application/json"
Utilities / ابزارهای کاربردی
Offline helper endpoints computed entirely on the Homa server — no third-party calls. Available to any valid token (no extra scope).
Server Date/Time
Reference "now": UTC instant plus Gregorian and Jalali (شمسی) representations in the requested IANA timezone (default Asia/Tehran). Query: timezone, withSeconds.
Example
curl -X GET "https://www.HomaCRM.com/api/v1/external/utilities/datetime?timezone=Asia/Tehran" \
-H "Authorization: YOUR_TOKEN" \
-H "Accept: application/json"
Response
{
"success": true,
"data": {
"utcIso": "2026-07-04T16:20:00.000Z",
"unixMs": 1783268400000,
"timezone": "Asia/Tehran",
"gregorian": { "date": "2026-07-04", "time": "19:50:00", "weekday": "Saturday" },
"jalali": { "date": "1405/04/13", "time": "19:50:00", "weekday": "شنبه", "monthName": "تیر" },
"serverSource": "sql"
}
}
QR Code Generation
Encode text or a URL into a QR code. Returns JSON with a base64 PNG data URL (or SVG markup) — the payload never leaves the Homa server.
Request Body
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
text | string | Yes | — | Text or URL to encode (max 2000 characters) |
size | number | No | 400 | PNG width/height in pixels (100–800) |
format | string | No | png | png (data URL) or svg (markup) |
errorCorrectionLevel | string | No | M | L/M/Q/H |
margin | number | No | 2 | Quiet-zone margin in modules (0–8) |
Example
curl -X POST "https://www.HomaCRM.com/api/v1/external/utilities/qrcode" \
-H "Authorization: YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "text": "https://homacrm.com", "size": 400, "format": "png" }'
Response
{
"success": true,
"data": {
"format": "png",
"size": 400,
"textLength": 19,
"dataUrl": "data:image/png;base64,iVBORw0KGgo..."
}
}
Deputy / نمایندگان
API endpoints for portal deputies (نمایندگان). These endpoints are only available to portals registered as deputies in the system.
Create Portal
Create new portals under your deputy management. Shahkar verification is performed automatically.
Create new portal with automatic Shahkar verification.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
firstName | string | Yes | First name (Persian) |
lastName | string | Yes | Last name (Persian) |
mobile | string | Yes | Mobile number (09XXXXXXXXX) |
email | string | Yes | Email address |
nationalCode | string | Yes | 10-digit national code |
edition | string | Yes | "sms" or "full" |
skipShahkar | boolean | No | Skip Shahkar verification (default: false) |
Response
| Field | Type | Description |
|---|---|---|
portalCode | number | New portal code |
username | string | Admin username |
password | string | Admin password |
shahkarVerified | boolean | Whether Shahkar was verified |
Example
curl -X POST "https://www.HomaCRM.com/api/v1/external/deputy/portal/create" \
-H "Authorization: YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"firstName": "علی",
"lastName": "محمدی",
"mobile": "09121234567",
"email": "ali@example.com",
"nationalCode": "1234567890",
"edition": "sms"
}'
Sub-Portal Management
List Sub-Portals
Get list of all portals under your management.
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
page | number | 1 | Page number |
pageSize | number | 20 | Items per page (max 100) |
search | string | - | Search by code, name, mobile |
status | string | all | Filter: active, inactive, all |
Get Portal Details
Get detailed information about a sub-portal.
Update Portal
Update sub-portal information (limited fields).
Request Body
| Field | Type | Description |
|---|---|---|
title | string | Portal title |
companyName | string | Company name |
ownerFirstName | string | Owner first name |
ownerLastName | string | Owner last name |
email | string | Email address |
isActive | boolean | Active status |
Get Portal Credit
Get SMS credit balance for a sub-portal.
Get Portal Stats
Get statistics for a sub-portal (SMS, contacts, activity).
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
period | string | 30d | Time period: 7d, 30d, 90d, all |
Deputy Statistics
Overall Stats
Get overall statistics for your deputy network.
Response
| Field | Type | Description |
|---|---|---|
deputyCode | number | Your deputy code |
totalPortals | number | Total sub-portals |
activePortals | number | Active sub-portals |
inactivePortals | number | Inactive sub-portals |
totalSmsCredit | number | Total SMS credit across all |
portalsCreatedThisMonth | number | New portals this month |
topPortals | array | Top 5 portals by credit |
Error Codes
When an error occurs, the API returns a structured error response:
{
"success": false,
"error": {
"code": "E1001",
"message": "Invalid or malformed token",
"requestId": "req_abc123xyz"
}
}
Error Code Reference
| Code | HTTP | Description |
|---|---|---|
E1001 | 401 | Invalid or malformed token |
E1003 | 403 | Insufficient permissions |
E1004 | 429 | Rate limit exceeded |
E1005 | 401 | Authentication token required |
E2001 | 400 | Invalid request format |
E2002 | 400 | Required field is missing |
E4001 | 422 | Insufficient SMS credit |
E4002 | 400 | Invalid recipient number |
E4003 | 400 | Message too long |
E7001 | 404 | Contact not found |
E7006 | 409 | Duplicate mobile number |
E8001 | 404 | Ticket not found |
E8002 | 423 | Ticket is closed |
E9001 | 500 | Internal server error |
Rate Limits
To ensure fair usage, the API enforces rate limits on all endpoints.
100 requests per minute per API token
Rate Limit Headers
Every response includes these headers:
| Header | Description |
|---|---|
X-RateLimit-Limit | Maximum requests allowed |
X-RateLimit-Remaining | Requests remaining in window |
X-RateLimit-Reset | When the limit resets (ISO 8601) |
Handling Rate Limits
When you exceed the rate limit, you'll receive a 429 Too Many Requests response.
Wait until the reset time before making more requests.