> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thedecard.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Company status and alerts

> Query an onboarded company's details, freeze and unfreeze it by capability domain (idempotent set semantics), and set per-currency low-balance alerts on its funding pools (full-replacement semantics) — with field tables, examples and error codes.

## 📄 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](./company-onboarding).

## 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 |

```http theme={null}
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` |

<Note>
  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](../basic-concepts/states-and-freezing).
</Note>

### Response example

```json theme={null}
{
  "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)                                |

<Warning>
  `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.
</Warning>

### 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)

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

### Request example: unfreeze (remove behavioral states)

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

### Response example

An action endpoint: `data` is empty on success.

```json theme={null}
{
  "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.

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

### 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

```json theme={null}
{
  "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.

```json theme={null}
{
  "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](./funding-and-reconciliation)
* Review the whole flow from onboarding to maintenance: [Managing companies](./managing-companies)