> For AI agents: [llms.txt](https://docs.trustedauth.com/llms.txt) provides a Markdown index of this documentation. # Get directory synchronization settings `GET /api/web/v1/directorysyncs/{id}` Get the specified directory synchronization settings. Caller requires the DIRECTORIES:VIEW permission. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | id | path | Yes | string | The UUID of the directory synchronization settings to be returned. | ## Responses ### 200 Successful #### application/json Schema ```json { "type": "object", "properties": { "crawlFrequency": { "type": "integer", "description": "The rate at which the directory will be queried in milliseconds", "format": "int32", "example": 3600000 }, "deltaCrawl": { "type": "boolean", "description": "Only sync changed users/groups (delta sync) on next crawl." }, "directory": { "type": "object", "properties": { "aliasMappingName": { "type": "string", "description": "The name of the AD attribute value that will be mapped into comma seperated string value of alias", "example": "adminDescription,adminDisplayName" }, "certificate": { "type": "string", "description": "The SSL certificate to connect to the Directory with.", "format": "byte", "deprecated": true }, "directoryAttributeMappings": { "type": "array", "description": "Directory attribure mappings.", "items": { "type": "object", "properties": { "directoryAttributeName": { "type": "string", "description": "The name of the directory attribute being mapped.", "example": "givenName" }, "directoryId": { "type": "string", "description": "The UUID of the Directory the attribute mapping belongs to.", "example": "6781549d-433c-44ea-a42f-4705c26f3245" }, "id": { "type": "string", "description": "The UUID of the attribute mapping.", "example": "6781549d-433c-44ea-a42f-4705c26f3245" }, "userAttribute": { "required": [ "mandatory", "name", "systemDefined", "unique" ], "type": "object", "properties": { "id": { "type": "string", "description": "The UUID for this user attribute. Generated when the user attribute is created." }, "mandatory": { "type": "boolean", "description": "A flag indicating if users must have a value for this user attribute." }, "name": { "type": "string", "description": "The name of this user attribute." }, "systemDefined": { "type": "boolean", "description": "A flag indicating if this user attribute is one of the system defined user attributes." }, "type": { "type": "string", "description": "Type of user attribute. Currently only used to specify the type of contact if the attribute is to be used for OTP delivery.", "example": "OTP_EMAIL", "enum": [ "NONE", "OTP_EMAIL", "OTP_SMS", "OTP_VOICE", "OTP_WECHAT", "OTP_WHATSAPP" ] }, "unique": { "type": "boolean", "description": "A flag indicating if this attribute is intended to be unique." } }, "description": "Information about user attribute definitions.", "title": "UserAttribute" }, "userAttributeId": { "type": "string", "description": "The UUID of the Identity as a Service User Attribute being mapped to.", "example": "6781549d-433c-44ea-a42f-4705c26f3245" } }, "description": "A DirectoryAttributeMapping defines the information returned about a directory attribute mapping. A directory attribute mapping specifies which directory attribute values are mapped into which Identity as a Service user attributes.", "title": "DirectoryAttributeMapping" } }, "directoryConnections": { "type": "array", "description": "The connections that you want to connect when syncing.", "items": { "type": "object", "properties": { "certificate": { "type": "string", "description": "The SSL certificate to connect to the Directory with.", "format": "byte", "deprecated": true }, "directoryId": { "type": "string", "description": "The UUID of the Directory the connection belongs to.", "example": "6781549d-433c-44ea-a42f-4705c26f3245" }, "hostname": { "type": "string", "description": "The Directory hostname or IP address.", "example": "10.4.1.2 or directory.server.com" }, "id": { "type": "string", "description": "The UUID of the Directory connection." }, "port": { "type": "integer", "description": "The Directory port.", "format": "int32", "example": 389 }, "useSsl": { "type": "boolean", "description": "Whether or not to connect to the Directory using an SSL certificate." } }, "description": "The connections that you want to connect when syncing.", "title": "DirectoryConnection" } }, "directorySync": "circular(DirectorySync)", "directorySyncId": { "type": "string", "description": "The UUID of the directory sync", "example": "6781549d-433c-44ea-a42f-4705c26f3245" }, "groupFilters": { "type": "array", "description": "Directory group filters.", "items": { "type": "object", "properties": { "directoryId": { "type": "string", "description": "The UUID of the Directory the group filter belongs to.", "example": "6781549d-433c-44ea-a42f-4705c26f3245" }, "id": { "type": "string", "description": "The UUID of the group filter.", "example": "6781549d-433c-44ea-a42f-4705c26f3245" }, "name": { "type": "string", "description": "The name of the group to filter on.", "example": "Engineering" } }, "description": "A GroupFilter defines the information returned about a directory group filter.", "title": "GroupFilter" } }, "hostname": { "type": "string", "description": "The hostname of the Directory Can be an IP address or a hostname.", "example": "10.4.1.2 or directory.server.com", "deprecated": true }, "id": { "type": "string", "description": "The UUID of the Directory.", "example": "6781549d-433c-44ea-a42f-4705c26f3245" }, "name": { "type": "string", "description": "The name of the Directory.", "example": "Directory" }, "password": { "type": "string", "description": "The password to connect to the Directory with." }, "port": { "type": "integer", "description": "The port to connect to the Directory over.", "format": "int32", "example": 389, "deprecated": true }, "rootDomainNamingContext": { "type": "string", "description": "The root domain naming context of the Directory.", "example": "DC=AnyCorp,DC=biz" }, "searchBases": { "type": "array", "description": "The searchbases that you want to search when syncing.", "items": { "type": "object", "properties": { "directoryId": { "type": "string", "description": "The UUID of the Directory the seachbase belongs to.", "example": "6781549d-433c-44ea-a42f-4705c26f3245" }, "emptySearchBase": { "type": "boolean", "description": "Whether or not an empty searchbase is empty?" }, "id": { "type": "string", "description": "The UUID of the searchbase.", "example": "6781549d-433c-44ea-a42f-4705c26f3245" }, "node": { "type": "string", "description": "The searchbase node.", "example": "DC=Users" }, "subsearchbasesIncluded": { "type": "boolean", "description": "Whether or not a sub-tree is included?" } }, "description": "A SearchBase defines the information returned about a directory search base.", "title": "SearchBase" } }, "type": { "type": "string", "description": "The type of the Directory.", "example": "AD", "enum": [ "AD", "LDAP" ] }, "useSsl": { "type": "boolean", "description": "Whether or not to connect to the Directory using an SSL certificate.", "deprecated": true }, "userName": { "type": "string", "description": "The username to connect to the Directory with. Value must be a fully distinguished name or UPN.", "example": "CN=Administrator,CN=Users,DC=AnyCorp,DC=biz or Administrator@AnyCorp.biz" } }, "description": "A Directory defines the information returned about a directory.", "title": "Directory" }, "directoryId": { "type": "string", "description": "The ID of the directory." }, "directorySyncAgentId": { "type": "string", "description": "The UUID of the Directory Sync Gateway Agent.", "example": "6781549d-433c-44ea-a42f-4705c26f3245" }, "forceCrawlSequence": { "type": "integer", "description": "Sequence counter incremented on each force crawl to trigger agent sync.", "format": "int32" }, "groupDesyncPolicy": { "type": "string", "description": "Group desynchronization will be done based on the selected option.", "example": "GROUP_DELETED", "enum": [ "GROUP_LOCALLY_MANAGED", "GROUP_DELETED" ] }, "groupNameAttribute": { "type": "string", "description": "The group name attribute" }, "groupObjectClass": { "type": "string", "description": "The Group Object Class", "example": "groupOfNames" }, "groupSynchronizationType": { "type": "string", "description": "Group synchronization will be done based on the selected option.", "example": "ALL, FILTER or NONE", "enum": [ "ALL", "FILTER", "NONE" ] }, "id": { "type": "string", "description": "The UUID of the directory.", "example": "6781549d-433c-44ea-a42f-4705c26f3245" }, "lastUpdate": { "type": "string", "description": "The last time the directory was updated.", "format": "date-time", "example": "2019-02-19T13:15:27Z" }, "pageSize": { "type": "integer", "description": "The number of records that should returned per query. Default is 25.", "format": "int32", "example": 25 }, "state": { "type": "string", "description": "The status of the Directory Sync.", "example": "CRAWLING", "enum": [ "UNKNOWN", "ERROR", "PENDING_CHANGES", "SYNCED", "OUT_OF_SYNC", "CRAWLING", "CRAWL_COMPLETE", "NOTIFYING_GROUPS", "NOTIFYING_GROUPS_USERS", "NOTIFYING_USERS", "NOTIFY_COMPLETE", "SYNCING", "FAILED" ] }, "userDesyncPolicy": { "type": "string", "description": "User synchronization will be done based on the selected option.", "example": "USER_DELETED", "enum": [ "USER_LOCALLY_MANAGED_ENABLED", "USER_LOCALLY_MANAGED_DISABLED", "USER_DELETED" ] }, "userObjectClass": { "type": "string", "description": "The User Object Class" }, "userUniqueIdAttribute": { "type": "string", "description": "The User Unique Id Attribute" }, "waitBetweenNotifications": { "type": "integer", "description": "How long to wait between notifications in milliseconds.", "format": "int32", "example": 500 } }, "description": "A DirectorySync defines the information returned about the directory sync configuration of a directory.", "title": "DirectorySync" } ``` ### 400 Bad Request #### application/json Schema ```json { "type": "object", "properties": { "errorCode": { "type": "string", "description": "Error Codes specific to cause of failure.", "example": "invalid_user_response" }, "errorMessage": { "type": "string", "description": "Additional Error Message describing the error.", "example": "Application id cannot be null" }, "parameters": { "type": "array", "description": "Optional additional error information.", "items": { "type": "object", "description": "Optional additional error information." } } }, "description": "Object containing information about errors reported by services.", "title": "ErrorInfo" } ``` ### 401 Access denied #### application/json Schema ```json { "type": "object", "properties": { "errorCode": { "type": "string", "description": "Error Codes specific to cause of failure.", "example": "invalid_user_response" }, "errorMessage": { "type": "string", "description": "Additional Error Message describing the error.", "example": "Application id cannot be null" }, "parameters": { "type": "array", "description": "Optional additional error information.", "items": { "type": "object", "description": "Optional additional error information." } } }, "description": "Object containing information about errors reported by services.", "title": "ErrorInfo" } ``` ### 403 Forbidden #### application/json Schema ```json { "type": "object", "properties": { "errorCode": { "type": "string", "description": "Error Codes specific to cause of failure.", "example": "invalid_user_response" }, "errorMessage": { "type": "string", "description": "Additional Error Message describing the error.", "example": "Application id cannot be null" }, "parameters": { "type": "array", "description": "Optional additional error information.", "items": { "type": "object", "description": "Optional additional error information." } } }, "description": "Object containing information about errors reported by services.", "title": "ErrorInfo" } ``` ### 404 Not Found #### application/json Schema ```json { "type": "object", "properties": { "errorCode": { "type": "string", "description": "Error Codes specific to cause of failure.", "example": "invalid_user_response" }, "errorMessage": { "type": "string", "description": "Additional Error Message describing the error.", "example": "Application id cannot be null" }, "parameters": { "type": "array", "description": "Optional additional error information.", "items": { "type": "object", "description": "Optional additional error information." } } }, "description": "Object containing information about errors reported by services.", "title": "ErrorInfo" } ``` ### 409 Conflict #### application/json Schema ```json { "type": "object", "properties": { "errorCode": { "type": "string", "description": "Error Codes specific to cause of failure.", "example": "invalid_user_response" }, "errorMessage": { "type": "string", "description": "Additional Error Message describing the error.", "example": "Application id cannot be null" }, "parameters": { "type": "array", "description": "Optional additional error information.", "items": { "type": "object", "description": "Optional additional error information." } } }, "description": "Object containing information about errors reported by services.", "title": "ErrorInfo" } ``` ## Security Requirements ```json [ { "AdminAPIAuthentication": [ "DIRECTORIES:VIEW" ] } ] ```