Users

Manage care team users, territories, regions, and security policies.

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

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

{
  "firstName": "Alex",
  "lastName": "Johnson",
  "email": "[e-mail]",
  "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

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