Contacts

Customers, vendors and employees. A contact can be both a customer and a vendor.

List contacts

GET /masterdata/getContacts/{gtimeStamp?} — Permission: any role

Query	Type	Notes
balanceDue	boolean	true to include receivable/payable balances on each contact.

Returns Contact[]. getContactsNew takes the same parameters and returns the same shape; it is the newer implementation of the same call.

Get a contact

GET /masterdata/getContact/{contactId} — Permission: any role — returns a Contact, or 404.

Create or update a contact

POST /masterdata/upsertContact — Permission: Contact · Write

JSON body: a Contact. contactId and contactName are required. Contact names must be unique within a business; a duplicate returns 400.

curl -X POST "$BASE_URL/masterdata/upsertContact" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contactId": "c3b1f0e2-6a52-4c1a-9d0e-2f6b9a7d1e10",
    "contactName": "Acme Traders",
    "displayName": "Acme Traders",
    "custFlg": true,
    "vendorFlg": false,
    "contactTyp": ["Customer"],
    "emailTxt": "accounts@acme.example",
    "mobileNumber": "9876543210",
    "billingAddress": "12 Market Road, Chennai 600001",
    "taxIdNo": "33ABCDE1234F1Z5"
  }'

Response 200:

{ "contact": { "contactId": "c3b1f0e2-...", "contactName": "Acme Traders", "...": "..." }, "status": "..." }

Opening receivable/payable amounts (receivableAmt, payableAmt) cannot be negative.

POST /masterdata/upsertContactwFile does the same with attachments — see Uploading files. Permission: Contact · Write.

Contact balance

GET /masterdata/getContactBalance/{contactId} — Permission: Contact · Read

Query	Type	Notes
dateFilter	JSON (required)	For all-time use {"predefinedDateFilter":"AllTime"}.

Response:

{
  "receivables": 12500.00,
  "payables": 0,
  "unallocatedReceivableCredit": 0,
  "unallocatedPayableCredit": 0,
  "receivableCreditSources": [],
  "payableCreditSources": []
}

getContactBalanceNew/{contactId} takes the same query and returns just receivables and payables.

Delete contacts

Endpoint	Permission	Body
DELETE /masterdata/deleteContact/{contactId}	Contact · Full	—
POST /masterdata/deleteContacts	Contact · Full	JSON array of contact IDs, e.g. ["id1","id2"]

A contact that has transactions cannot be deleted (409). deleteContacts processes each ID independently and returns a summary:

{
  "success": true,
  "message": "Bulk delete completed. 2 deleted, 1 skipped, 0 failed.",
  "summary": { "total": 3, "deleted": 2, "skipped": 1, "failed": 0 },
  "details": { "success": [...], "skipped": [...], "failed": [...] }
}

---

Data model

Only the commonly used properties are listed. Unless marked required, every property is optional. Properties that the server sets itself (bizId, createdBy, modifiedBy, app, and creation/modification timestamps) should be left out of requests. The OpenAPI document has the complete definitions.

Contact

Property	Type	Notes
contactId	string	Required. Caller-generated unique ID.
contactName	string	Required. Unique within the business.
displayName, firstName, lastName, companyName	string
custFlg, vendorFlg	boolean	Whether the contact is a customer and/or a vendor.
contactTyp	string[]	Any of Customer, Vendor, Employee.
emailTxt, mobileNumber, workPhone, website, faxNumber	string
billingAddress, shippingAddress	string	Free text.
addresses	object[]	Additional structured addresses.
taxIdNo	string	Tax registration number (GSTIN/VAT/…).
inGSTNo, inGSTRegister, inGSTTreatment, panNo	string	India GST fields. Prefer taxIdNo for the GSTIN.
taxExempt, isBusiness	boolean
currId	string	Currency ID.
paymentTerms	string	Payment terms ID.
creditLimit	number
receivableAmt, payableAmt	number	Opening balances — cannot be negative.
contactCategory, contactGroup	string
parentContact	string	Parent contact ID for branches/sub-contacts.
customFields	object[]	User-defined fields.
portalAccess, portalEmail	boolean, string	Customer-portal access.