API call description
After a DingTalk ID is changed, it cannot be changed again within one year.Request
Basic information
| Field | Value |
|---|---|
| HTTP URL | https://api.dingtalk.io/v1.0/contact/orgAccounts/dingTalkIds/change |
| HTTP Method | POST |
| Supported app types | appType-Internal app |
| Permissions required | permission-qyapi_manage_addresslist-Permission to access the API for maintaining Contacts |
Request header
| Name | Type | Required | Description |
|---|---|---|---|
| x-acs-dingtalk-access-token | String | Yes | The access credential for calling this API. Obtain it by calling the Get the access token of an internal app API. |
Request body
| Name | Type | Required | Description |
|---|---|---|---|
| userId | String | Yes | The userId of the employee. Only the userId of an Enterprise Account that belongs to your organization is supported. |
| dingTalkId | String | Yes | The new DingTalk ID. It must be globally unique, not only unique within the organization. Therefore, it cannot conflict with an existing one; if a conflict occurs, use an alternative value. Format requirements: 6 <= length <= 20, must start with a letter, can contain only letters and digits, and must not contain prohibited content. |
Request example
HTTPResponse
Response body
| Name | Type | Description |
|---|---|---|
| result | Boolean | The execution result. |
Response body example
Error codes
If an error is returned when you call this API, refer to the Global error codes document to find a solution based on the error message.| HttpCode | Error code | Error message | Description |
|---|---|---|---|
| 400 | incorrect.format | The DingTalk ID format is incorrect. Please re-enter it. | The DingTalk ID format is incorrect. Please re-enter it. |
| 400 | have.been.set | You have already set a DingTalk ID and cannot change it. | You have already set a DingTalk ID and cannot change it. |
| 400 | emp.not.exist | The employee does not exist. | The employee does not exist. |
| 400 | internalenterpriseaccount.limit | Only Enterprise Accounts belonging to your organization can be processed. | Only Enterprise Accounts belonging to your organization can be processed. |
| 400 | incorrect.length | The DingTalk ID format is incorrect. Please re-enter it. | The DingTalk ID format is incorrect. Please re-enter it. |
| 400 | incorrect.reserved | The DingTalk ID is already taken. Please re-enter it. | The DingTalk ID is already taken. Please re-enter it. |
| 500 | system.busy | The system is busy. Please try again later. | The system is busy. Please try again later. |