HomaCRM API

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.

Base URL
https://www.HomaCRM.com/api/v1/external
Example token in this page: all 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

Available

Drafts

Create and manage pre-written message templates

Available

CRM

Manage contacts, groups, and customer information

Available

Support

Create tickets, track issues, manage support requests

Available

Finance

Invoices with balances, payments, and the chart of accounts (read-only)

Available

Warehouse

Products, categories, and live inventory levels (read-only)

Available

Production

Manufacturing orders with progress and BOM formulas (read-only)

Available

Payroll

Periods, calculation runs (aggregate totals) and employee roster (read-only)

Available

Quick 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"
Note: Your API token does not expire. However, regenerating a new token will invalidate the previous one immediately.

Verify Token Endpoint

GET /auth/verify

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

POST /messaging/send

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

FieldTypeRequiredValid values / constraintsDescription
recipientstringYesNormalizes to 09XXXXXXXXX (11 digits). Also accepts forms like 98912…, +98912…, 00989….Destination mobile.
messagestringYesMax 600 characters (API enforced).SMS text.
senderIdnumber or stringNoLine 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.
referenceIdnumberNoInteger > 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.
serverTypenumberNoDefault 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_domainstringNoYour 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 /messaging/credit

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 /messaging/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 /messaging/reports/outbox

Get sent messages report with pagination.

Query Parameters

ParameterTypeConstraintsDescription
pagenumberInteger ≥ 1 (default 1)Page index.
pageSizenumberInteger 1–100 (default 20)Rows per page.
dateFromstringParseable date, e.g. 2026-05-01Filter sent at ≥ start of day.
dateTostringParseable 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

GET /messaging/reports/outbox/{messageId}

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

ParameterTypeConstraintsDescription
messageIdstring (path)Positive integer, up to 19 digitsThe messageId from the send response.
bystringmessageId (default) or idUse 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 /messaging/reports/inbox

Get received messages report.

Query Parameters

ParameterTypeConstraintsDescription
pagenumberInteger ≥ 1 (default 1)Page index.
pageSizenumberInteger 1–100 (default 20)Rows per page.
dateFromstringParseable date, e.g. 2026-05-01Filter received at ≥ start of day.
dateTostringParseable date (end of day applied)Filter received at ≤ end of day.
searchstringAny 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.

Quick setup: URL = 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

GET POST /messaging/gateway

Send a single SMS using simple web-service parameters. Parameter names are case-insensitive; several aliases are accepted for each field.

ParameterAliasesRequiredDescription
usernameuser, unameYesPortal API token.
passwordpass, apikey, api_key, apiKey, key, tokenAlternativeAPI token when the software expects a separate password field.
PortalCodeportalcode, portal_codeRecommendedPortal code, e.g. 10003385.
ServerTypeservertype, server_typeRecommendedServer/line type; e.g. 100 for public send / blacklist.
tomobile, recipient, receiver, phoneYesRecipient mobile; normalized to 09XXXXXXXXX.
textmessage, msg, body, contentYesMessage text (max 600 characters).
fromsender, line, number, senderid, sender_idNoSender line number (optional).
formatoutput, responseNotext (default) or json.

Software field → gateway parameter mapping

Field in softwareGateway parameterValue
Username (UserName)usernameAPI token
Portal code (PortalCode)PortalCodePortal code, e.g. 10003385
Server type (ServerType)ServerTypee.g. 100
Recipient (To)toRecipient mobile number
Message text (Message)textSMS 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

PatternHoma connection
Custom web service / dedicated URLDirect connection via this gateway.
SMS plugin with fixed providersDirect only if a custom URL option exists; otherwise a dedicated adapter is required.
Corporate API / ERPPrefer a dedicated adapter built on the Homa REST API.

Software compatibility matrix

SoftwareTypical statusConnection methodNotes
HolooDirect test possible when custom provider is supportedCustom web serviceIf URL and parameter names are configurable, this gateway is enough.
Holoo APEXVersion-dependentCustom web service or adapterIf only fixed providers are listed, a dedicated adapter is needed.
ParmisOfficial SMS module / gatewaySMS module or custom URLDirect connection works only when the panel accepts a custom web service.
MahakOfficial SMS messenger pluginPlugin or custom URLIf the plugin only supports fixed providers, HomaCRM must be added to the list or an adapter written.
NeginProduct-specificCustom web serviceExact product name and version should be verified.
Dasht (Hamkaran System)Official SMS subsystemSMS subsystem or adapterDirect connection only if the subsystem/plugin exposes a custom URL.
SepidarPlugin review requiredPlugin / dedicated adapterMany installations use fixed provider lists.
Rahkaran (Hamkaran System)Adapter project usually requiredCustom API / integrationFor enterprise ERP, a simple URL setup is usually insufficient.
Shayegan, Ghyas, Ferdad, Arian System, Tadbir, Peyvast, RafeDepends on version and SMS moduleCustom web service or adapterDirect when to and text parameters are configurable.
Hesabfa, Chortke, and cloud accounting appsOften API-driven or locked to built-in SMSAPI / adapterCheck 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 fieldValue
Panel nameHomaCRM (any label)
Site URLhttps://www.HomaCRM.com/api/v1/external/messaging/gateway
UsernameAPI token
UserName → parameterusername
PortalCode → parameterPortalCode
ServerType → parameterServerType
To → parameterto
Message → parametertext
If your Holoo build only shows a fixed provider list and offers no custom URL or parameter mapping, direct connection is not possible — evaluate a dedicated plugin or adapter instead.

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.

FieldValue
Web service URLhttps://www.HomaCRM.com/api/v1/external/messaging/gateway
UsernameAPI token
ServerType parameterServerType
Recipient parameterto
Message parametertext
PortalCode parameterPortalCode

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}
Note: Sepidar, Dasht, Rahkaran, and some Parmis/Mahak builds typically use SMS subsystems or plugins tied to specific providers. Direct Homa connection works only when that plugin allows a custom URL; otherwise prepare a dedicated plugin or adapter.

Drafts

Manage pre-written message templates (drafts) for quick sending.

List Drafts

GET /messaging/drafts

Get list of saved message drafts.

Query Parameters

ParameterTypeConstraintsDescription
pagenumberInteger ≥ 1 (default 1)Page index.
pageSizenumberInteger 1–100 (default 20)Rows per page.
groupIdnumberPositive integer (list category / ListCode)Filter drafts in one group.
searchstringSubstring searchMatches 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

POST /messaging/drafts

Create a new message draft.

Request Body

FieldTypeRequiredValid values / constraintsDescription
titlestringYesMax 500 charactersDraft title.
messagestringYesMax 1000 charactersTemplate text (SMS page count derived on save).
groupIdnumberNoPositive integer or omitListCode / category.
languagenumberNo1 = 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 /messaging/drafts/{id}

Get a specific draft by ID.

Path

SegmentConstraintsDescription
idPositive 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

PUT /messaging/drafts/{id}

Request Body (partial update)

FieldTypeRequiredValid values / constraintsDescription
titlestringNoMax 500 chars if presentNew title.
messagestringNoMax 1000 chars; updates SMS page countNew body.
groupIdnumberNoPositive integerListCode.
languagenumberNo1 or 2Override 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 /messaging/drafts/{id}

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

GET /messaging/scenarios

Query Parameters

ParamTypeDescription
activebooleanOptional — true only active, false only inactive.
page, pageSizenumberPagination; 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

GET /messaging/scenarios/{id}

The list row plus items[], scenario findings[] and notes[].

Item fields

FieldDescription
timing.mode1 = 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, bodyChannel flags and content.
senderSender line resolved from the portal numbers: referenceType, referenceId, number, isBlackList, active, whoisStatus, blackListActive, mask.
runCountRecommender_Items.Runtimes — execution counter maintained by the sending worker, which lives outside this codebase (0 = never ran).
lastMatchingSendNewest 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

POST /messaging/programs

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

FieldTypeDescription
titlestring, 1–200Program title.
messagestring, 2–1000SMS text.
senderIdnumberAn id from GET /messaging/numbers: -11 = Black List, otherwise an active, approved line of the portal. A line number is not accepted here.
sourceobjectOne 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.
blacklistMode0|1|2Optional; the wizard's «exclude recipients of earlier programs». 2 + blacklistProgramIds = only those programs.
justDeliveredbooleanOptional; wizard filter.
dryRunbooleantrue = 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

GET /messaging/audiences/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

POST /messaging/audiences/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 /crm/contacts

Get paginated list of contacts.

Query Parameters

ParameterTypeConstraintsDescription
pagenumberInteger ≥ 1 (default 1)Page index.
pageSizenumberInteger 1–100 (default 20)Rows per page.
searchstringSubstring (LIKE on name, company, mobiles)Free-text filter.
groupIdnumberMaps to Category columnOnly 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

POST /crm/contacts

Create a new contact.

Request Body

FieldTypeRequiredValid values / constraintsDescription
mobilestringYesMust normalize to 09XXXXXXXXX; duplicate Mobile per portal → 409Primary mobile.
firstNamestringNoStored as NVARCHARFirst name.
lastNamestringNo—Last name.
emailstringNo—Email.
companyNamestringNo—Company title.
groupIdnumberNoInteger; CategoryContact group.
mobile2stringNoSame mobile rules as mobile if providedSecond mobile.
mobile3stringNo—Third mobile.
phonestringNoLandline / telStored in Tell.
nationalCodestringNo—National ID.
addressstringNo—Postal address.
citynumberNoPortal city dictionary IDCity.
provincenumberNoPortal province dictionary IDProvince.
notesstringNo—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 /crm/contacts/{id}

Get a specific contact by ID.

Path

SegmentConstraintsDescription
idPositive 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

PUT /crm/contacts/{id}

Update contact fields. Only keys you send are applied.

Request Body (partial)

FieldTypeValid values / constraintsDescription
firstNamestring—First name.
lastNamestring—Last name.
companyNamestring—Company.
mobilestringDigits normalized (prefer 09…)Primary mobile.
mobile2string—Second mobile.
mobile3string—Third mobile.
phonestring—Landline (Tell).
emailstring—Email.
addressstring—Address.
groupIdnumberIntegerCategory / group.
notesstring—Notes (Tozihat).
isActivebooleantrue / falseSoft-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 /crm/contacts/{id}

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 /crm/contacts/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

PUT /crm/contacts/groups/{id}

Update an existing contact group. Scope: crm:groups:write.

Delete Contact Group

DELETE /crm/contacts/groups/{id}

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 /crm/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 /crm/deals

Get paginated deals. Scope: crm:deals:read.

Query Parameters

ParameterTypeDescription
pipelineIdnumberFilter by pipeline
stageIdnumberFilter by stage
statusstringFilter by status (e.g. open, won, lost)
searchstringText search on the title
page, pageSizenumberPagination (pageSize max 100)

Create Deal

POST /crm/deals

Create a new deal. Scope: crm:deals:write.

Request Body

FieldTypeRequiredDescription
titlestringYesDeal title
pipelineIdnumberYesPipeline ID (from List Pipelines)
stageIdnumberYesStage ID within that pipeline
amountnumberNoDeal value
contactIdnumberNoLinked 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

PUT /crm/deals/{id}

Update an existing deal. Scope: crm:deals:write.

Delete Deal

DELETE /crm/deals/{id}

Soft-delete a deal. Returns 204 No Content. Scope: crm:deals:write.

List Leads

GET /crm/leads

Get paginated sales leads. Supports search, page, pageSize. Scope: crm:leads:read.

Create Lead

POST /crm/leads

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

PUT /crm/leads/{id}

Update an existing lead. Scope: crm:leads:write.

Delete Lead

DELETE /crm/leads/{id}

Soft-delete a lead. Returns 204 No Content. Scope: crm:leads:write.

List Automations (read-only)

GET /crm/automations

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)

GET /crm/automations/{id}

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 /support/tickets

Get list of your support tickets.

Query Parameters

ParameterTypeDescription
pagenumberPage number
pageSizenumberItems per page (max 100)
statusstringFilter: 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

POST /support/tickets

Create a new support ticket.

Request Body

FieldTypeRequiredDescription
titlestringYesTicket title (max 200)
descriptionstringYesDetailed description
prioritynumberNoInteger 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 /support/tickets/{id}

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

POST /support/tickets/{id}/reply

Add a reply to an existing ticket.

Request Body

FieldTypeRequiredDescription
contentstringYesReply 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)

POST /support/tickets/{id}/actions

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

FieldTypeRequiredDescription
actionstringYes"followup"
notestringNoOptional note (max 2000)
urgentbooleanNoWhen true, the ticket priority is raised

Request Body — request_call

FieldTypeRequiredDescription
actionstringYes"request_call"
phonestringYesIranian mobile in 09xxxxxxxxx format
preferredTimestringNoPreferred time window (free text)
notestringNoOptional 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

GET /warehouse/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

GET /warehouse/categories

Portal product categories with ID, name, warehouse ID, priority and active status.

Get Inventory

GET /warehouse/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

GET /finance/invoices

Invoices with total, paid and remaining amounts.

Query Parameters

ParameterTypeDescription
searchstringText search on invoice number / customer
statusstringdraft, ready, settled, balance (has remaining balance), credit
dateFrom, dateTostringDate range, YYYY-MM-DD (Gregorian)
page, pageSizenumberPagination (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

GET /finance/invoices/{id}

Invoice header plus line items (quantity, unit price, discount, line total) and payments. Sensitive internal fields are omitted.

List Payments

GET /finance/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

POST /finance/payments

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

POST /finance/invoices

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

PUT /finance/invoices/{id}

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

GET /finance/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.

GET /finance/documents

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.

GET /finance/documents/lines

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"}.

POST /finance/documents

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"}.

GET /finance/documents/{id}

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"}.

PUT /finance/documents/{id}

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"}.

GET /finance/documents/{id}

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.

GET /finance/accounts/balances

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"}.

GET /finance/reports/trial-balance

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"}.

GET /finance/reports/income-statement

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"}.

GET /finance/reports/balance-sheet

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.

GET /finance/treasury/banks

Bank accounts (account numbers masked to the last 4 digits). Query: activeOnly. Example response: {"data":[{"id":3,"title":"ملت","accountNumber":"****1234","branchTitle":"مرکزی","isActive":true}]}.

GET /finance/treasury/funds

Cash funds (صندوق). Query: activeOnly. Example response: {"data":[{"id":2,"title":"صندوق مرکزی","comments":null,"isActive":true}]}.

GET /finance/treasury/cheques

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}}}.

GET /finance/treasury/balances

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"}.

GET /finance/treasury/banks/{id}/ledger

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"}.

GET /finance/treasury/funds/{id}/ledger

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"}.

POST /finance/treasury/transfers

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.

GET /finance/counterparties/balances

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"}

GET /finance/counterparties/{customerId}/statement

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}]}.

GET /finance/counterparties/aging

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

GET /production/orders

Manufacturing orders with planned/produced quantities and status. Query: status, search, page, pageSize.

Get Production Order

GET /production/orders/{id}

Full order detail including child operations/steps. Cost-related fields are intentionally not exposed.

List Formulas (BOM)

GET /production/formulas

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.

Privacy by design: only aggregate run totals and summary identity fields are exposed — individual payslip lines, salary details and sensitive personal data are never returned by this API.

List Periods

GET /payroll/periods

Payroll periods. Query: year, status, page, pageSize.

List Calculation Runs

GET /payroll/runs

Calculation runs with employee count and aggregate gross/deductions/net totals. Query: periodId, status, page, pageSize.

Get Run Summary

GET /payroll/runs/{id}

Aggregate totals for a single run — individual payslip lines are intentionally omitted.

List Employees

GET /payroll/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).

GET /admin/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 } }
POST /admin/users

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)." } }
GET /admin/users/{id}

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"
PATCH /admin/users/{id}

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 /system/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 /system/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

GET /utilities/datetime

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

POST /utilities/qrcode

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

FieldTypeRequiredDefaultDescription
textstringYes—Text or URL to encode (max 2000 characters)
sizenumberNo400PNG width/height in pixels (100–800)
formatstringNopngpng (data URL) or svg (markup)
errorCorrectionLevelstringNoML/M/Q/H
marginnumberNo2Quiet-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.

Note: All deputy endpoints require a valid API token from a portal that has deputy status enabled.

Create Portal

Create new portals under your deputy management. Shahkar verification is performed automatically.

POST /deputy/portal/create

Create new portal with automatic Shahkar verification.

Request Body

FieldTypeRequiredDescription
firstNamestringYesFirst name (Persian)
lastNamestringYesLast name (Persian)
mobilestringYesMobile number (09XXXXXXXXX)
emailstringYesEmail address
nationalCodestringYes10-digit national code
editionstringYes"sms" or "full"
skipShahkarbooleanNoSkip Shahkar verification (default: false)

Response

FieldTypeDescription
portalCodenumberNew portal code
usernamestringAdmin username
passwordstringAdmin password
shahkarVerifiedbooleanWhether 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"
  }'
Note: Shahkar service validates that the national code belongs to the mobile number owner. If verification fails, portal will not be created.

Sub-Portal Management

List Sub-Portals

GET /deputy/portals

Get list of all portals under your management.

Query Parameters

ParameterTypeDefaultDescription
pagenumber1Page number
pageSizenumber20Items per page (max 100)
searchstring-Search by code, name, mobile
statusstringallFilter: active, inactive, all

Get Portal Details

GET /deputy/portals/{code}

Get detailed information about a sub-portal.

Update Portal

PUT /deputy/portals/{code}

Update sub-portal information (limited fields).

Request Body

FieldTypeDescription
titlestringPortal title
companyNamestringCompany name
ownerFirstNamestringOwner first name
ownerLastNamestringOwner last name
emailstringEmail address
isActivebooleanActive status
Note: National code and mobile number cannot be changed.

Get Portal Credit

GET /deputy/portals/{code}/credit

Get SMS credit balance for a sub-portal.

Get Portal Stats

GET /deputy/portals/{code}/stats

Get statistics for a sub-portal (SMS, contacts, activity).

Query Parameters

ParameterTypeDefaultDescription
periodstring30dTime period: 7d, 30d, 90d, all

Deputy Statistics

Overall Stats

GET /deputy/stats

Get overall statistics for your deputy network.

Response

FieldTypeDescription
deputyCodenumberYour deputy code
totalPortalsnumberTotal sub-portals
activePortalsnumberActive sub-portals
inactivePortalsnumberInactive sub-portals
totalSmsCreditnumberTotal SMS credit across all
portalsCreatedThisMonthnumberNew portals this month
topPortalsarrayTop 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

CodeHTTPDescription
E1001401Invalid or malformed token
E1003403Insufficient permissions
E1004429Rate limit exceeded
E1005401Authentication token required
E2001400Invalid request format
E2002400Required field is missing
E4001422Insufficient SMS credit
E4002400Invalid recipient number
E4003400Message too long
E7001404Contact not found
E7006409Duplicate mobile number
E8001404Ticket not found
E8002423Ticket is closed
E9001500Internal server error

Rate Limits

To ensure fair usage, the API enforces rate limits on all endpoints.

Default Limits

100 requests per minute per API token

Rate Limit Headers

Every response includes these headers:

HeaderDescription
X-RateLimit-LimitMaximum requests allowed
X-RateLimit-RemainingRequests remaining in window
X-RateLimit-ResetWhen 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.

Best Practice: Implement exponential backoff in your client to handle rate limits gracefully.