Employee information and status - DCS Technical Documentation

📄 Guide

Day-to-day maintenance after an employee has been created is covered by six endpoints: query the details, one update endpoint each for name / phone / email / address, and freeze/unfreeze. A name change triggers KYC re-submission; the other three do not touch KYC. Freezing and unfreezing use add/remove set semantics over capability codes. Creation and resubmission are covered in Creating employees; the full state machine is in State machine and freezing.

Querying employee details

GET /open-api-corp/customer/v1/query Returns the employee’s name, contact details, status and address list (once maintained).

Request parameters (query string)

Field	Type	Required	Description
`customerId`	String	Yes	≤36; employee ID

Response `data`

Field	Type	Description
`customerId`	String	Employee ID
`customerRef`	String	Your own employee identifier (echoed)
`organizationId`	String	The organization the employee belongs to
`firstName`	String	First name
`middleName`	String	Middle name
`lastName`	String	Last name
`phoneCountryCode`	String	Country / region code of the mobile number
`phoneNumber`	String	Mobile number
`email`	String	Email address
`status`	String	Employee status: lifecycle `ACTIVE` / `TERMINATED`; behavioral `SUSPENDED` / `FROZEN` / `RESTRICTED`
`addresses`	Array	Address list, element structure below; empty when never maintained

addresses[] element structure:

Field	Type	Description
`addressType`	String	Address purpose, the discriminator inside the array. Current value: `SHIPPING_ADDRESS` (physical card delivery)
`postalCode`	String	Postal code (absent in some regions, may be empty)
`addressLine1`	String	Address line 1
`addressLine2`	String	Address line 2 (may be empty)
`addressLine3`	String	Address line 3 (may be empty)
`city`	String	City (a district is acceptable for Hong Kong)
`state`	String	State / province (`Hong Kong` for Hong Kong)
`addressCountryCode`	String	Two-letter ISO country code (for example `HK`)

Request example

GET /open-api-corp/customer/v1/query?customerId=a3f8d2b1-6c94-4e07-b512-9d8e7f6a5b4c

Response example

{
  "code": "SYS_SUCCESS",
  "message": null,
  "data": {
    "customerId": "a3f8d2b1-6c94-4e07-b512-9d8e7f6a5b4c",
    "customerRef": "emp-acme-0001",
    "organizationId": "e7c9a1f0-3b52-4d8e-9a67-1f2b3c4d5e6f",
    "firstName": "TAI MAN",
    "middleName": null,
    "lastName": "CHAN",
    "phoneCountryCode": "HK",
    "phoneNumber": "91234567",
    "email": "taiman.chan@acme.com",
    "status": "ACTIVE",
    "addresses": [
      {
        "addressType": "SHIPPING_ADDRESS",
        "postalCode": "999077",
        "addressLine1": "Flat 5, 12/F, Acme Tower",
        "addressLine2": "8 Connaught Road Central",
        "addressLine3": "Central",
        "city": "Hong Kong",
        "state": "Hong Kong",
        "addressCountryCode": "HK"
      }
    ]
  }
}

Error codes

Error code	Description
`CUSTOMER_INVALID`	The employee does not exist (or does not belong to your partner account)

Updating employee information

Each of the four categories has its own endpoint. The path states the intent, the request carries only the fields that category needs, and the error codes returned are only the ones that category can hit:

Endpoint	What it changes	Triggers KYC
`POST /open-api-corp/customer/v1/update-name`	The three name parts	Yes — resubmitted whenever the name actually changes
`POST /open-api-corp/customer/v1/update-phone`	Mobile country code + number	No
`POST /open-api-corp/customer/v1/update-email`	Email address	No
`POST /open-api-corp/customer/v1/update-address`	Address list	No

All four are action endpoints: on success they return SYS_SUCCESS with data set to null.

Updating the name

The name is replaced as a whole: the firstName + middleName + lastName submitted become the new legal name, with no per-part merging — KYC compares the complete name, and only a whole-name submission makes what goes to review unambiguous. Omitting middleName means there is no middle name, and any previous value is cleared. The call either fully succeeds or fully fails; there is no partial success.

Field	Type	Required	Description
`customerId`	String	Yes	≤36; the target employee
`firstName`	String	Yes	≤64; letters, digits and spaces only
`middleName`	String	No	≤64; omitting it means no middle name (any previous value is cleared)
`lastName`	String	Yes	≤64; letters, digits and spaces only

{
  "customerId": "a3f8d2b1-6c94-4e07-b512-9d8e7f6a5b4c",
  "firstName": "TAI MAN",
  "lastName": "CHAN"
}

Error code	Description
`CUSTOMER_INVALID`	The employee does not exist or is not in a valid state
`KYC_IN_REVIEW`	The employee already has a KYC review in flight; retry once it completes

Updating the mobile number

The country code and the number must be submitted together. This number also serves as the delivery contact for physical cards.

Field	Type	Required	Description
`customerId`	String	Yes	≤36; the target employee
`phoneCountryCode`	String	Yes	Exactly 2 characters; ISO-3166-1 alpha-2 uppercase (for example `HK`), and must be on the supported list
`phoneNumber`	String	Yes	≤15; digits only, local number without the country code and without `+`

{
  "customerId": "a3f8d2b1-6c94-4e07-b512-9d8e7f6a5b4c",
  "phoneCountryCode": "HK",
  "phoneNumber": "91234567"
}

Error code	Description
`CUSTOMER_INVALID`	The employee does not exist or is not in a valid state

Updating the email address

Field	Type	Required	Description
`customerId`	String	Yes	≤36; the target employee
`email`	String	Yes	≤128; contact email address

{
  "customerId": "a3f8d2b1-6c94-4e07-b512-9d8e7f6a5b4c",
  "email": "taiman.chan@acme.com"
}

Error code	Description
`CUSTOMER_INVALID`	The employee does not exist or is not in a valid state

Updating addresses

The update is “partial by addressType, whole by object”: only the address types present in the request are affected, types left out are untouched, and a type that is matched has its whole object replaced. Field-level edits are not supported.

Field	Type	Required	Description
`customerId`	String	Yes	≤36; the target employee
`addresses`	Array	Yes	At least one entry; element structure as in the query response above, where `addressType` / `addressLine1` / `city` / `state` / `addressCountryCode` are required

{
  "customerId": "a3f8d2b1-6c94-4e07-b512-9d8e7f6a5b4c",
  "addresses": [
    {
      "addressType": "SHIPPING_ADDRESS",
      "postalCode": "999077",
      "addressLine1": "Flat 5, 12/F, Acme Tower",
      "addressLine2": "8 Connaught Road Central",
      "addressLine3": "Central",
      "city": "Hong Kong",
      "state": "Hong Kong",
      "addressCountryCode": "HK"
    }
  ]
}

An address update only affects later virtual-to-physical applications — the address is snapshotted into the application when it is accepted, so cards already in transit or delivered are unaffected.

Error code	Description
`CUSTOMER_INVALID`	The employee does not exist or is not in a valid state
`COUNTRY_SANCTIONED`	`addresses[].addressCountryCode` is on a sanctions list

Freezing and unfreezing (updating employee restrictions)

POST /open-api-corp/customer/v1/update-restrictions Freeze or unfreeze an employee. The semantics match the organization side exactly: adding a restriction freezes, removing it unfreezes, with idempotent set semantics that make repeated submissions safe. Only the five open L1 capability codes are accepted:

Capability code	What it disables
`ACCOUNT_FROZEN`	The account as a whole (sign-in, password change, phone / email change, MFA binding, closure)
`CASH_IN_FROZEN`	Deposits / top-ups
`CASH_OUT_FROZEN`	Withdrawals / remittances
`PAYMENT_FROZEN`	Payments / spending (card payments included)
`CARD_FROZEN`	Card management actions (apply, activate, change PIN)

Once an employee is frozen, every card in their name declines transactions. Restricted states written by risk, regulatory or judicial processes cannot be lifted through this endpoint.

Request parameters

Field	Type	Required	Description
`customerId`	String	Yes	≤36; the target employee
`addRestrictions`	Array<String>	Conditional	Restrictions to add; multiple allowed. At least one of `addRestrictions` / `removeRestrictions` is required — omitting both returns `DAPI_PARAM_INVALID`. Elements must come from the five L1 capability codes above; anything else (including `KYC_FROZEN` / `TRANSFER_FROZEN` / L2 fine-grained codes / `SUSPENDED` / `RESTRICTED`) also returns `DAPI_PARAM_INVALID`
`removeRestrictions`	Array<String>	Conditional	Restrictions to remove; same value constraints as `addRestrictions`; at least one of the two is required
`remark`	String	No	≤256; operation remark

Request examples

Freeze (add restrictions):

{
  "customerId": "a3f8d2b1-6c94-4e07-b512-9d8e7f6a5b4c",
  "addRestrictions": ["PAYMENT_FROZEN", "CARD_FROZEN"],
  "remark": "suspicious transactions"
}

Unfreeze (remove restrictions):

{
  "customerId": "a3f8d2b1-6c94-4e07-b512-9d8e7f6a5b4c",
  "removeRestrictions": ["PAYMENT_FROZEN", "CARD_FROZEN"],
  "remark": "risk cleared"
}

Error codes

Error code	Description
`CUSTOMER_INVALID`	The employee does not exist (or does not belong to your partner account)
`STATUS_CONFLICT`	The current status does not allow the operation (for example the employee is not `ACTIVE`)

Related webhook: CUSTOMER_STATUS_CHANGED, with businessId set to customerId and data carrying this change’s addRestrictions / removeRestrictions and remark.

Next steps

Once the employee is ACTIVE and not frozen, issue and manage their cards: Managing cards
The full employee state machine and freezing capabilities: State machine and freezing

​📄 Guide

​Querying employee details

​Request parameters (query string)

​Response data

​Request example

​Response example

​Error codes

​Updating employee information

​Updating the name

​Updating the mobile number

​Updating the email address

​Updating addresses

​Freezing and unfreezing (updating employee restrictions)

​Request parameters

​Request examples

​Error codes

​Next steps

📄 Guide

Querying employee details

Request parameters (query string)

Response `data`

Request example

Response example

Error codes

Updating employee information

Updating the name

Updating the mobile number

Updating the email address

Updating addresses

Freezing and unfreezing (updating employee restrictions)

Request parameters

Request examples

Error codes

Next steps