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

# Users

The Users API allows you to create and manage care team member records, assign territorial coverage, and update security policies.

**Base path:** `/{tenantName}/{instanceName}/users`

***

## Endpoints

### POST Create User Record

**POST** `/{tenantName}/{instanceName}/users`

Creates a new care team user in Welkin.

#### Request Body

| Field       | Type   | Required | Description                              |
| ----------- | ------ | -------- | ---------------------------------------- |
| `firstName` | string | Yes      | User's first name                        |
| `lastName`  | string | Yes      | User's last name                         |
| `email`     | string | Yes      | Login email address                      |
| `username`  | string | Yes      | Unique username                          |
| `role`      | string | No       | Assigned role from Designer              |
| `timezone`  | string | No       | IANA timezone (e.g., `America/New_York`) |

#### Example Request

```http
POST /acme-health/live/users
Authorization: Bearer <token>
Content-Type: application/json

{
  "firstName": "Alex",
  "lastName": "Johnson",
  "email": "alex.johnson@acme-health.com",
  "username": "alex.johnson",
  "role": "care-coordinator",
  "timezone": "America/Chicago"
}
```

***

### GET Read Users Records

**GET** `/{tenantName}/{instanceName}/users`

Returns a paginated list of all care team users in the instance.

#### Query Parameters

| Parameter | Type    | Description                      |
| --------- | ------- | -------------------------------- |
| `page`    | integer | Page number (default: `0`)       |
| `size`    | integer | Results per page (default: `20`) |
| `search`  | string  | Filter by name or email          |

***

### GET Read User Record

**GET** `/{tenantName}/{instanceName}/users/{userId}`

Returns a single user record by UUID.

#### Path Parameters

| Parameter | Type   | Required | Description      |
| --------- | ------ | -------- | ---------------- |
| `userId`  | string | Yes      | Welkin user UUID |

***

### PATCH Update User Record

**PATCH** `/{tenantName}/{instanceName}/users/{userId}`

Partially updates a user record. Only include fields to change.

***

### PUT Update Security Policies

**PUT** `/{tenantName}/{instanceName}/users/{userId}/policies`

Replaces the full set of security policies assigned to a user.

#### Request Body

| Field      | Type  | Required | Description                  |
| ---------- | ----- | -------- | ---------------------------- |
| `policies` | array | Yes      | Array of policy name strings |

#### Example Request

```http
PUT /acme-health/live/users/user-uuid/policies
Authorization: Bearer <token>
Content-Type: application/json

{
  "policies": ["read-patients", "write-encounters", "read-assessments"]
}
```

***

## Users — Regions and Territories

Users can be assigned to geographic regions and territories to control patient routing and assignment.

### GET Get User Territories

**GET** `/{tenantName}/{instanceName}/users/{userId}/territories`

### PATCH Update User Territories

**PATCH** `/{tenantName}/{instanceName}/users/{userId}/territories`


---

# 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.welkinhealth.com/developer-and-integration-guide/api-reference/users.md?ask=<question>
```

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.