# 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: 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.