Skip to content

User Management ​

Manage users within your client organization.

Authentication ​

Requires a Client token with scopes:

  • user:read — For GET endpoints
  • user:write — For POST/PUT/DELETE endpoints

Endpoints ​

List Users ​

http
GET /ext/latest/users
Authorization: Bearer {token}

Query Parameters:

  • externalId (optional) — Filter by external ID
  • firstName (optional) — Filter by first name
  • lastName (optional) — Filter by last name
  • email (optional) — Filter by email
  • limit (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 ​

FieldTypeCreateUpdateDescription
userIdstring——System-generated UUID (read-only)
clientIdstring——Owning client ID (read-only)
usernamestringrequiredoptionalUsername (typically email)
firstNamestringrequiredoptionalFirst name
lastNamestringrequiredoptionalLast name
emailstringrequiredoptionalEmail address
titlestringoptionaloptionalJob title (nullable)
phonestringoptionaloptionalPhone number (nullable)
externalIdstringoptionaloptionalExternal system identifier (nullable)
activeboolean——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 ​

StatusCodeDescription
400VALIDATION_ERRORMissing or invalid fields
401FORBIDDENMissing authentication or invalid token
403FORBIDDENInsufficient scopes
404RESOURCE_NOT_FOUNDUser not found
409RESOURCE_EXISTSDuplicate username or email
422INVALID_REFERENCEReferenced 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}"

Vivlio Health API Documentation