> ## 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.
# Creating an employee
> The full call-level detail of the employee application: every apply field with the shipping-address structure, the email/phone uniqueness rules, tracking progress with query-apply, and resubmitting after a rejection.
## 📄 Guide
Employees are the end cardholders, and creating one is the mandatory step before any card can be issued to them. You submit the employee's details under an ACTIVE company, DCS accepts the application and runs individual due diligence (KYC name screening) asynchronously; rely on webhooks for the result with the query endpoint as fallback, and if KYC rejects the application, correct the name and resubmit under the same `customerApplyId`. This page covers all fields and examples for the three endpoints — apply, query-apply and resubmit; for the capability overview see [Managing employees](./managing-employees).
### Flow at a glance
The application state machine has only three states: `PENDING` / `SUCCEED` / `REJECTED`. After a rejection you do not start over with a new ID — you resubmit under the same `customerApplyId`.
### Prerequisites
* The company already exists and is `ACTIVE` (if not, start with [Managing companies](./managing-companies)).
* You have the employee's name, mobile number and email ready; if a physical card will be needed, also prepare a shipping address.
## Submit the application
**`POST /open-api-corp/customer/v1/apply`**
Creates an employee: submit the details, and individual due diligence (KYC name screening) runs asynchronously. Pass the shipping address as the address information.
### Request parameters
| Field | Type | Required | Description |
| ------------------ | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `customerRef` | String | Yes | ≤64; your unique employee identifier; character set `^[A-Za-z0-9_-]+$` |
| `organizationId` | String | Yes | ≤20; the company the employee belongs to, must be `ACTIVE` |
| `firstName` | String | Yes | ≤64; first name; English letters, digits and spaces only |
| `lastName` | String | Yes | ≤64; last name; English letters, digits and spaces only |
| `middleName` | String | No | ≤64; middle name; English letters, digits and spaces only |
| `phoneCountryCode` | String | Yes | Fixed length 2; mobile area code (ISO 3166-1 alpha-2 two-letter code, e.g. `HK`; must be on the supported list) |
| `phoneNumber` | String | Yes | ≤15; mobile number (digits only) |
| `email` | String | Yes | ≤128; email address |
| `addresses` | Array | No | Address list (structure below). If supplied at creation it is stored with the onboarding flow; if omitted, it can be added later through [updating employee addresses](./employee-maintenance) |
`addresses[]` element structure:
| Field | Required | Description |
| -------------------- | -------- | --------------------------------------------------------------------------------------------------------------- |
| `addressType` | Yes | Address purpose, the discriminator inside the array. Current value: `SHIPPING_ADDRESS` (physical card delivery) |
| `postalCode` | No | Postal code (some regions have none; may be empty) |
| `addressLine1` | Yes | Address line 1, ≤40 |
| `addressLine2` | No | Address line 2, ≤40 |
| `addressLine3` | No | Address line 3, ≤40 |
| `city` | Yes | City (for Hong Kong, the district is acceptable), ≤64 |
| `state` | Yes | State / province (for Hong Kong, use `Hong Kong`), ≤20 |
| `addressCountryCode` | Yes | Two-letter ISO country code (e.g. `HK`) |
**An employee without a shipping address cannot apply for a physical card.** If you only issue virtual cards you may omit `addresses` and add it later through the update endpoint when a physical card is needed.
**Uniqueness rules**: within one partner, an employee's email and phone (area code + number) are unique across companies, and **once taken they are never released — even if the application was rejected**. Duplicate submissions return `EMAIL_DUPLICATE` / `PHONE_DUPLICATE` respectively. Before submitting, make sure the contact details are not already used by another employee, including historical rejected applications.
### Request example
```json theme={null}
{
"customerRef": "ext-employee-0001",
"organizationId": "e7c9a1f0-3b52-4d8e-9a67-1f2b3c4d5e6f",
"firstName": "JOHN",
"lastName": "DOE",
"phoneCountryCode": "HK",
"phoneNumber": "12345678",
"email": "finance@example.com",
"addresses": [
{
"addressType": "SHIPPING_ADDRESS",
"postalCode": "999077",
"addressLine1": "Room 1201, Example Tower",
"addressLine2": "1 Example Street",
"addressLine3": "Central",
"city": "Hong Kong",
"state": "Hong Kong",
"addressCountryCode": "HK"
}
]
}
```
### Response example
```json theme={null}
{
"code": "SYS_SUCCESS",
"message": null,
"data": {
"customerApplyId": "5136744097353943553",
"status": "PENDING"
}
}
```
In the response `data`, `customerApplyId` is the employee application ID (the key for the query and resubmit calls that follow — persist it), and `status` is `PENDING` on acceptance.
### Error codes
| Error code | Description |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `APPLY_DUPLICATE` | An in-flight or already-successful application exists for the same `customerRef`; duplicate submission is not allowed |
| `APPLY_REJECTED_USE_RESUBMIT` | Only a rejected application exists for the same `customerRef` — use the resubmit endpoint on this page instead (a duplicate apply is no longer accepted) |
| `EMAIL_DUPLICATE` | The `email` is already taken under this partner (partner-wide, any state including rejected) |
| `PHONE_DUPLICATE` | The phone (area code + number) is already taken under this partner (partner-wide, any state including rejected) |
| `ORGANIZATION_INVALID` | The company does not exist or is not `ACTIVE` |
| `COUNTRY_SANCTIONED` | The supplied `addresses[].addressCountryCode` is on the sanctions list |
Related webhooks: `CUSTOMER_CREATED` / `CUSTOMER_REJECTED`.
## Query the application progress and result
**`GET /open-api-corp/customer/v1/query-apply`**
Rely on the webhooks as your primary channel; use this endpoint as the polling fallback.
### Request parameters
| Field | Type | Required | Description |
| ----------------- | ------ | -------- | -------------------------------- |
| `customerApplyId` | String | Yes | ≤20; the employee application ID |
### Response `data`
| Field | Type | Description |
| ----------------- | ------ | ------------------------------------------------------------------------- |
| `customerApplyId` | String | Application ID |
| `customerRef` | String | Your identifier |
| `organizationId` | String | The company the employee belongs to |
| `status` | String | `PENDING` / `SUCCEED` / `REJECTED` |
| `rejectMessage` | String | Rejection reason (when `REJECTED`) |
| `customerId` | String | The employee ID once the entity is created (present only after `SUCCEED`) |
### Request example
```http theme={null}
GET /open-api-corp/customer/v1/query-apply?customerApplyId=5136744097353943553
```
### Response example (approved)
`status=SUCCEED` and `customerId` has been issued — persist it:
```json theme={null}
{
"code": "SYS_SUCCESS",
"message": null,
"data": {
"customerApplyId": "5136744097353943553",
"customerRef": "ext-employee-0001",
"organizationId": "e7c9a1f0-3b52-4d8e-9a67-1f2b3c4d5e6f",
"status": "SUCCEED",
"rejectMessage": null,
"customerId": "a3f8d2b1-6c94-4e07-b512-9d8e7f6a5b4c"
}
}
```
### Response example (KYC rejected)
`status=REJECTED`, with `rejectMessage` explaining why; use the resubmit endpoint below to try again:
```json theme={null}
{
"code": "SYS_SUCCESS",
"message": null,
"data": {
"customerApplyId": "5136744097353943553",
"customerRef": "ext-employee-0001",
"organizationId": "e7c9a1f0-3b52-4d8e-9a67-1f2b3c4d5e6f",
"status": "REJECTED",
"rejectMessage": "name mismatch",
"customerId": null
}
}
```
### Error codes
| Error code | Description |
| ----------------- | ---------------------------------------------------------------------------- |
| `APPLY_NOT_FOUND` | The employee application does not exist (or does not belong to this partner) |
## Resubmit after a rejection
**`POST /open-api-corp/customer/v1/resubmit`**
After a KYC rejection, correct the name and send the application back for review under the same `customerApplyId`.
### Request parameters
| Field | Type | Required | Description |
| ----------------- | ------ | -------- | --------------------------------------------------------- |
| `customerApplyId` | String | Yes | ≤20; the rejected employee application ID |
| `firstName` | String | Yes | ≤64; first name; English letters, digits and spaces only |
| `lastName` | String | Yes | ≤64; last name; English letters, digits and spaces only |
| `middleName` | String | No | ≤64; middle name; English letters, digits and spaces only |
### Request example
```json theme={null}
{
"customerApplyId": "5136744097353943553",
"firstName": "JOHN",
"lastName": "DOE"
}
```
### Response example
```json theme={null}
{
"code": "SYS_SUCCESS",
"message": null,
"data": {
"customerApplyId": "5136744097353943553",
"customerRef": "ext-employee-0001",
"status": "PENDING"
}
}
```
### Error codes
| Error code | Description |
| ----------------- | ---------------------------------------------------------------------------- |
| `APPLY_NOT_FOUND` | The employee application does not exist (or does not belong to this partner) |
| `STATUS_CONFLICT` | The application is not currently `REJECTED`, so it cannot be resubmitted |
Related webhooks: `CUSTOMER_CREATED` / `CUSTOMER_REJECTED`.
To **rename** an employee after the entity has been created successfully, use the [update-name endpoint](./employee-maintenance) rather than resubmit; resubmit only serves the case where the application was rejected and no entity exists yet.
## Next steps
* Once the employee is created, maintain their details and freeze status: [Employee details and status](./employee-maintenance)
* Issue cards once the employee is `ACTIVE`: [Managing cards](./managing-cards)