> For AI agents: [llms.txt](https://docs.trustedauth.com/llms.txt) provides a Markdown index of this documentation.

# Synchronize a new user or an existing user

`POST /api/web/v1/syncusers/sync`

Synchronize a user. Caller requires the USERS:EDIT permission. An Identity as a Service directory must be configured and associated with an Identity as a Service Gateway 5.0 or later. If you unsynchronize a user using the unsync API, the user becomes locally managed. In order to set the user back to an AD Sync user, the user should be synchronized again using this API. Using an AD Sync crawl will only re-synchronize the user if the user is updated in AD (i.e., the user's last update time in AD is updated) or a new custom user attribute mapping is added for the directory (this resets The last update time for all users such that all AD users will be re-synchronlized).<br/><br/>The following response status attribute values are possible: <ul><li>CONVERTED:  the locally managed Identity as a Service user was converted into an AD Sync user.</li><li>CREATED: a new user was created as an AD Sync user.</li><li>DELETED: the user was not found in AD and has been deleted in Identity as a Service.</li><li>LOCALIZED_ENABLED: the user was not found in AD and has been set as locally managed and enabled in Identity as a Service.</li><li>LOCALIZED_DISABLED: the user was not found in AD and has been set as locally managed and disabled in Identity as a Service.</li><li>UPDATED: the user was synchronized.</li></ul>

## Request Body

Required.

### application/json

Schema

```json
{
  "required": [
    "directoryId",
    "id"
  ],
  "type": "object",
  "properties": {
    "directoryId": {
      "type": "string",
      "description": "The directory id for this synchronization.  This value is required",
      "example": "993dd9b4-e25c-433b-aac6-868b596763a6"
    },
    "id": {
      "type": "string",
      "description": "The id of the user to be synchronized.  The type of the id is specified by idType.",
      "example": "jsmith"
    },
    "idType": {
      "type": "string",
      "description": "The type of the id identifying the user.  The value can be one of UUID (the user's internal UUID) or USERID (the user's userId). The value of EXTERNALID  is currently not supported.  If not specified, this defaults to USERID.",
      "enum": [
        "UUID",
        "USERID",
        "EXTERNALID"
      ]
    }
  },
  "description": "Parameters for synchronization.",
  "title": "SyncUserParms"
}
```

## Responses

### 200

Successful

#### application/json

Schema

```json
{
  "required": [
    "status",
    "userId",
    "uuid"
  ],
  "type": "object",
  "properties": {
    "directoryId": {
      "type": "string",
      "description": "The directory Id for this user."
    },
    "directoryUuid": {
      "type": "string",
      "description": "The directory uuid for this user."
    },
    "searchBaseId": {
      "type": "string",
      "description": "The searchBase Id for this user."
    },
    "status": {
      "type": "string",
      "description": "The outcome of the synchronization.",
      "enum": [
        "CONVERTED",
        "CREATED",
        "DELETED",
        "LOCALIZED_ENABLED",
        "LOCALIZED_DISABLED",
        "UPDATED"
      ]
    },
    "userId": {
      "type": "string",
      "description": "The user Id for this user."
    },
    "uuid": {
      "type": "string",
      "description": "The uuid for this user."
    }
  },
  "description": "The values associated with a synchronized user.  This structure is returned when synchronizing a user.",
  "title": "SyncUser"
}
```

### 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": [
      "USERS:EDIT"
    ]
  }
]
```