> ## 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 onboarding and review
> Submit a company onboarding application for asynchronous KYB review, query the progress and outcome, and resubmit a rejected application under the same organizationApplyId — with full field tables, request/response examples and error codes.
## 📄 Guide
Whether you serve trading firms, Web3 projects or cross-border merchants, the three endpoints on this page take your business customer through onboarding: submit the application (`apply`), query the outcome (`query-apply`), and resubmit after a rejection (`resubmit`). Onboarding is asynchronous — the synchronous response carries only the application record with status `PENDING`, and acceptance is not approval. Rely on the webhook for the final result, with the query endpoint as the polling fallback. For the overall call sequence, see the overview page [Managing companies](./managing-companies).
## Submit the onboarding application
**`POST /open-api-corp/organization/v1/apply`**
Once you submit the company details, DCS runs corporate due diligence (KYB) asynchronously. Acceptance returns an `organizationApplyId`, and `status` in the synchronous response is always `PENDING`.
### Request parameters
| Field | Type | Required | Description |
| --------------------------- | --------- | :------: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `organizationRef` | string | Yes | ≤64; your unique company identifier (the idempotency key); charset `^[A-Za-z0-9_-]+$` |
| `organizationName` | string | Yes | ≤256; company legal name; English letters, digits and spaces only |
| `companyRegistrationNumber` | string | Yes | ≤64; company registration number |
| `email` | string | Yes | ≤128; company contact email |
| `fundingCurrencies` | string\[] | Yes | Funding-pool currencies, `USD` / `HKD`, one or more (a funding-pool virtual account, VA, is created per currency); no empty elements and no duplicate currencies — empty, duplicate or non-enum values return `DAPI_PARAM_INVALID`; the set must also be a subset of the currencies allowed for your enterprise, and anything outside that range rejects the whole request (no partial opening) with `CURRENCY_NOT_ALLOWED` |
**Deduplication runs on three dimensions**: `organizationRef`, `email` and `companyRegistrationNumber` are each unique within one partner, and the latter two are **never released, even after a rejection**. Reapplying under an `organizationRef` that already has 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` under the same `organizationApplyId`, never a fresh ID.
### Request example
```json theme={null}
{
"organizationRef": "ext-company-001",
"organizationName": "EXAMPLE COMPANY LIMITED",
"companyRegistrationNumber": "CR1234567",
"email": "finance@example.com",
"fundingCurrencies": ["USD", "HKD"]
}
```
### Response example
```json theme={null}
{
"code": "SYS_SUCCESS",
"message": null,
"data": {
"organizationApplyId": "5136744097353943553",
"organizationRef": "ext-company-001",
"status": "PENDING"
}
}
```
### Response fields (`data`)
| Field | Type | Description |
| --------------------- | ------ | -------------------------------------------------------------------------- |
| `organizationApplyId` | string | The onboarding application ID; quote it in later queries and resubmissions |
| `organizationRef` | string | Your identifier, echoed back |
| `status` | string | Always `PENDING` (accepted; KYB in progress) |
### Error codes
| Error code | Description |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `APPLY_DUPLICATE` | An in-flight or approved application already exists under this `organizationRef`; it cannot be submitted again |
| `APPLY_REJECTED_USE_RESUBMIT` | Only a rejected application exists under this `organizationRef` — use the resubmission endpoint instead (a duplicate `apply` is no longer allowed) |
| `EMAIL_DUPLICATE` | This `email` is already taken under the same partner (enterprise-wide, any status including rejected) |
| `COMPANY_REGISTRATION_DUPLICATE` | The same `companyRegistrationNumber` has already been applied for under this partner (enterprise-wide, any status including rejected) |
| `CURRENCY_NOT_ALLOWED` | A requested currency is outside the list allowed for your enterprise (`message` names the offending currency) |
## Query the onboarding application
**`GET /open-api-corp/organization/v1/query-apply`**
Query the review progress and outcome of an onboarding application. Rely on webhooks first, with this endpoint as the polling fallback.
### Request parameters
| Field | Type | Required | Description |
| --------------------- | ------ | :------: | ---------------------------------- |
| `organizationApplyId` | string | Yes | ≤20; the onboarding application ID |
```http theme={null}
GET /open-api-corp/organization/v1/query-apply?organizationApplyId=5136744097353943553
```
### Response fields (`data`)
| Field | Type | Description |
| --------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------- |
| `organizationApplyId` | string | Application ID |
| `organizationRef` | string | Your identifier |
| `status` | string | `PENDING` (under review; KYB in progress) / `SUCCEED` (onboarded) / `REJECTED` (refused by KYB) |
| `rejectMessage` | string | The rejection reason (present when `REJECTED`) |
| `organizationId` | string | The company ID once the entity exists, present only after `SUCCEED` — persist it; every later company endpoint uses it |
### Response example: onboarded
```json theme={null}
{
"code": "SYS_SUCCESS",
"message": null,
"data": {
"organizationApplyId": "5136744097353943553",
"organizationRef": "ext-company-001",
"status": "SUCCEED",
"rejectMessage": null,
"organizationId": "e7c9a1f0-3b52-4d8e-9a67-1f2b3c4d5e6f"
}
}
```
### Response example: rejected
```json theme={null}
{
"code": "SYS_SUCCESS",
"message": null,
"data": {
"organizationApplyId": "5136744097353943553",
"organizationRef": "ext-company-001",
"status": "REJECTED",
"rejectMessage": "registration number mismatch",
"organizationId": null
}
}
```
The envelope's `code=SYS_SUCCESS` only means the query itself succeeded; judge the business outcome by `data.status`. When it is `REJECTED`, read `rejectMessage` for the cause, correct the details and use the resubmission endpoint below.
### Error codes
| Error code | Description |
| ----------------- | ------------------------------------------------------------------------------ |
| `APPLY_NOT_FOUND` | The onboarding application does not exist (or does not belong to this partner) |
## Resubmit after a rejection
**`POST /open-api-corp/organization/v1/resubmit`**
After a KYB rejection, correct the details and send the same `organizationApplyId` back for review; `organizationRef` cannot change. Resubmission is allowed only while the application's current status is `REJECTED` — in-flight or approved applications need no resubmission and are not accepted, returning `STATUS_CONFLICT`.
### Request parameters
| Field | Type | Required | Description |
| --------------------------- | ------ | :------: | ------------------------------------------------------------------------------- |
| `organizationApplyId` | string | Yes | ≤20; the rejected onboarding application ID |
| `organizationName` | string | Yes | ≤256; the corrected company legal name; English letters, digits and spaces only |
| `companyRegistrationNumber` | string | Yes | ≤64; the corrected company registration number |
### Request example
```json theme={null}
{
"organizationApplyId": "5136744097353943553",
"organizationName": "EXAMPLE COMPANY LIMITED",
"companyRegistrationNumber": "CR7654321"
}
```
### Response example
```json theme={null}
{
"code": "SYS_SUCCESS",
"message": null,
"data": {
"organizationApplyId": "5136744097353943553",
"organizationRef": "ext-company-001",
"status": "PENDING"
}
}
```
Once the resubmission is accepted, the application returns to `PENDING`, and you get the outcome exactly as for a first submission (webhook first, `query-apply` as fallback).
### Error codes
| Error code | Description |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `APPLY_NOT_FOUND` | The onboarding application does not exist (or does not belong to this partner) |
| `STATUS_CONFLICT` | The application is not currently `REJECTED`, so it cannot be resubmitted (in-flight or approved applications need no resubmission) |
## Related webhooks
DCS pushes the onboarding outcome to you; two events cover the two terminal results:
| Event `type` | Trigger | Payload highlights |
| ----------------------- | ----------------------------- | ------------------------------------------------------------------------------- |
| `ORGANIZATION_CREATED` | KYB passed; company onboarded | Carries `organizationId`; the company is `ACTIVE` and ready for the next steps |
| `ORGANIZATION_REJECTED` | KYB refused | Carries `rejectMessage` (the rejection cause); correct the details and resubmit |
The shared event envelope (each event's business payload sits inside `data`):
```json theme={null}
{
"webhookId": "7800000000000000900",
"webhookType": "ORGANIZATION_CREATED",
"notificationTime": 1717211400000,
"data": { }
}
```
For the envelope structure, signature verification, retries and idempotency rules, see the [Quickstart](../getting-started/quickstart).
## Next steps
* Once onboarded and holding a `organizationId`, maintain the company's status and balance alerts: [Company status and alerts](./company-maintenance)
* Create cardholders once the company is `ACTIVE`: [Managing employees](./managing-employees)