Creating an employee - DCS Technical Documentation

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

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.

Employee creation and KYC outcome branches

Prerequisites

The company already exists and is ACTIVE (if not, start with 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

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

{
  "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

{
  "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

GET /open-api-corp/customer/v1/query-apply?customerApplyId=5136744097353943553

Response example (approved)

status=SUCCEED and customerId has been issued — persist it:

{
  "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:

{
  "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

{
  "customerApplyId": "5136744097353943553",
  "firstName": "JOHN",
  "lastName": "DOE"
}

Response example

{
  "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 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
Issue cards once the employee is ACTIVE: Managing cards

​📄 Guide

​Flow at a glance

​Prerequisites

​Submit the application

​Request parameters

​Request example

​Response example

​Error codes

​Query the application progress and result

​Request parameters

​Response data

​Request example

​Response example (approved)

​Response example (KYC rejected)

​Error codes

​Resubmit after a rejection

​Request parameters

​Request example

​Response example

​Error codes

​Next steps

📄 Guide

Flow at a glance

Prerequisites

Submit the application

Request parameters

Request example

Response example

Error codes

Query the application progress and result

Request parameters

Response `data`

Request example

Response example (approved)

Response example (KYC rejected)

Error codes

Resubmit after a rejection

Request parameters

Request example

Response example

Error codes

Next steps