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

# Employees · Overview

> Create and maintain employees under an ACTIVE organization: KYC submission, querying and resubmission, one update endpoint per category, freeze/unfreeze — with the uniqueness and re-review rules.

## 📄 Guide

Employees are the end cardholders — and the source of custodians for company cards. Creating an employee runs asynchronous KYC name screening; only after it passes can you issue them cards. This page covers creation, result handling and information maintenance.

## Step 1: create the employee

`POST /open-api-corp/customer/v1/apply` (the company must be ACTIVE).

| Field                                   | Required       | Description                                                                                                                                                                                                                                                                                                                   |
| --------------------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `customerRef`                           | Yes            | ≤64; your unique employee identifier (the idempotency key)                                                                                                                                                                                                                                                                    |
| `organizationId`                        | Yes            | The organization, must be ACTIVE                                                                                                                                                                                                                                                                                              |
| `firstName` / `lastName` / `middleName` | Yes / Yes / No | ≤64 each; English letters, digits and spaces only                                                                                                                                                                                                                                                                             |
| `phoneCountryCode` + `phoneNumber`      | Yes            | Area code is a two-letter ISO country code (e.g. `HK`); number is digits only, ≤15                                                                                                                                                                                                                                            |
| `email`                                 | Yes            | ≤128                                                                                                                                                                                                                                                                                                                          |
| `addresses`                             | No             | Address list; each element carries `addressType` (currently only `SHIPPING_ADDRESS`) / `postalCode` / `addressLine1` / `addressLine2` / `addressLine3` / `city` / `state` / `addressCountryCode`. Can be added later through the update endpoint; **an employee without a shipping address cannot apply for a physical card** |

<Warning>
  **Uniqueness**: within one partner, employee email and phone (area code + number) are unique across companies and are **never released, even after a rejection** (`EMAIL_DUPLICATE` / `PHONE_DUPLICATE`). An address country on the sanctions list returns `COUNTRY_SANCTIONED`.
</Warning>

## Step 2: get the KYC result

Rely on webhooks `CUSTOMER_CREATED` / `CUSTOMER_REJECTED`, with `GET /open-api-corp/customer/v1/query-apply` as fallback (by `customerApplyId` or by your own `customerRef`). On `status=SUCCEED` you receive `customerId` (persist it); on `REJECTED`, `rejectMessage` explains why.

**Resubmission after rejection**: `POST /open-api-corp/customer/v1/resubmit` with `customerApplyId` plus the three corrected name parts, re-reviewed under the same application; calling outside the `REJECTED` state returns `STATUS_CONFLICT`.

## Maintaining information and status

**Query employee detail**: `GET /open-api-corp/customer/v1/query?customerId=...` — name, contact details, status and the address list (empty if never set).

**Update employee information**: each of the four categories has its own endpoint, and the path states the intent:

| Endpoint         | Fields                                                   | Notes                                                                                                                                                                               |
| ---------------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `update-name`    | `firstName` + `lastName` required, `middleName` optional | The name is **replaced as a whole**; any actual change **re-triggers KYC review**, and with a KYC already in flight the call returns `KYC_IN_REVIEW` — retry after the result lands |
| `update-phone`   | `phoneCountryCode` + `phoneNumber` (as a pair)           | Same uniqueness rules as creation                                                                                                                                                   |
| `update-email`   | `email`                                                  | Same uniqueness rules as creation                                                                                                                                                   |
| `update-address` | The `addresses` array                                    | Partial by `addressType`, whole-object by entry — no field-level partial update                                                                                                     |

**Freeze / unfreeze**: `POST /open-api-corp/customer/v1/update-restrictions`, identical semantics to organizations (`addRestrictions` / `removeRestrictions`, the 5 capability-domain codes only). **Freezing an employee makes every card under them decline transactions.**

## Related webhooks

`CUSTOMER_CREATED` / `CUSTOMER_REJECTED` / `CUSTOMER_STATUS_CHANGED` (carries `addRestrictions` / `removeRestrictions` and `remark`).

## Next steps

* Issue cards once the employee is ACTIVE: [Managing cards](./managing-cards)
* The in-flight KYC conflict on renames: the update table above and the [FAQ](../customer-success/faq)
* In this group: [Creating employees](./employee-onboarding) · [Employee information and status](./employee-maintenance)