Create or replace a directory sync source

Scope: admin.v1.directory-sync-config.manage
Permission: Manage directory sync configuration (directory-sync-config)
Permission type: Manage
Endpoint: PUT/api/openapi/v1/directory-sync/sources/{sourceId}

Authentication and request headers

Call with an application API key. This endpoint checks only the scope above; read, manage and execute permissions do not imply one another.

Name	Location	Type	Required	Description	Example
Authorization	header	string	Yes	Application API key, passed as a Bearer token.	Bearer qwk_***
X-Request-Id	header	string	No	Optional request tracing identifier; generated by the server if omitted.	req-20260831-001

Request parameters

Name	Location	Type	Required	Description	Example
sourceId	path	string · uuid	Required	Source ID	"<uuid>"
Idempotency-Key	header	string	Required	Idempotency key used to prevent duplicate submissions	"<string>"
config_revision	body	integer · int64	No	Configuration revision	1
credentials	body	OpenapifacadeDirectorySourceCredentials	No	Credentials	{"agent_id":"<string>","app_id":"<string>","app_secret":"<string>","bind_dn":"<string>","bind_password":"<string>","client_id":"<string>","client_secret":"<string>","corp_id":"<string>","secret":"<string>","tenant_id":"<string>"}
default_seat	body	boolean	Required	Request seats for new users by default	false
deletion_alert_email	body	string	No	Alert email	"<string>"
deletion_alert_enabled	body	boolean	Required	Deletion alert	false
deletion_alert_threshold	body	integer · int64	Required	Deletion alert threshold	0
deletion_policy	body	string	Required	Offboarding	"delete_user"
initial_scim_token	body	string	No	Initial SCIM token	"<string>"
name	body	string	Required	Source name	"<string>"
schedule	body	string	Required	Sync frequency	"manual"
schedule_anchor_at	body	string · date-time	No	Sync time (Beijing time)	"2026-08-27T10:00:00Z"
settings	body	OpenapifacadeDirectorySourceSettings	Required	Source configuration	{"connection":{"client_name":"<string>","tls_enabled":false,"url":"<string>"},"department_mapping":{"external_id":"<string>","name":"<string>","order":"<string>","parent_external_id":"<string>","status":"<string>"},"mapping":{"account":"<string>","department_external_id":"<string>","email":"<string>","employee_no":"<string>","external_id":"<string>","name":"<string>","phone":"<string>","status":"<string>"},"scope":{"base_dn":"<string>","mode":"all","org_unit_external_ids":["<string>"],"org_unit_filter":"<string>","user_filter":"<string>"}}
source_type	body	string	Required	Source type	"dingtalk"

Request example

cURL

Responses

200 OK

Name	Type	Required	Description	Example
config_revision	integer · int64	Yes	Configuration revision	0
connection_status	string	Yes	Connection	"<string>"
created_at	string · date-time	Yes	Created at	"2026-08-27T10:00:00Z"
created_by_email	string	No	Creator email	"<string>"
created_by_name	string	No	Created by	"<string>"
credential_configured	boolean	Yes	Whether credentials are configured	false
default_seat	boolean	Yes	Request seats for new users by default	false
deletion_alert_email	string	No	Alert email	"<string>"
deletion_alert_enabled	boolean	Yes	Deletion alert	false
deletion_alert_threshold	integer · int64	Yes	Deletion alert threshold	0
deletion_policy	string	Yes	Offboarding	"<string>"
external_id_field	string	Yes	Source field for the external user ID	"<string>"
external_id_field_locked	boolean	Yes	Whether the external user ID mapping is locked	false
id	string · uuid	Yes	Source ID	"<uuid>"
last_activity_at	string · date-time	No	Last activity time	"2026-08-27T10:00:00Z"
last_connected_at	string · date-time	No	Last connection time	"2026-08-27T10:00:00Z"
last_connection_error_code	string	No	Last connection error code	"<string>"
modified_at	string · date-time	Yes	Updated at	"2026-08-27T10:00:00Z"
name	string	Yes	Source name	"<string>"
next_run_at	string · date-time	No	Next sync time	"2026-08-27T10:00:00Z"
schedule	string	Yes	Sync frequency	"<string>"
schedule_anchor_at	string · date-time	No	Sync time (Beijing time)	"2026-08-27T10:00:00Z"
settings	OpenapifacadeDirectorySourceSettings	Yes	Source configuration	{"connection":{"client_name":"<string>","tls_enabled":false,"url":"<string>"},"department_mapping":{"external_id":"<string>","name":"<string>","order":"<string>","parent_external_id":"<string>","status":"<string>"},"mapping":{"account":"<string>","department_external_id":"<string>","email":"<string>","employee_no":"<string>","external_id":"<string>","name":"<string>","phone":"<string>","status":"<string>"},"scope":{"base_dn":"<string>","mode":"all","org_unit_external_ids":["<string>"],"org_unit_filter":"<string>","user_filter":"<string>"}}
settings.connection	OpenapifacadeDirectorySourceConnection	Yes	Connection settings	{"client_name":"<string>","tls_enabled":false,"url":"<string>"}
settings.connection.client_name	string	No	SCIM Client	"<string>"
settings.connection.tls_enabled	boolean	No	Enable TLS	false
settings.connection.url	string	No	Server URL	"<string>"
settings.department_mapping	OpenapifacadeDirectorySourceDepartmentMapping	Yes	Department mappings	{"external_id":"<string>","name":"<string>","order":"<string>","parent_external_id":"<string>","status":"<string>"}
settings.department_mapping.external_id	string	Yes	External department ID (source field)	"<string>"
settings.department_mapping.name	string	Yes	Department name (source field)	"<string>"
settings.department_mapping.order	string	No	Sort order (source field)	"<string>"
settings.department_mapping.parent_external_id	string	No	External parent department ID (source field)	"<string>"
settings.department_mapping.status	string	No	Status (source field)	"<string>"
settings.mapping	OpenapifacadeDirectorySourceFieldMapping	Yes	Member mappings	{"account":"<string>","department_external_id":"<string>","email":"<string>","employee_no":"<string>","external_id":"<string>","name":"<string>","phone":"<string>","status":"<string>"}
settings.mapping.account	string	No	Account (source field)	"<string>"
settings.mapping.department_external_id	string	No	External department ID for the user's department (source field)	"<string>"
settings.mapping.email	string	No	Email (source field)	"<string>"
settings.mapping.employee_no	string	No	Employee ID (source field)	"<string>"
settings.mapping.external_id	string	Yes	External user ID (source field)	"<string>"
settings.mapping.name	string	Yes	User name (source field)	"<string>"
settings.mapping.phone	string	No	Phone number (source field)	"<string>"
settings.mapping.status	string	No	Status (source field)	"<string>"
settings.scope	OpenapifacadeDirectorySourceScope	Yes	Sync scope	{"base_dn":"<string>","mode":"all","org_unit_external_ids":["<string>"],"org_unit_filter":"<string>","user_filter":"<string>"}
settings.scope.base_dn	string	No	Base DN	"<string>"
settings.scope.mode	string	Yes	Sync scope type	"all"
settings.scope.org_unit_external_ids	array ｜ null	No	Scope departments (external department IDs)	["<string>"]
settings.scope.org_unit_filter	string	No	Department filter	"<string>"
settings.scope.user_filter	string	No	User filter	"<string>"
source_type	string	Yes	Source type	"<string>"
status	string	Yes	Status	"<string>"
updated_by_email	string	No	Updater email	"<string>"
updated_by_name	string	No	Updated by	"<string>"

Response example

default Flat business error

Name	Type	Required	Description	Example
code	string	No	Stable business error code	"<string>"
detail	string	Yes	Human-readable error description	"<string>"
details	OpenapiErrorDetails	No	Error details	{"field":"<string>","reason":"<string>","suggestion":"<string>"}
details.field	string	No	Request field that failed validation	"<string>"
details.reason	string	No	Stable validation failure reason	"<string>"
details.suggestion	string	No	Suggested normalized value	"<string>"
error	string	Yes	Stable HTTP error type	"<string>"

Response example

​Authentication and request headers

​Request parameters

​Request example

​Responses

Authentication and request headers

Request parameters

Request example

Responses