Employees · Overview - DCS Technical Documentation

📄 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

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.

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. CUSTOMER_CREATED / CUSTOMER_REJECTED / CUSTOMER_STATUS_CHANGED (carries addRestrictions / removeRestrictions and remark).

Next steps

Issue cards once the employee is ACTIVE: Managing cards
The in-flight KYC conflict on renames: the update table above and the FAQ
In this group: Creating employees · Employee information and status

​📄 Guide

​Step 1: create the employee

​Step 2: get the KYC result

​Maintaining information and status

​Related webhooks

​Next steps

📄 Guide

Step 1: create the employee

Step 2: get the KYC result

Maintaining information and status

Related webhooks

Next steps