> 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-user-groups.md).

# External User Groups

## GET /api/v1/external-user-groups

> Retrieves multiple external user groups.

```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-user-groups":{"get":{"description":"Retrieves multiple external user groups.","tags":["External User Groups"],"parameters":[{"schema":{"type":"string"},"required":false,"name":"externalId","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":"ids","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","minLength":1,"description":"Search term to filter external user groups by name or external ids."},"required":false,"description":"Search term to filter external user groups by name or external ids.","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":"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 user groups 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"},"externalId":{"type":"string","nullable":true,"minLength":3,"maxLength":250,"description":"External reference in the integrated system."},"name":{"type":"string","nullable":true,"minLength":3,"maxLength":50,"description":"The display name of the external user group."},"tierId":{"type":"string","nullable":true,"format":"uuid","description":"The tier associated with the external user group."},"workspaceId":{"type":"string","format":"uuid","description":"The workspace that owns the external user group."}},"required":["createdAt","id","updatedAt","externalId","name","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."}}}}}}}}}
```

## POST /api/v1/external-user-groups

> Creates a new external user group.

```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-user-groups":{"post":{"description":"Creates a new external user group.","tags":["External User Groups"],"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":{"externalId":{"type":"string","nullable":true,"minLength":3,"maxLength":250,"description":"External reference in the integrated system."},"name":{"type":"string","nullable":true,"minLength":3,"maxLength":50,"description":"The display name of the external user group."},"tierId":{"type":"string","nullable":true,"format":"uuid","description":"The tier associated with the external user group."}},"required":["externalId","name","tierId"]}}}},"responses":{"200":{"description":"The external user group was created.","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"},"externalId":{"type":"string","nullable":true,"minLength":3,"maxLength":250,"description":"External reference in the integrated system."},"name":{"type":"string","nullable":true,"minLength":3,"maxLength":50,"description":"The display name of the external user group."},"tierId":{"type":"string","nullable":true,"format":"uuid","description":"The tier associated with the external user group."},"workspaceId":{"type":"string","format":"uuid","description":"The workspace that owns the external user group."}},"required":["createdAt","id","updatedAt","externalId","name","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":"Tier 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."}}}},"409":{"description":"External user group external id already exists in this workspace.","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-user-groups/{id}

> Retrieves an external user group.

```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-user-groups/{id}":{"get":{"description":"Retrieves an external user group.","tags":["External User Groups"],"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 group.","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"},"externalId":{"type":"string","nullable":true,"minLength":3,"maxLength":250,"description":"External reference in the integrated system."},"name":{"type":"string","nullable":true,"minLength":3,"maxLength":50,"description":"The display name of the external user group."},"tierId":{"type":"string","nullable":true,"format":"uuid","description":"The tier associated with the external user group."},"workspaceId":{"type":"string","format":"uuid","description":"The workspace that owns the external user group."}},"required":["createdAt","id","updatedAt","externalId","name","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 group 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."}}}}}}}}}
```

## DELETE /api/v1/external-user-groups/{id}

> Removes an external user group.

```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-user-groups/{id}":{"delete":{"description":"Removes an external user group.","tags":["External User Groups"],"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":"The external user group was removed.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"An informative message for a call that has no effective result to be returned."}},"required":["message"]}}}},"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 group 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-user-groups/{id}

> Updates an external user group.

```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-user-groups/{id}":{"patch":{"description":"Updates an external user group.","tags":["External User Groups"],"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":{"externalId":{"type":"string","nullable":true,"minLength":3,"maxLength":250,"description":"External reference in the integrated system."},"name":{"type":"string","nullable":true,"minLength":3,"maxLength":50,"description":"The display name of the external user group."},"tierId":{"type":"string","nullable":true,"format":"uuid","description":"The tier associated with the external user group."}}}}}},"responses":{"200":{"description":"The external user group 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"},"externalId":{"type":"string","nullable":true,"minLength":3,"maxLength":250,"description":"External reference in the integrated system."},"name":{"type":"string","nullable":true,"minLength":3,"maxLength":50,"description":"The display name of the external user group."},"tierId":{"type":"string","nullable":true,"format":"uuid","description":"The tier associated with the external user group."},"workspaceId":{"type":"string","format":"uuid","description":"The workspace that owns the external user group."}},"required":["createdAt","id","updatedAt","externalId","name","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 group or tier 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."}}}},"409":{"description":"External user group external id already exists in this workspace.","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."}}}}}}}}}
```