> For the complete documentation index, see [llms.txt](https://docs.zaia.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zaia.app/documentation/api-reference-alpha/reference/external-users.md).

# External Users

## POST /api/v1/external-users/authenticate

> Authenticates an external user.

```json
{"openapi":"3.1.0","info":{"title":"Public API","version":"1.0.0"},"servers":[{"description":"API Server","url":"https://api.endless.zaia.app"}],"paths":{"/api/v1/external-users/authenticate":{"post":{"description":"Authenticates an external user.","tags":["External Users"],"parameters":[{"schema":{"type":"string","description":"The API key to use for authentication. Can be created in the api keys section on the workspace settings page."},"required":true,"description":"The API key to use for authentication. Can be created in the api keys section on the workspace settings page.","name":"authorization","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"channelId":{"type":"string","format":"uuid","description":"A UUID v4 string that identifies an entity."},"externalId":{"type":"string","nullable":true},"id":{"type":"string","nullable":true,"format":"uuid","description":"A UUID v4 string that identifies an entity."},"identifier":{"type":"string","nullable":true}},"required":["channelId","externalId","id","identifier"]}}}},"responses":{"200":{"description":"The external user was authenticated and access token generated.","content":{"application/json":{"schema":{"type":"object","properties":{"createdAt":{"type":"string","format":"date-time"},"id":{"type":"string","format":"uuid","description":"A UUID v4 string that identifies an entity."},"updatedAt":{"type":"string","format":"date-time"},"blocked":{"type":"boolean","description":"Whether the external user is blocked."},"channelId":{"type":"string","format":"uuid","description":"The ID of the channel associated with the external user."},"externalId":{"type":"string","nullable":true,"minLength":3,"maxLength":250,"description":"External reference in the integrated system."},"externalUserGroupId":{"type":"string","nullable":true,"format":"uuid","description":"The ID of the external user group associated with the external user."},"identifier":{"type":"string","nullable":true,"description":"A unique identifier of the external user (usernames, emails, phone numbers and etc)."},"name":{"type":"string","nullable":true,"minLength":3,"maxLength":50,"description":"The display name of the external user."},"superIdentityId":{"type":"string","format":"uuid","description":"The ID of the super identity associated with the external user."},"tierId":{"type":"string","nullable":true,"format":"uuid","description":"The ID of the tier associated with the external user."},"workspaceId":{"type":"string","format":"uuid","description":"The ID of the workspace associated with the external user."},"accessToken":{"type":"string"}},"required":["createdAt","id","updatedAt","blocked","channelId","externalId","externalUserGroupId","identifier","name","superIdentityId","tierId","workspaceId","accessToken"]}}}},"400":{"description":"Invalid data provided.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"The error code."},"cta":{"type":"object","properties":{"type":{"type":"string","enum":["support-contact"]},"url":{"type":"string","format":"uri"}},"required":["type","url"],"description":"The error call-to-action."},"feedback":{"type":"object","properties":{"enUs":{"type":"string"},"esEs":{"type":"string"},"ptBr":{"type":"string"}},"description":"The error feedback."},"message":{"type":"string","description":"The error message."},"name":{"type":"string","description":"The error name."}},"required":["feedback","message","name"],"description":"The description of a known exception."}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"The error code."},"cta":{"type":"object","properties":{"type":{"type":"string","enum":["support-contact"]},"url":{"type":"string","format":"uri"}},"required":["type","url"],"description":"The error call-to-action."},"feedback":{"type":"object","properties":{"enUs":{"type":"string"},"esEs":{"type":"string"},"ptBr":{"type":"string"}},"description":"The error feedback."},"message":{"type":"string","description":"The error message."},"name":{"type":"string","description":"The error name."}},"required":["feedback","message","name"],"description":"The description of a known exception."}}}},"404":{"description":"Channel not found.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"The error code."},"cta":{"type":"object","properties":{"type":{"type":"string","enum":["support-contact"]},"url":{"type":"string","format":"uri"}},"required":["type","url"],"description":"The error call-to-action."},"feedback":{"type":"object","properties":{"enUs":{"type":"string"},"esEs":{"type":"string"},"ptBr":{"type":"string"}},"description":"The error feedback."},"message":{"type":"string","description":"The error message."},"name":{"type":"string","description":"The error name."}},"required":["feedback","message","name"],"description":"The description of a known exception."}}}}}}}}}
```

## GET /api/v1/external-users

> Retrieves multiple external users.

```json
{"openapi":"3.1.0","info":{"title":"Public API","version":"1.0.0"},"servers":[{"description":"API Server","url":"https://api.endless.zaia.app"}],"paths":{"/api/v1/external-users":{"get":{"description":"Retrieves multiple external users.","tags":["External Users"],"parameters":[{"schema":{"anyOf":[{"type":"array","items":{"type":"string","format":"uuid","description":"A UUID v4 string that identifies an entity."}},{"type":"string","format":"uuid","description":"A UUID v4 string that identifies an entity."}],"default":[]},"required":false,"name":"channelIds","in":"query"},{"schema":{"anyOf":[{"type":"array","items":{"type":"string","format":"uuid","description":"A UUID v4 string that identifies an entity."}},{"type":"string","format":"uuid","description":"A UUID v4 string that identifies an entity."}],"default":[]},"required":false,"name":"externalUserGroupIds","in":"query"},{"schema":{"type":"number","minimum":1,"default":1,"description":"The page number."},"required":false,"description":"The page number.","name":"pageNumber","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":100,"default":10,"description":"The page size."},"required":false,"description":"The page size.","name":"pageSize","in":"query"},{"schema":{"type":"string"},"required":false,"name":"search","in":"query"},{"schema":{"anyOf":[{"type":"array","items":{"type":"string","format":"uuid","description":"A UUID v4 string that identifies an entity."}},{"type":"string","format":"uuid","description":"A UUID v4 string that identifies an entity."}],"default":[]},"required":false,"name":"superIdentityIds","in":"query"},{"schema":{"anyOf":[{"type":"array","items":{"type":"string","format":"uuid","description":"A UUID v4 string that identifies an entity."}},{"type":"string","format":"uuid","description":"A UUID v4 string that identifies an entity."}],"default":[]},"required":false,"name":"tierIds","in":"query"},{"schema":{"type":"string","description":"The API key to use for authentication. Can be created in the api keys section on the workspace settings page."},"required":true,"description":"The API key to use for authentication. Can be created in the api keys section on the workspace settings page.","name":"authorization","in":"header"}],"responses":{"200":{"description":"Retrieves all external users for the workspace.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"createdAt":{"type":"string","format":"date-time"},"id":{"type":"string","format":"uuid","description":"A UUID v4 string that identifies an entity."},"updatedAt":{"type":"string","format":"date-time"},"blocked":{"type":"boolean","description":"Whether the external user is blocked."},"channelId":{"type":"string","format":"uuid","description":"The ID of the channel associated with the external user."},"externalId":{"type":"string","nullable":true,"minLength":3,"maxLength":250,"description":"External reference in the integrated system."},"externalUserGroupId":{"type":"string","nullable":true,"format":"uuid","description":"The ID of the external user group associated with the external user."},"identifier":{"type":"string","nullable":true,"description":"A unique identifier of the external user (usernames, emails, phone numbers and etc)."},"name":{"type":"string","nullable":true,"minLength":3,"maxLength":50,"description":"The display name of the external user."},"superIdentityId":{"type":"string","format":"uuid","description":"The ID of the super identity associated with the external user."},"tierId":{"type":"string","nullable":true,"format":"uuid","description":"The ID of the tier associated with the external user."},"workspaceId":{"type":"string","format":"uuid","description":"The ID of the workspace associated with the external user."}},"required":["createdAt","id","updatedAt","blocked","channelId","externalId","externalUserGroupId","identifier","name","superIdentityId","tierId","workspaceId"]}}}}},"400":{"description":"Bad Request.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"The error code."},"cta":{"type":"object","properties":{"type":{"type":"string","enum":["support-contact"]},"url":{"type":"string","format":"uri"}},"required":["type","url"],"description":"The error call-to-action."},"feedback":{"type":"object","properties":{"enUs":{"type":"string"},"esEs":{"type":"string"},"ptBr":{"type":"string"}},"description":"The error feedback."},"message":{"type":"string","description":"The error message."},"name":{"type":"string","description":"The error name."}},"required":["feedback","message","name"],"description":"The description of a known exception."}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"The error code."},"cta":{"type":"object","properties":{"type":{"type":"string","enum":["support-contact"]},"url":{"type":"string","format":"uri"}},"required":["type","url"],"description":"The error call-to-action."},"feedback":{"type":"object","properties":{"enUs":{"type":"string"},"esEs":{"type":"string"},"ptBr":{"type":"string"}},"description":"The error feedback."},"message":{"type":"string","description":"The error message."},"name":{"type":"string","description":"The error name."}},"required":["feedback","message","name"],"description":"The description of a known exception."}}}}}}}}}
```

## POST /api/v1/external-users

> Creates a new external user.

```json
{"openapi":"3.1.0","info":{"title":"Public API","version":"1.0.0"},"servers":[{"description":"API Server","url":"https://api.endless.zaia.app"}],"paths":{"/api/v1/external-users":{"post":{"description":"Creates a new external user.","tags":["External Users"],"parameters":[{"schema":{"type":"string","description":"The API key to use for authentication. Can be created in the api keys section on the workspace settings page."},"required":true,"description":"The API key to use for authentication. Can be created in the api keys section on the workspace settings page.","name":"authorization","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"channelId":{"type":"string","format":"uuid","description":"The ID of the channel associated with the external user."},"externalId":{"type":"string","nullable":true,"minLength":3,"maxLength":250,"description":"External reference in the integrated system."},"externalUserGroupId":{"type":"string","nullable":true,"format":"uuid","description":"The ID of the external user group associated with the external user."},"identifier":{"type":"string","nullable":true,"description":"A unique identifier of the external user (usernames, emails, phone numbers and etc)."},"name":{"type":"string","nullable":true,"minLength":3,"maxLength":50,"description":"The display name of the external user."},"tierId":{"type":"string","nullable":true,"format":"uuid","description":"The ID of the tier associated with the external user."}},"required":["channelId","externalId","externalUserGroupId","identifier","name","tierId"]}}}},"responses":{"200":{"description":"The external user was created and access token generated.","content":{"application/json":{"schema":{"type":"object","properties":{"createdAt":{"type":"string","format":"date-time"},"id":{"type":"string","format":"uuid","description":"A UUID v4 string that identifies an entity."},"updatedAt":{"type":"string","format":"date-time"},"blocked":{"type":"boolean","description":"Whether the external user is blocked."},"channelId":{"type":"string","format":"uuid","description":"The ID of the channel associated with the external user."},"externalId":{"type":"string","nullable":true,"minLength":3,"maxLength":250,"description":"External reference in the integrated system."},"externalUserGroupId":{"type":"string","nullable":true,"format":"uuid","description":"The ID of the external user group associated with the external user."},"identifier":{"type":"string","nullable":true,"description":"A unique identifier of the external user (usernames, emails, phone numbers and etc)."},"name":{"type":"string","nullable":true,"minLength":3,"maxLength":50,"description":"The display name of the external user."},"superIdentityId":{"type":"string","format":"uuid","description":"The ID of the super identity associated with the external user."},"tierId":{"type":"string","nullable":true,"format":"uuid","description":"The ID of the tier associated with the external user."},"workspaceId":{"type":"string","format":"uuid","description":"The ID of the workspace associated with the external user."}},"required":["createdAt","id","updatedAt","blocked","channelId","externalId","externalUserGroupId","identifier","name","superIdentityId","tierId","workspaceId"]}}}},"400":{"description":"Invalid data provided.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"The error code."},"cta":{"type":"object","properties":{"type":{"type":"string","enum":["support-contact"]},"url":{"type":"string","format":"uri"}},"required":["type","url"],"description":"The error call-to-action."},"feedback":{"type":"object","properties":{"enUs":{"type":"string"},"esEs":{"type":"string"},"ptBr":{"type":"string"}},"description":"The error feedback."},"message":{"type":"string","description":"The error message."},"name":{"type":"string","description":"The error name."}},"required":["feedback","message","name"],"description":"The description of a known exception."}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"The error code."},"cta":{"type":"object","properties":{"type":{"type":"string","enum":["support-contact"]},"url":{"type":"string","format":"uri"}},"required":["type","url"],"description":"The error call-to-action."},"feedback":{"type":"object","properties":{"enUs":{"type":"string"},"esEs":{"type":"string"},"ptBr":{"type":"string"}},"description":"The error feedback."},"message":{"type":"string","description":"The error message."},"name":{"type":"string","description":"The error name."}},"required":["feedback","message","name"],"description":"The description of a known exception."}}}},"404":{"description":"Channel not found.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"The error code."},"cta":{"type":"object","properties":{"type":{"type":"string","enum":["support-contact"]},"url":{"type":"string","format":"uri"}},"required":["type","url"],"description":"The error call-to-action."},"feedback":{"type":"object","properties":{"enUs":{"type":"string"},"esEs":{"type":"string"},"ptBr":{"type":"string"}},"description":"The error feedback."},"message":{"type":"string","description":"The error message."},"name":{"type":"string","description":"The error name."}},"required":["feedback","message","name"],"description":"The description of a known exception."}}}}}}}}}
```

## GET /api/v1/external-users/{id}

> Retrieves an external user.

```json
{"openapi":"3.1.0","info":{"title":"Public API","version":"1.0.0"},"servers":[{"description":"API Server","url":"https://api.endless.zaia.app"}],"paths":{"/api/v1/external-users/{id}":{"get":{"description":"Retrieves an external user.","tags":["External Users"],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A UUID v4 string that identifies an entity."},"required":true,"description":"A UUID v4 string that identifies an entity.","name":"id","in":"path"},{"schema":{"type":"string","description":"The API key to use for authentication. Can be created in the api keys section on the workspace settings page."},"required":true,"description":"The API key to use for authentication. Can be created in the api keys section on the workspace settings page.","name":"authorization","in":"header"}],"responses":{"200":{"description":"Retrieves an external user.","content":{"application/json":{"schema":{"type":"object","properties":{"createdAt":{"type":"string","format":"date-time"},"id":{"type":"string","format":"uuid","description":"A UUID v4 string that identifies an entity."},"updatedAt":{"type":"string","format":"date-time"},"blocked":{"type":"boolean","description":"Whether the external user is blocked."},"channelId":{"type":"string","format":"uuid","description":"The ID of the channel associated with the external user."},"externalId":{"type":"string","nullable":true,"minLength":3,"maxLength":250,"description":"External reference in the integrated system."},"externalUserGroupId":{"type":"string","nullable":true,"format":"uuid","description":"The ID of the external user group associated with the external user."},"identifier":{"type":"string","nullable":true,"description":"A unique identifier of the external user (usernames, emails, phone numbers and etc)."},"name":{"type":"string","nullable":true,"minLength":3,"maxLength":50,"description":"The display name of the external user."},"superIdentityId":{"type":"string","format":"uuid","description":"The ID of the super identity associated with the external user."},"tierId":{"type":"string","nullable":true,"format":"uuid","description":"The ID of the tier associated with the external user."},"workspaceId":{"type":"string","format":"uuid","description":"The ID of the workspace associated with the external user."}},"required":["createdAt","id","updatedAt","blocked","channelId","externalId","externalUserGroupId","identifier","name","superIdentityId","tierId","workspaceId"]}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"The error code."},"cta":{"type":"object","properties":{"type":{"type":"string","enum":["support-contact"]},"url":{"type":"string","format":"uri"}},"required":["type","url"],"description":"The error call-to-action."},"feedback":{"type":"object","properties":{"enUs":{"type":"string"},"esEs":{"type":"string"},"ptBr":{"type":"string"}},"description":"The error feedback."},"message":{"type":"string","description":"The error message."},"name":{"type":"string","description":"The error name."}},"required":["feedback","message","name"],"description":"The description of a known exception."}}}},"404":{"description":"External user not found.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"The error code."},"cta":{"type":"object","properties":{"type":{"type":"string","enum":["support-contact"]},"url":{"type":"string","format":"uri"}},"required":["type","url"],"description":"The error call-to-action."},"feedback":{"type":"object","properties":{"enUs":{"type":"string"},"esEs":{"type":"string"},"ptBr":{"type":"string"}},"description":"The error feedback."},"message":{"type":"string","description":"The error message."},"name":{"type":"string","description":"The error name."}},"required":["feedback","message","name"],"description":"The description of a known exception."}}}}}}}}}
```

## PATCH /api/v1/external-users/{id}

> Updates an external user.

```json
{"openapi":"3.1.0","info":{"title":"Public API","version":"1.0.0"},"servers":[{"description":"API Server","url":"https://api.endless.zaia.app"}],"paths":{"/api/v1/external-users/{id}":{"patch":{"description":"Updates an external user.","tags":["External Users"],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A UUID v4 string that identifies an entity."},"required":true,"description":"A UUID v4 string that identifies an entity.","name":"id","in":"path"},{"schema":{"type":"string","description":"The API key to use for authentication. Can be created in the api keys section on the workspace settings page."},"required":true,"description":"The API key to use for authentication. Can be created in the api keys section on the workspace settings page.","name":"authorization","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"blocked":{"type":"boolean","description":"Whether the external user is blocked."},"externalId":{"type":"string","nullable":true,"minLength":3,"maxLength":250,"description":"External reference in the integrated system."},"externalUserGroupId":{"type":"string","nullable":true,"format":"uuid","description":"The ID of the external user group associated with the external user."},"identifier":{"type":"string","nullable":true,"description":"A unique identifier of the external user (usernames, emails, phone numbers and etc)."},"name":{"type":"string","nullable":true,"minLength":3,"maxLength":50,"description":"The display name of the external user."},"tierId":{"type":"string","nullable":true,"format":"uuid","description":"The ID of the tier associated with the external user."}}}}}},"responses":{"200":{"description":"The external user was updated.","content":{"application/json":{"schema":{"type":"object","properties":{"createdAt":{"type":"string","format":"date-time"},"id":{"type":"string","format":"uuid","description":"A UUID v4 string that identifies an entity."},"updatedAt":{"type":"string","format":"date-time"},"blocked":{"type":"boolean","description":"Whether the external user is blocked."},"channelId":{"type":"string","format":"uuid","description":"The ID of the channel associated with the external user."},"externalId":{"type":"string","nullable":true,"minLength":3,"maxLength":250,"description":"External reference in the integrated system."},"externalUserGroupId":{"type":"string","nullable":true,"format":"uuid","description":"The ID of the external user group associated with the external user."},"identifier":{"type":"string","nullable":true,"description":"A unique identifier of the external user (usernames, emails, phone numbers and etc)."},"name":{"type":"string","nullable":true,"minLength":3,"maxLength":50,"description":"The display name of the external user."},"superIdentityId":{"type":"string","format":"uuid","description":"The ID of the super identity associated with the external user."},"tierId":{"type":"string","nullable":true,"format":"uuid","description":"The ID of the tier associated with the external user."},"workspaceId":{"type":"string","format":"uuid","description":"The ID of the workspace associated with the external user."}},"required":["createdAt","id","updatedAt","blocked","channelId","externalId","externalUserGroupId","identifier","name","superIdentityId","tierId","workspaceId"]}}}},"400":{"description":"Invalid data provided.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"The error code."},"cta":{"type":"object","properties":{"type":{"type":"string","enum":["support-contact"]},"url":{"type":"string","format":"uri"}},"required":["type","url"],"description":"The error call-to-action."},"feedback":{"type":"object","properties":{"enUs":{"type":"string"},"esEs":{"type":"string"},"ptBr":{"type":"string"}},"description":"The error feedback."},"message":{"type":"string","description":"The error message."},"name":{"type":"string","description":"The error name."}},"required":["feedback","message","name"],"description":"The description of a known exception."}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"The error code."},"cta":{"type":"object","properties":{"type":{"type":"string","enum":["support-contact"]},"url":{"type":"string","format":"uri"}},"required":["type","url"],"description":"The error call-to-action."},"feedback":{"type":"object","properties":{"enUs":{"type":"string"},"esEs":{"type":"string"},"ptBr":{"type":"string"}},"description":"The error feedback."},"message":{"type":"string","description":"The error message."},"name":{"type":"string","description":"The error name."}},"required":["feedback","message","name"],"description":"The description of a known exception."}}}},"404":{"description":"External user not found.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"The error code."},"cta":{"type":"object","properties":{"type":{"type":"string","enum":["support-contact"]},"url":{"type":"string","format":"uri"}},"required":["type","url"],"description":"The error call-to-action."},"feedback":{"type":"object","properties":{"enUs":{"type":"string"},"esEs":{"type":"string"},"ptBr":{"type":"string"}},"description":"The error feedback."},"message":{"type":"string","description":"The error message."},"name":{"type":"string","description":"The error name."}},"required":["feedback","message","name"],"description":"The description of a known exception."}}}}}}}}}
```