> ## 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. # Employee information and status > The full call detail for maintaining existing employees: query for details (including the address array), one endpoint each for name / phone / email / address, and update-restrictions to freeze and unfreeze by capability code. ## 📄 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](./employee-onboarding); the full state machine is in [State machine and freezing](../basic-concepts/states-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 ```http theme={null} GET /open-api-corp/customer/v1/query?customerId=a3f8d2b1-6c94-4e07-b512-9d8e7f6a5b4c ``` ### Response example ```json theme={null} { "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 | ```json theme={null} { "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 `+` | ```json theme={null} { "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 | ```json theme={null} { "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 | ```json theme={null} { "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\ | 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\ | 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): ```json theme={null} { "customerId": "a3f8d2b1-6c94-4e07-b512-9d8e7f6a5b4c", "addRestrictions": ["PAYMENT_FROZEN", "CARD_FROZEN"], "remark": "suspicious transactions" } ``` Unfreeze (remove restrictions): ```json theme={null} { "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](./managing-cards) * The full employee state machine and freezing capabilities: [State machine and freezing](../basic-concepts/states-and-freezing)