Compliance Profile API¶
Applies to: All subscriptions. The profile applies to registrations whose ERP is Tally
Purpose¶
Describe the application endpoints behind Administration > Compliance Profiles, for implementation partners who script a customer's setup and for administrators who read it into another tool.
The one thing to know first: only a Complifly Super Admin can write. Every write call from any other role is refused with 403, and nothing is changed. Reads are open to a customer's Org Administrator and External Auditor (their own company) and to Complifly's Support and Platform Engineers (any company, each read recorded in that company's audit log).
These are application endpoints, not a versioned integration contract (see Endpoint Index). Pin to the fields listed here and ignore the rest.
Audience¶
Implementation partners, system administrators and Complifly staff scripting or reading a company's compliance profile.
Prerequisites¶
- A user token (see API Authentication). No
x-gstinheader is needed: the company is named in the path. - The permission shown in each table:
compliance_profile.viewto read,compliance_profile.manageto write. Who holds them is in Roles and Permissions. - Writes need a Complifly Super Admin login. A customer cannot obtain this role.
Who can call what¶
| Role | Read | Write | Which companies |
|---|---|---|---|
| Platform Super Admin | Yes | Yes | Any |
| Org Administrator | Yes | No | Their own only |
| External Auditor | Yes | No | Their own only |
| Support Engineer, Platform Engineer | Yes (audited) | No | Any |
| Every other role | No | No | none |
A company in a path is a claim, checked against your token before anything is read: a company that is not yours answers 403 COMPANY_NOT_PERMITTED, and a GSTIN that does not belong to a company you may use answers 404 UNKNOWN_GSTIN (the same answer whether it belongs to someone else or does not exist).
Reference¶
{erp} is TALLY. Any other value answers 404 UNSUPPORTED_ERP. Paths below are relative to /api/admin.
| Method | Path | Needs | What it does |
|---|---|---|---|
GET |
/compliance-profile/catalogue |
view | Every setting the workbench may edit, with its type, accepted values and screen. Also your own access |
GET |
/compliance-profile/registries |
view | The platform's rules, read only. There is no write call |
GET |
/companies/{companyId}/compliance-profile/{erp} |
view | The overview: revision, saved changes, effective profile, status (including status.exportPort), exportPortTask (the open CONFIGURE_EXPORT_PORT onboarding task, or null), gaps, six summary cards |
GET |
…/{erp}/revisions |
view | Every revision, newest first |
GET |
…/{erp}/revisions/{revision} |
view | One revision with its saved changes |
GET |
…/{erp}/revisions/compare?from=&to= |
view | Field-by-field difference. 0 means the platform base |
POST |
…/{erp}/validate |
view | Dry run of a change. Writes nothing |
PUT |
/companies/{companyId}/compliance-profile/{erp} |
manage | Save the next revision |
POST |
…/{erp}/rollback |
manage | A new revision copying an old one |
GET |
…/{erp}/audit?action=&gstin= |
view | The audit trail of all of the above (newest 200) |
GET |
/companies/{companyId}/registration-classes |
view | Every GSTIN of the company with its turnover class |
GET |
/gstins/{gstin}/registration-class |
view | One GSTIN's class |
PUT |
/gstins/{gstin}/registration-class |
manage | Declare or clear the class |
GET |
/companies/{companyId}/onboarding-tasks?status=&gstin=&taskCode= |
view | Tasks, and the users a task may be assigned to |
POST |
…/onboarding-tasks/{taskId}/close |
manage | Close a task by hand |
POST |
…/onboarding-tasks/{taskId}/assign |
manage | Assign a task |
A save is a new revision, and it needs three things¶
PUT /api/admin/companies/1001/compliance-profile/TALLY
{ "delta": { "stockTransferMode": "CHALLAN" }, "baseRevision": 3, "note": "CA confirmed transfers are by challan." }
| Field | Rule | If wrong |
|---|---|---|
delta |
An object holding all the customer's settings, not just the ones changed. It replaces the previous saved changes | 400 DELTA_REQUIRED |
baseRevision |
The revision you loaded. null when the company has none yet. It must be present: leaving it out would skip the overwrite check |
400 BASE_REVISION_REQUIRED; 409 CONCURRENT_MODIFICATION if it is no longer the latest |
note |
Why, 1 to 500 characters | 400 NOTE_REQUIRED / NOTE_TOO_LONG |
Success returns the new revision number and compiledHash. A delta that does not validate answers 422 PROFILE_DELTA_INVALID with problems[] in plain words, and stores nothing. Run it through /validate first to see the problems, and the gaps the change would leave, without saving.
The export port is the exportPort section of the delta: { "name", "addr1", "addr2", "city", "stateCode", "pin" }. It must be filled in completely or left empty (all six null or empty means "not configured", which is how you clear it); only addr2 is optional. stateCode must be an Indian state code from 01 to 38 (96, 97 and 99 are refused), pin exactly six digits, name, addr1 and city at least three characters. A port that fails any of this answers 422 PROFILE_DELTA_INVALID with the reason in problems[] and stores nothing. A successful save writes EXPORT_PORT_CONFIGURED, EXPORT_PORT_UPDATED or EXPORT_PORT_CLEARED to the audit log, and a valid port closes the company's open CONFIGURE_EXPORT_PORT task (audited as ONBOARDING_TASK_CLOSED).
What a save does not do: it never edits an earlier revision, and it does not touch documents already filed. Documents read after the save use the new revision.
Rollback¶
POST /api/admin/companies/1001/compliance-profile/TALLY/rollback
{ "toRevision": 2, "baseRevision": 4, "note": "Revision 4 was wrong." }
Creates revision 5 with revision 2's settings. Revision 2 is unchanged and revision 4 stays in the history. 404 REVISION_NOT_FOUND if toRevision does not exist; 422 ROLLBACK_TARGET_IS_CURRENT if it is already the latest.
Turnover class¶
PUT /api/admin/gstins/29AAACW3775F000/registration-class
{ "registrationClass": "TURNOVER_GE_5CR", "note": "Confirmed by the customer's CA." }
registrationClass is TURNOVER_GE_5CR, TURNOVER_LT_5CR, or null (also accepted: "UNKNOWN") to clear it. It must be present. While a GSTIN has no class, its documents are not held: they are routed as above the e-invoicing limit and flagged UNKNOWN_TURNOVER, and an onboarding task is opened.
Onboarding tasks¶
A task is closed automatically when its cause is fixed. close is for closing one by hand and needs a note. assign takes { "assignee": "<userId>" }, which must be an active user of the same company (422 ASSIGNEE_NOT_ELIGIBLE otherwise). Closing or assigning a task that is no longer open answers 409 TASK_NOT_OPEN.
What the overview does not tell you¶
| Not in the response | Why |
|---|---|
| How many documents are held by a gap | A held document is not stored, so it cannot be counted. Gaps that hold documents report blocked.measurable: false. The affected count is stored documents that carried the matching warning in the last 30 days |
Whether the agent applies selector |
The document-selection list is computed here; the agent does not read it automatically yet |
Errors¶
Every error is { "code": "...", "message": "..." }. The full list with who resolves each is in Platform Error Codes.
Audit¶
Every write is recorded in the audit log with the company, GSTIN where there is one, the user, the old and new values and the time.
| Action | Written when |
|---|---|
COMPLIANCE_PROFILE_DELTA_SAVED |
A revision is saved |
COMPLIANCE_PROFILE_ROLLBACK |
A rollback creates a revision |
REGISTRATION_CLASS_SET |
A turnover class is declared or cleared |
ONBOARDING_TASK_CLOSED |
A task is closed, by hand or automatically (automatic: true) |
ONBOARDING_TASK_ASSIGNED |
A task is assigned |
COMPLIANCE_PROFILE_VIEWED |
Complifly staff read a customer's profile |
Validation¶
| Check | Method | Pass condition |
|---|---|---|
| The save took effect | GET …/compliance-profile/TALLY |
revision.revision is the number the save returned, and revision.note is your reason |
| It is the change you meant | GET …/revisions/compare?from=<previous>&to=<new> |
changes lists only the settings you changed |
| Nothing was written by a dry run | POST …/validate, then GET …/revisions |
The revision count did not change |
| A write by a non-Super-Admin was refused | Repeat the PUT with a customer token |
403, and the revision count did not change |
Troubleshooting¶
| Symptom | Cause | Action |
|---|---|---|
403 on every write |
The token's role is not Complifly Super Admin | Use a Super Admin login. A customer cannot obtain this role |
400 BASE_REVISION_REQUIRED |
The body has no baseRevision |
Send the revision you loaded, or null when the company has none |
409 CONCURRENT_MODIFICATION |
Someone saved after you loaded | GET the profile again, re-apply your change, resend with the new baseRevision |
422 PROFILE_DELTA_INVALID |
The delta does not validate |
Read problems[]. Send the same body to /validate while you fix it |
The delta you sent replaced settings you did not mention |
delta is the whole set of customer settings, not a patch |
GET the profile, change the delta it returned, send that |
404 UNKNOWN_GSTIN for a GSTIN you know exists |
It is not under a company your token may use | Check the company, or use a Support Engineer login to read it |