Company status and alerts - DCS Technical Documentation

📄 Guide

Whether for routine operational checks, risk handling or treasury management, the three endpoints on this page maintain a company that has already been onboarded: query its details (query), freeze and unfreeze it (update-state), and configure low-balance alerts (balance-alert-set). All three locate the company by the organizationId returned on successful onboarding; for the onboarding and review flow, see Company onboarding and review.

Query company details

GET /open-api-corp/organization/v1/query Query an onboarded company’s basic details, funding-pool currencies and current status.

Request parameters

Field	Type	Required	Description
`organizationId`	string	Yes	≤20; the company ID

GET /open-api-corp/organization/v1/query?organizationId=e7c9a1f0-3b52-4d8e-9a67-1f2b3c4d5e6f

Response fields (`data`)

Field	Type	Description
`organizationId`	string	Company ID
`organizationRef`	string	Your identifier
`organizationName`	string	Company legal name
`companyRegistrationNumber`	string	Registration number
`fundingCurrencies`	string[]	Funding-pool currency list
`status`	string	Company status (merged view): life cycle `ACTIVE` / `TERMINATED`, overlaid with the behavioral states `SUSPENDED` / `FROZEN` / `RESTRICTED`

The company status is presented as one merged field: the life cycle overlaid with behavioral states. Whether the company can issue cards or spend comes down to whether it is ACTIVE. For the state machine semantics, see State machines and freezing.

Response example

{
  "code": "SYS_SUCCESS",
  "message": null,
  "data": {
    "organizationId": "e7c9a1f0-3b52-4d8e-9a67-1f2b3c4d5e6f",
    "organizationRef": "ext-company-001",
    "organizationName": "EXAMPLE COMPANY LIMITED",
    "companyRegistrationNumber": "CR1234567",
    "fundingCurrencies": ["USD", "HKD"],
    "status": "ACTIVE"
  }
}

Error codes

Error code	Description
`ORGANIZATION_INVALID`	The company does not exist (or does not belong to this partner)

Freeze and unfreeze

POST /open-api-corp/organization/v1/update-restrictions Freeze or unfreeze a company by capability domain, with idempotent set semantics: the company’s behavioral state is a set — addRestrictions puts a capability-domain code into the set (freezing it) and removeRestrictions takes it out (unfreezing it), and repeating the same operation yields the same result.

The five capability-domain codes

Freezing applies per capability domain, and one call may carry several:

Capability-domain code	What a freeze disables
`ACCOUNT_FROZEN`	The account as a whole (login, password change, phone/email change, MFA binding, account closure)
`CASH_IN_FROZEN`	Pay-in / top-up
`CASH_OUT_FROZEN`	Pay-out / withdrawal / remittance
`PAYMENT_FROZEN`	Payment / spending (card payments included)
`CARD_FROZEN`	Card-management actions (card application, activation, PIN change)

addRestrictions / removeRestrictions accept only the 5 open L1 capability-domain codes above; anything else (including KYC_FROZEN / TRANSFER_FROZEN, L2 fine-grained codes, and SUSPENDED / RESTRICTED) returns DAPI_PARAM_INVALID. Restricted states written by risk, regulatory or judicial processes cannot be lifted through this endpoint.

Request parameters

Field	Type	Required	Description
`organizationId`	string	Yes	≤20; the target company
`addRestrictions`	string[]	No	Freeze codes; values restricted to the 5 L1 capability-domain codes; several may be passed
`removeRestrictions`	string[]	No	Unfreeze codes; same value set as `addRestrictions`; several may be passed
`remark`	string	No	≤256; operation remark

Request example: freeze (add behavioral states)

{
  "organizationId": "e7c9a1f0-3b52-4d8e-9a67-1f2b3c4d5e6f",
  "addRestrictions": ["PAYMENT_FROZEN", "CARD_FROZEN"],
  "remark": "suspicious transactions under review"
}

Request example: unfreeze (remove behavioral states)

{
  "organizationId": "e7c9a1f0-3b52-4d8e-9a67-1f2b3c4d5e6f",
  "removeRestrictions": ["PAYMENT_FROZEN", "CARD_FROZEN"],
  "remark": "review cleared"
}

Response example

An action endpoint: data is empty on success.

{
  "code": "SYS_SUCCESS",
  "message": null,
  "data": null
}

After a state change, DCS pushes the company status-change notification (for the event name, see the webhook event table in the API reference); its payload carries the addRestrictions / removeRestrictions of this operation.

Error codes

Error code	Description
`ORGANIZATION_INVALID`	The company does not exist (or does not belong to this partner)
`STATUS_CONFLICT`	The current status does not allow this operation (for example, the company is not `ACTIVE`)

Low-balance alerts

POST /open-api-corp/fund/v1/balance-alert-set Set per-currency low-balance alerts on the company’s funding pools.

Full-replacement semantics: every call resets the entire alert configuration, so always send the complete list rather than an increment.

Request parameters

Field	Type	Required	Description
`organizationId`	string	Yes	≤20; the company ID
`balanceSettings`	array	Yes	Per-currency thresholds, at least 1 entry; no duplicate currencies (a duplicate returns `DAPI_PARAM_INVALID`); the currency must be one of the company’s opened funding-pool currencies
`balanceSettings[].currency`	string	Yes	`USD` / `HKD`
`balanceSettings[].threshold`	BigDecimal	Yes	The threshold (the alert triggers when the available balance falls below it; two decimal places, non-negative)
`emailSettings`	string[]	No	≤128 per entry; notification mailboxes (company-level, several allowed, each an email address); omit it to receive webhooks only

Request example

{
  "organizationId": "e7c9a1f0-3b52-4d8e-9a67-1f2b3c4d5e6f",
  "balanceSettings": [
    { "currency": "USD", "thresholdAmount": "1000.00" },
    { "currency": "HKD", "thresholdAmount": "8000.00" }
  ],
  "emailSettings": ["finance@example.com"]
}

Response example

An action endpoint: data is empty on success.

{
  "code": "SYS_SUCCESS",
  "message": null,
  "data": null
}

Trigger behavior (`LOW_BALANCE`)

When a funding pool’s available balance falls below the threshold for its currency, DCS pushes the LOW_BALANCE webhook (the funding-pool low-balance alert).
Only the webhook fires by default; email is sent additionally only when emailSettings is configured.
The same alert fires once a day until the balance is topped back up.

Error codes

Error code	Description
`SUBJECT_INVALID`	The company (the funding-pool holder) does not exist or is invalid
`BALANCE_ALERT_CURRENCY_NO_POOL`	The alert currency has no corresponding funding pool

Next steps

Top up the funding pool and reconcile after a low-balance alert: Funding and reconciliation
Review the whole flow from onboarding to maintenance: Managing companies

​📄 Guide

​Query company details

​Request parameters

​Response fields (data)

​Response example

​Error codes

​Freeze and unfreeze

​The five capability-domain codes

​Request parameters

​Request example: freeze (add behavioral states)

​Request example: unfreeze (remove behavioral states)

​Response example

​Error codes

​Low-balance alerts

​Request parameters

​Request example

​Response example

​Trigger behavior (LOW_BALANCE)

​Error codes

​Next steps

📄 Guide

Query company details

Request parameters

Response fields (`data`)

Response example

Error codes

Freeze and unfreeze

The five capability-domain codes

Request parameters

Request example: freeze (add behavioral states)

Request example: unfreeze (remove behavioral states)

Response example

Error codes

Low-balance alerts

Request parameters

Request example

Response example

Trigger behavior (`LOW_BALANCE`)

Error codes

Next steps