نرم‌افزار هُما

بازگشت به فهرست

CRM & Contacts

HomaCRM API

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.

HomaCRM External API

For support, create a ticket via /support/tickets endpoint.