> ## 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. # 创建员工 > 员工创建申请的完整调用细节：apply 全字段与寄送地址结构、邮箱手机唯一性规则、query-apply 查询进度与结果、被拒后 resubmit 重提。 ## 📄 正文 员工是最终持卡人，创建员工是发卡前的必经一步。您在 ACTIVE 公司下提交员工资料，DCS 受理后异步进行个人尽职调查（KYC 姓名筛查），结果以 Webhook 通知为主、查询接口兜底；KYC 被拒时按同一 `customerApplyId` 修正姓名重提即可。本页覆盖创建申请、查询结果与重新提交三个接口的全部字段与示例，能力总览见[管理员工](./managing-employees)。 ### 流程总览 申请状态机只有三个状态：`PENDING` / `SUCCEED` / `REJECTED`。被拒后不换 ID 重发，而是沿用同一 `customerApplyId` 重提。 创建员工与 KYC 结果分支 创建员工与 KYC 结果分支 ### 前置条件 * 所属公司已创建且处于 `ACTIVE` 状态（如尚未创建，请先阅读[管理公司](./managing-companies)）。 * 已准备员工的姓名、手机号、邮箱；如需申请实体卡，还需准备寄送地址。 ## 提交创建申请 **`POST /open-api-corp/customer/v1/apply`** 创建员工：提交资料，异步进行个人尽职调查（KYC 姓名筛查）。地址信息请传入寄送地址。 ### 请求参数 | 字段 | 类型 | 必填 | 说明 | | ------------------ | ------ | -- | ----------------------------------------------------------------------- | | `customerRef` | String | 是 | ≤64；合作伙伴侧员工唯一标识；字符集 `^[A-Za-z0-9_-]+$` | | `organizationId` | String | 是 | ≤20；所属公司，须 `ACTIVE` | | `firstName` | String | 是 | ≤64；名；仅允许英文、数字、空格 | | `lastName` | String | 是 | ≤64；姓；仅允许英文、数字、空格 | | `middleName` | String | 否 | ≤64；中间名；仅允许英文、数字、空格 | | `phoneCountryCode` | String | 是 | 固定 2 位；手机区号（ISO 3166-1 alpha-2 两位字母，如 `HK`；须在支持列表中） | | `phoneNumber` | String | 是 | ≤15；手机号（纯数字） | | `email` | String | 是 | ≤128；邮箱 | | `addresses` | Array | 否 | 地址列表（结构见下表）。创建时携带则随开户流程落库；未携带可在开户后经[更新员工地址](./employee-maintenance)补充维护 | `addresses[]` 元素结构： | 字段 | 必填 | 说明 | | -------------------- | -- | --------------------------------------------- | | `addressType` | 是 | 地址用途，数组内的判别字段。当前值域仅 `SHIPPING_ADDRESS`（实体卡寄送） | | `postalCode` | 否 | 邮编（部分地区无，可为空） | | `addressLine1` | 是 | 地址行 1，≤40 | | `addressLine2` | 否 | 地址行 2，≤40 | | `addressLine3` | 否 | 地址行 3，≤40 | | `city` | 是 | 城市（香港可填区域），≤64 | | `state` | 是 | 州 / 省（香港填 `Hong Kong`），≤20 | | `addressCountryCode` | 是 | 两位 ISO 国家码（如 `HK`） | **无寄送地址的员工无法申请实体卡**。仅发虚拟卡可不传 `addresses`，后续需要实体卡时再经更新接口补充。 **唯一性规则**：同一合作伙伴下，员工邮箱与手机号（区号 + 号码）跨公司唯一，且**占用后即使申请被拒也不释放**，重复提交分别返回 `EMAIL_DUPLICATE` / `PHONE_DUPLICATE`。请在提交前确认联系方式未被其它员工（含历史被拒申请）使用。 ### 请求示例 ```json theme={null} { "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" } ] } ``` ### 响应示例 ```json theme={null} { "code": "SYS_SUCCESS", "message": null, "data": { "customerApplyId": "5136744097353943553", "status": "PENDING" } } ``` 响应 `data` 中，`customerApplyId` 是员工创建申请 ID（后续查询与重提的关联键，请落库保存），`status` 受理即为 `PENDING`。 ### 错误码 | 错误码 | 说明 | | ----------------------------- | -------------------------------------------------- | | `APPLY_DUPLICATE` | 同一 `customerRef` 已存在在途 / 已成功的申请，不可重复提交 | | `APPLY_REJECTED_USE_RESUBMIT` | 同一 `customerRef` 仅存在被拒申请，改用本页的重新提交接口（不再放行重复 apply） | | `EMAIL_DUPLICATE` | 同合作伙伴下该 `email` 已被占用（合作伙伴级，任意状态含被拒） | | `PHONE_DUPLICATE` | 同合作伙伴下该手机号（区号 + 号码）已被占用（合作伙伴级，任意状态含被拒） | | `ORGANIZATION_INVALID` | 所属公司不存在或非 `ACTIVE` | | `COUNTRY_SANCTIONED` | 携带的 `addresses[].addressCountryCode` 命中制裁名单 | 关联 Webhook：`CUSTOMER_CREATED` / `CUSTOMER_REJECTED`。 ## 查询申请进度与结果 **`GET /open-api-corp/customer/v1/query-apply`** 以 Webhook 通知为主，本接口兜底轮询。 ### 请求参数 | 字段 | 类型 | 必填 | 说明 | | ----------------- | ------ | -- | ----------- | | `customerApplyId` | String | 是 | ≤20；员工申请 ID | ### 响应 `data` | 字段 | 类型 | 说明 | | ----------------- | ------ | ---------------------------------- | | `customerApplyId` | String | 申请 ID | | `customerRef` | String | 合作伙伴侧标识 | | `organizationId` | String | 所属公司 | | `status` | String | `PENDING` / `SUCCEED` / `REJECTED` | | `rejectMessage` | String | 拒绝原因（`REJECTED` 时） | | `customerId` | String | 落实体后的员工 ID（`SUCCEED` 后才有） | ### 请求示例 ```http theme={null} GET /open-api-corp/customer/v1/query-apply?customerApplyId=5136744097353943553 ``` ### 响应示例（审核通过） `status=SUCCEED`，`customerId` 已下发，请落库保存： ```json theme={null} { "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" } } ``` ### 响应示例（KYC 被拒） `status=REJECTED`，`rejectMessage` 给出原因，可用下方重新提交接口重提： ```json theme={null} { "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 } } ``` ### 错误码 | 错误码 | 说明 | | ----------------- | ----------------- | | `APPLY_NOT_FOUND` | 员工申请不存在（或不属本合作伙伴） | ## 被拒后重新提交 **`POST /open-api-corp/customer/v1/resubmit`** KYC 被拒后修正姓名，按同一 `customerApplyId` 重新送审。 ### 请求参数 | 字段 | 类型 | 必填 | 说明 | | ----------------- | ------ | -- | ------------------- | | `customerApplyId` | String | 是 | ≤20；被拒的员工申请 ID | | `firstName` | String | 是 | ≤64；名；仅允许英文、数字、空格 | | `lastName` | String | 是 | ≤64；姓；仅允许英文、数字、空格 | | `middleName` | String | 否 | ≤64；中间名；仅允许英文、数字、空格 | ### 请求示例 ```json theme={null} { "customerApplyId": "5136744097353943553", "firstName": "JOHN", "lastName": "DOE" } ``` ### 响应示例 ```json theme={null} { "code": "SYS_SUCCESS", "message": null, "data": { "customerApplyId": "5136744097353943553", "customerRef": "ext-employee-0001", "status": "PENDING" } } ``` ### 错误码 | 错误码 | 说明 | | ----------------- | ----------------------- | | `APPLY_NOT_FOUND` | 员工申请不存在（或不属本合作伙伴） | | `STATUS_CONFLICT` | 申请当前非 `REJECTED`，不可重新提交 | 关联 Webhook：`CUSTOMER_CREATED` / `CUSTOMER_REJECTED`。 员工创建成功后如需**改名**，走[更新员工姓名](./employee-maintenance)接口而非 resubmit；resubmit 只服务于「申请被拒、实体尚未落地」的场景。 ## 下一步 * 员工创建成功后，维护其信息与冻结状态：[员工信息与状态](./employee-maintenance) * 员工 `ACTIVE` 后为其发卡：[管理卡片](./managing-cards)