> For the complete documentation index, see [llms.txt](https://docs.riskbase.uk/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.riskbase.uk/riskbase-docs/api/users-and-teams.md).
# Users & Teams
## GET /users
> Get Users
```json
{"openapi":"3.1.1","info":{"title":"RiskBase API","version":"0.0.1"},"tags":[{"name":"Users & Teams","description":""}],"servers":[{"url":"https://api3.riskbase.uk"}],"security":[{"Bearer Authentication":[]}],"components":{"securitySchemes":{"Bearer Authentication":{"type":"http","scheme":"bearer","description":"`Authorization: Bearer {AuthorizationToken}`"}}},"paths":{"/users":{"get":{"tags":["Users & Teams"],"summary":"Get Users","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":1000,"default":1000},"in":"query","name":"limit"},{"schema":{"type":"integer","default":1},"in":"query","name":"page"},{"schema":{"type":"string","format":"UID"},"in":"query","name":"account","description":"Comma separated user IDs"},{"schema":{"type":"string","format":"email"},"in":"query","name":"email","description":"Comma separated emails"},{"schema":{"type":"string","format":"string"},"in":"query","name":"reference","description":"Comma separated RiskBase references"},{"schema":{"type":"string","format":"string"},"in":"query","name":"customReference","description":"Comma separated RiskBase custom references"}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"total":{"type":"integer"},"users":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"UID"},"email":{"type":"email"},"forename":{"type":"string"},"surname":{"type":"string"},"teams":{"type":"array","description":"An array of team IDs the user is a member of","items":{"type":"string","format":"UID"}},"provisionType":{"type":"enum","enum":["riskbase","scim"],"description":"Describes whether the account was provisioned via RiskBase (riskbase) or the SCIM API (scim)"}}}}}}}}}}}}}}
```
## Create or Link User
> This POST request is used to create a new user. If a user already exists, they will be added to the organisation. The authentication type will be set to passwordless by default.
```json
{"openapi":"3.1.1","info":{"title":"RiskBase API","version":"0.0.1"},"tags":[{"name":"Users & Teams","description":""}],"servers":[{"url":"https://api3.riskbase.uk"}],"security":[{"Bearer Authentication":[]}],"components":{"securitySchemes":{"Bearer Authentication":{"type":"http","scheme":"bearer","description":"`Authorization: Bearer {AuthorizationToken}`"}}},"paths":{"/users":{"post":{"tags":["Users & Teams"],"summary":"Create or Link User","description":"This POST request is used to create a new user. If a user already exists, they will be added to the organisation. The authentication type will be set to passwordless by default.\n","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["email","forename","surname"],"properties":{"email":{"type":"string","format":"email","description":"The user's email address"},"forename":{"type":"string"},"surname":{"type":"string"},"customReference":{"type":"string"},"roles":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"}}}},"active":{"type":"boolean","default":false}}}}}},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"id":{"type":"string","format":"UID"},"usercreated":{"type":"boolean","description":"Indicates whether the operation created a new user within an organisation."},"userLinked":{"type":"boolean","description":"Indicates whether the operation linked an existing user to the organisation rather than creating a new user."}}}}}},"400":{"content":{"application/json":{"schema":{"oneOf":[{"title":"UserCreateFailedToLink","properties":{"code":{"type":"string","enum":["UserCreateFailedToLink"]}}},{"title":"UserCreateEmailRequired","properties":{"code":{"type":"string","enum":["UserCreateEmailRequired"]}}},{"title":"UserCreateEmailFormatInvalid","properties":{"code":{"type":"string","enum":["UserCreateEmailFormatInvalid"]}}},{"title":"UserCreateFailed","properties":{"code":{"type":"string","enum":["UserCreateFailed"]}}}]}}}}}}}}}
```
## GET /teams
> Get Teams
```json
{"openapi":"3.1.1","info":{"title":"RiskBase API","version":"0.0.1"},"tags":[{"name":"Users & Teams","description":""}],"servers":[{"url":"https://api3.riskbase.uk"}],"security":[{"Bearer Authentication":[]}],"components":{"securitySchemes":{"Bearer Authentication":{"type":"http","scheme":"bearer","description":"`Authorization: Bearer {AuthorizationToken}`"}}},"paths":{"/teams":{"get":{"tags":["Users & Teams"],"summary":"Get Teams","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":1000,"default":1000},"in":"query","name":"limit"},{"schema":{"type":"integer","default":1},"in":"query","name":"page"},{"schema":{"type":"string","format":"UID"},"in":"query","name":"team","description":"Comma separated teams IDs"}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"total":{"type":"integer"},"teams":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"UID"},"name":{"type":"string"},"users":{"type":"array","description":"An array of member user IDs","items":{"type":"string","format":"UID"}}}}}}}}}}}}}}}
```
## Add Users to Team
> Add users to a team\
> \- Invalid user IDs are silently ignored.\
> \- Triggers the \`team\` webhook.
```json
{"openapi":"3.1.1","info":{"title":"RiskBase API","version":"0.0.1"},"tags":[{"name":"Users & Teams","description":""}],"servers":[{"url":"https://api3.riskbase.uk"}],"security":[{"Bearer Authentication":[]}],"components":{"securitySchemes":{"Bearer Authentication":{"type":"http","scheme":"bearer","description":"`Authorization: Bearer {AuthorizationToken}`"}}},"paths":{"/teams/{teamId}/users/add":{"patch":{"tags":["Users & Teams"],"summary":"Add Users to Team","description":"Add users to a team\n- Invalid user IDs are silently ignored.\n- Triggers the `team` webhook.\n","parameters":[{"schema":{"type":"string","format":"UID"},"in":"path","name":"teamId","required":true}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["users"],"properties":{"users":{"type":"array","description":"User IDs to add to the team","items":{"type":"string","format":"UID"}},"skipWebhook":{"type":"boolean","default":false}}}}}},"responses":{"204":{"content":"application/json"}}}}}}
```
## Remove Users from Team
> Remove users from a team.\
> \- Users are also removed as responsible for the team. (See \`Get Property Team Users\`.)\
> \- Invalid user IDs are silently ignored.\
> \- Triggers the \`team\` webhook.
```json
{"openapi":"3.1.1","info":{"title":"RiskBase API","version":"0.0.1"},"tags":[{"name":"Users & Teams","description":""}],"servers":[{"url":"https://api3.riskbase.uk"}],"security":[{"Bearer Authentication":[]}],"components":{"securitySchemes":{"Bearer Authentication":{"type":"http","scheme":"bearer","description":"`Authorization: Bearer {AuthorizationToken}`"}}},"paths":{"/teams/{teamId}/users/remove":{"patch":{"tags":["Users & Teams"],"summary":"Remove Users from Team","description":"Remove users from a team.\n- Users are also removed as responsible for the team. (See `Get Property Team Users`.)\n- Invalid user IDs are silently ignored.\n- Triggers the `team` webhook.\n","parameters":[{"schema":{"type":"string","format":"UID"},"in":"path","name":"teamId","required":true}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["users"],"properties":{"users":{"type":"array","description":"User IDs to remove from the team","items":{"type":"string","format":"UID"}},"skipWebhook":{"type":"boolean","default":false}}}}}},"responses":{"204":{"content":"application/json"}}}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.riskbase.uk/riskbase-docs/api/users-and-teams.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.