User Management
Manage users within your client organization.
Authentication
Requires a Client token with scopes:
user:read— For GET endpointsuser:write— For POST/PUT/DELETE endpoints
Endpoints
List Users
http
GET /ext/latest/users
Authorization: Bearer {token}Query Parameters:
externalId(optional) — Filter by external IDfirstName(optional) — Filter by first namelastName(optional) — Filter by last nameemail(optional) — Filter by emaillimit(optional) — Page size (default: 10, max: 100)offset(optional) — Page offset (default: 0)
Response:
json
{
"data": [
{
"userId": "019d0716-6a88-70af-9ef4-50c1cc2bda86",
"clientId": "a587f055-12ff-4009-a4b2-6300f665f35e",
"username": "jdoe@acmemedical.com",
"firstName": "Jane",
"lastName": "Doe",
"email": "jdoe@acmemedical.com",
"title": "Nurse Practitioner",
"phone": "555-123-4567",
"externalId": "EXT-USER-001",
"active": true
}
],
"limit": 10,
"offset": 0,
"hasMore": false
}Get User
http
GET /ext/latest/users/{userId}
Authorization: Bearer {token}Response:
json
{
"data": { ... }
}Create User
http
POST /ext/latest/users
Content-Type: application/json
Authorization: Bearer {token}Request Body:
json
{
"username": "jdoe@acmemedical.com",
"firstName": "Jane",
"lastName": "Doe",
"email": "jdoe@acmemedical.com",
"title": "Nurse Practitioner",
"phone": "555-123-4567",
"externalId": "EXT-USER-001"
}Response (201 Created):
json
{
"data": { ... }
}Cognito Provisioning
Creating a user also provisions a Cognito account. If a Cognito user with the same email already exists, a 409 RESOURCE_EXISTS error is returned.
Update User
http
PUT /ext/latest/users/{userId}
Content-Type: application/json
Authorization: Bearer {token}Request Body: (all fields optional)
json
{
"firstName": "Janet",
"lastName": "Smith",
"title": "Senior Nurse Practitioner",
"phone": "555-123-4568"
}Response:
json
{
"data": { ... }
}Delete User
http
DELETE /ext/latest/users/{userId}
Authorization: Bearer {token}Response (204 No Content): (no body)
User Object Fields
| Field | Type | Create | Update | Description |
|---|---|---|---|---|
userId | string | — | — | System-generated UUID (read-only) |
clientId | string | — | — | Owning client ID (read-only) |
username | string | required | optional | Username (typically email) |
firstName | string | required | optional | First name |
lastName | string | required | optional | Last name |
email | string | required | optional | Email address |
title | string | optional | optional | Job title (nullable) |
phone | string | optional | optional | Phone number (nullable) |
externalId | string | optional | optional | External system identifier (nullable) |
active | boolean | — | — | Active status (read-only; use DELETE to deactivate) |
Examples
Node.js
javascript
async function createUser(token, userData) {
const response = await fetch('https://api.vivliohealth.io/ext/latest/users', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Authorization: `Bearer ${token}`
},
body: JSON.stringify(userData)
});
if (!response.ok) {
const error = await response.json();
throw new Error(`Failed to create user: ${error.error.message}`);
}
return response.json();
}
async function listUsers(token, filters = {}) {
const params = new URLSearchParams();
Object.entries(filters).forEach(([key, value]) => {
if (value) params.append(key, value);
});
const response = await fetch(
`https://api.vivliohealth.io/ext/latest/users?${params}`,
{ headers: { Authorization: `Bearer ${token}` } }
);
return response.json();
}Python
python
import requests
def create_user(token, user_data):
response = requests.post(
'https://api.vivliohealth.io/ext/latest/users',
headers={
'Content-Type': 'application/json',
'Authorization': f'Bearer {token}'
},
json=user_data
)
response.raise_for_status()
return response.json()
def list_users(token, filters=None):
params = filters or {}
response = requests.get(
'https://api.vivliohealth.io/ext/latest/users',
headers={'Authorization': f'Bearer {token}'},
params=params
)
response.raise_for_status()
return response.json()Error Responses
| Status | Code | Description |
|---|---|---|
| 400 | VALIDATION_ERROR | Missing or invalid fields |
| 401 | FORBIDDEN | Missing authentication or invalid token |
| 403 | FORBIDDEN | Insufficient scopes |
| 404 | RESOURCE_NOT_FOUND | User not found |
| 409 | RESOURCE_EXISTS | Duplicate username or email |
| 422 | INVALID_REFERENCE | Referenced client does not exist |
Common Use Cases
Create Multiple Users
bash
curl -X POST https://api.vivliohealth.io/ext/latest/users \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {token}" \
-d '{
"username": "nsmith@acme.com",
"firstName": "Nancy",
"lastName": "Smith",
"email": "nsmith@acme.com",
"title": "RN"
}'Search Users by Name
bash
curl "https://api.vivliohealth.io/ext/latest/users?lastName=Smith&limit=5" \
-H "Authorization: Bearer {token}"Deactivate User
bash
curl -X DELETE https://api.vivliohealth.io/ext/latest/users/{userId} \
-H "Authorization: Bearer {token}"