Skip to main content

Start a directory sync run

Start a directory sync run. POST /api/openapi/v1/directory-sync/runs, scope admin.v1.directory-sync-runs.execute.

  • Scope: admin.v1.directory-sync-runs.execute
  • Permission: Execute directory sync (directory-sync-runs)
  • Permission type: Execute
  • Endpoint: POST/api/openapi/v1/directory-sync/runs

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.
NameLocationTypeRequiredDescriptionExample
AuthorizationheaderstringYesApplication API key, passed as a Bearer token.Bearer qwk_***
X-Request-IdheaderstringNoOptional request tracing identifier; generated by the server if omitted.req-20260831-001

Request parameters

NameLocationTypeRequiredDescriptionExample
Idempotency-KeyheaderstringRequiredIdempotency key used to prevent duplicate submissions"<string>"
source_idbodystring · uuidRequiredSource ID"<uuid>"

Request example

cURL

Responses

202 Accepted
NameTypeRequiredDescriptionExample
runOpenapifacadeDirectorySyncRunYesSync records{"created_at":"2026-08-27T10:00:00Z","error_code":"<string>","error_summary":"<string>","finished_at":"2026-08-27T10:00:00Z","id":"<uuid>","requested_by_email":"<string>","requested_by_name":"<string>","resource_type":"<string>","result":"success","source_id":"<uuid>","source_name":"<string>","source_type":"<string>","started_at":"2026-08-27T10:00:00Z","stats":{"departments":{"created":0,"deactivated":0,"deleted":0,"updated":0},"failed":0,"processed":0,"relationships":{"added":0,"removed":0,"returned_to_root":0},"seats":{"granted":0,"reclaimed":0},"succeeded":0,"users":{"created":0,"deactivated":0,"deleted":0,"updated":0}},"status":"pending","trigger_type":"manual"}
run.created_atstring · date-timeYesCreated at"2026-08-27T10:00:00Z"
run.error_codestringNoError code"<string>"
run.error_summarystringNoError summary"<string>"
run.finished_atstring · date-timeNoFinished at"2026-08-27T10:00:00Z"
run.idstring · uuidYesSync run ID"<uuid>"
run.requested_by_emailstringNoRequester email"<string>"
run.requested_by_namestringNoRequested by"<string>"
run.resource_typestringYesResource type"<string>"
run.resultstringNoResult"success"
run.source_idstring · uuidYesSource ID"<uuid>"
run.source_namestringYesSource name"<string>"
run.source_typestringYesSource type"<string>"
run.started_atstring · date-timeNoStart time"2026-08-27T10:00:00Z"
run.statsOpenapifacadeDirectorySyncRunStatsYesSync statistics{"departments":{"created":0,"deactivated":0,"deleted":0,"updated":0},"failed":0,"processed":0,"relationships":{"added":0,"removed":0,"returned_to_root":0},"seats":{"granted":0,"reclaimed":0},"succeeded":0,"users":{"created":0,"deactivated":0,"deleted":0,"updated":0}}
run.stats.departmentsOpenapifacadeDirectorySyncChangeCountsYesDepartment statistics{"created":0,"deactivated":0,"deleted":0,"updated":0}
run.stats.departments.createdinteger · int64YesNumber created (departments)0
run.stats.departments.deactivatedinteger · int64NoNumber deactivated (departments)0
run.stats.departments.deletedinteger · int64YesNumber deleted (departments)0
run.stats.departments.updatedinteger · int64YesNumber updated (departments)0
run.stats.failedinteger · int64NoFailed count0
run.stats.processedinteger · int64NoProcessed count0
run.stats.relationshipsOpenapifacadeDirectorySyncRelationshipCountsYesMembership statistics{"added":0,"removed":0,"returned_to_root":0}
run.stats.relationships.addedinteger · int64YesNumber added (memberships)0
run.stats.relationships.removedinteger · int64YesNumber removed (memberships)0
run.stats.relationships.returned_to_rootinteger · int64YesNumber moved back to the root department (memberships)0
run.stats.seatsOpenapifacadeDirectorySyncSeatCountsYesSeat statistics{"granted":0,"reclaimed":0}
run.stats.seats.grantedinteger · int64YesNumber granted (seats)0
run.stats.seats.reclaimedinteger · int64YesNumber reclaimed (seats)0
run.stats.succeededinteger · int64NoSuccessful count0
run.stats.usersOpenapifacadeDirectorySyncChangeCountsYesUser statistics{"created":0,"deactivated":0,"deleted":0,"updated":0}
run.stats.users.createdinteger · int64YesNumber created (users)0
run.stats.users.deactivatedinteger · int64NoNumber deactivated (users)0
run.stats.users.deletedinteger · int64YesNumber deleted (users)0
run.stats.users.updatedinteger · int64YesNumber updated (users)0
run.statusstringYesStatus"pending"
run.trigger_typestringYesTrigger type"manual"
Response example
default Flat business error
NameTypeRequiredDescriptionExample
codestringNoStable business error code"<string>"
detailstringYesHuman-readable error description"<string>"
detailsOpenapiErrorDetailsNoError details{"field":"<string>","reason":"<string>","suggestion":"<string>"}
details.fieldstringNoRequest field that failed validation"<string>"
details.reasonstringNoStable validation failure reason"<string>"
details.suggestionstringNoSuggested normalized value"<string>"
errorstringYesStable HTTP error type"<string>"
Response example