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

# Companies · Overview

> Onboard and maintain your business customers: KYB application, querying and resubmission, freeze/unfreeze, low-balance alerts — with the key parameters and the idempotency and dedup rules.

## 📄 Guide

A company is your business customer's funding and compliance entity on the platform: onboarding creates its funding pool, and every employee, card and balance hangs off it. This page walks "apply → get the result → day-to-day maintenance", showing what to call, what to send and what you get back.

## Who does what

| Step                              | Who     | Notes                                                                   |
| --------------------------------- | ------- | ----------------------------------------------------------------------- |
| Submit the onboarding application | Partner | Collect the company details and call apply                              |
| KYB due diligence                 | DCS     | Reviewed asynchronously; the result arrives over webhook                |
| Handle the result / resubmit      | Partner | Persist `organizationId` on approval; correct and resubmit on rejection |
| Day-to-day maintenance            | Partner | Freeze / unfreeze, low-balance alert configuration                      |

## Step 1: submit the application

`POST /open-api-corp/organization/v1/apply` — KYB runs asynchronously after submission; acceptance returns an `organizationApplyId`.

| Field                       | Required | Description                                                                                                                                                                                                       |
| --------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `organizationRef`           | Yes      | ≤64; your unique company identifier (the idempotency key), charset `^[A-Za-z0-9_-]+$`                                                                                                                             |
| `organizationName`          | Yes      | ≤256; legal name — English letters, digits and spaces only                                                                                                                                                        |
| `companyRegistrationNumber` | Yes      | ≤64; company registration number                                                                                                                                                                                  |
| `email`                     | Yes      | ≤128; company contact email                                                                                                                                                                                       |
| `fundingCurrencies`         | Yes      | Pool currencies (USD / HKD, one or more — a receiving VA is created per currency); no duplicates, and must be a subset of the currencies allowed for your enterprise — anything outside rejects the whole request |

The synchronous response carries only `organizationApplyId` + `status=PENDING` — accepted, not approved.

<Warning>
  **Dedup runs on three dimensions**: `organizationRef`, `email` and `companyRegistrationNumber` are unique within one partner, and the latter two are **never released, even after a rejection**. Reapplying under an `organizationRef` with an in-flight or approved application returns `APPLY_DUPLICATE`; if only a rejected application exists it returns `APPLY_REJECTED_USE_RESUBMIT` — the right path is resubmit, never a new ID.
</Warning>

## Step 2: get the result

Rely on webhooks `ORGANIZATION_CREATED` / `ORGANIZATION_REJECTED`, with `GET /open-api-corp/organization/v1/query-apply?organizationApplyId=...` as the polling fallback. Key response fields:

| Field                      | Description                                                                             |
| -------------------------- | --------------------------------------------------------------------------------------- |
| `status`                   | `PENDING` (KYB in progress) / `SUCCEED` (onboarded) / `REJECTED` (KYB refused)          |
| `status` / `rejectMessage` | The application status and the rejection reason (`rejectMessage` only when `REJECTED`)  |
| `organizationId`           | The company ID, present only after `SUCCEED` — persist it; every later endpoint uses it |

**Resubmission after rejection**: `POST /open-api-corp/organization/v1/resubmit` with `organizationApplyId` plus the corrected `organizationName` / `companyRegistrationNumber`, re-reviewed under the same application; `organizationRef` cannot change. Allowed only while the current state is `REJECTED`, otherwise `STATUS_CONFLICT`.

## Day-to-day maintenance

**Query company detail**: `GET /open-api-corp/organization/v1/query?organizationId=...` — legal name, registration number, pool currencies and status (life cycle `ACTIVE` / `TERMINATED` overlaid with behavioral states `FROZEN` / `SUSPENDED` / `RESTRICTED`; semantics in [State machines and freezing](../basic-concepts/states-and-freezing)).

**Freeze / unfreeze**: `POST /open-api-corp/organization/v1/update-restrictions` — idempotent set semantics: `addRestrictions` freezes, `removeRestrictions` unfreezes, values restricted to the 5 capability-domain codes `ACCOUNT_FROZEN` / `CASH_IN_FROZEN` / `CASH_OUT_FROZEN` / `PAYMENT_FROZEN` / `CARD_FROZEN` (anything else returns `DAPI_PARAM_INVALID`). A state change pushes a webhook notification.

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

**Low-balance alerts**: `POST /open-api-corp/fund/v1/balance-alert-set` — a threshold per currency (`balanceSettings[].currency` + `balanceSettings[].thresholdAmount`), with optional `emailSettings`. **Full-replacement semantics** — every call resets the entire alert configuration; the webhook `LOW_BALANCE` always fires, and email is sent only if a mailbox is configured; the same alert fires once per day until the balance recovers.

## Related webhooks

`ORGANIZATION_CREATED` (KYB passed, carries `organizationId`) / `ORGANIZATION_REJECTED` (carries `rejectMessage`) / the company status-change notification (carries `addRestrictions` / `removeRestrictions`) / `LOW_BALANCE`. Envelope and signature verification: [Quickstart](../getting-started/quickstart).

## Next steps

* Create cardholders once the company is ACTIVE: [Managing employees](./managing-employees)
* Fund the pool: [Funding and reconciliation](./funding-and-reconciliation)
* In this group: [Company onboarding and review](./company-onboarding) · [Company status and alerts](./company-maintenance)