Skip to main content
GET
/
v1
/
users
Get paginated list of users
curl --request GET \
  --url https://app.hipp.health/api/v1/users \
  --header 'Authorization: Bearer <token>'
{
  "data": [
    {
      "publicId": "<string>",
      "firstName": "<string>",
      "lastName": "<string>",
      "caregiverId": "<string>",
      "birthDate": "2023-12-25",
      "addressLine1": "<string>",
      "addressLine2": "<string>",
      "city": "<string>",
      "state": "<string>",
      "postalCode": "<string>"
    }
  ],
  "pagination": {
    "page": 123,
    "pageSize": 123,
    "totalCount": 123,
    "totalPages": 123
  }
}

​
Get All Users

Retrieve a paginated list of users with optional filtering and sorting.

​
Headers

Authorization: Bearer <your-api-key>

​
Query Parameters

  • page (optional): Page number (1-indexed). Default: 1. Minimum: 1
  • pageSize (optional): Number of items per page. Default: 25. Minimum: 1, Maximum: 100
  • search (optional): Search term to filter users
  • role (optional): Filter by user role
    • Available roles: ADMIN, BILLING_MANAGER, SCHEDULING_MANAGER, CLINICIAN, TECHNICIAN, PATIENT, CAREGIVER, HIPP_ADMIN, HIPP_BILLING_MANAGER, CLINICAL_ADMIN, PAYROLL_ADMIN, CLINICAL_SUPERADMIN
    • Note: HIPP_ADMIN users are never included in the results, even when filtered for.
  • email (optional): Filter by email address
  • sort (optional): Sort order in format field_direction (e.g., createdAt_desc). Multiple sorts can be comma-separated (e.g., createdAt_desc,updatedAt_asc)
    • Allowed fields: createdAt, updatedAt
    • Allowed directions: asc, desc

​
Success Response (200)

{
  "data": [
    {
      "publicId": "usr_1234567890_abc123def",
      "firstName": "John",
      "lastName": "Doe",
      "sex": "MALE",
      "caregiverId": null,
      "role": "PATIENT",
      "birthDate": "1990-01-15",
      "addressLine1": "123 Main St",
      "addressLine2": "Apt 4B",
      "city": "New York",
      "state": "NY",
      "postalCode": "10001"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 25,
    "totalCount": 100,
    "totalPages": 4
  }
}

​
Error Responses

​
400 - Validation Error

{
  "error": "Validation error",
  "details": [
    {
      "code": "invalid_string",
      "message": "Invalid parameter value",
      "path": ["page"]
    }
  ]
}

​
401 - Unauthorized

{
  "error": "API key required"
}

​
403 - Forbidden

{
  "error": "Access denied"
}

​
Examples

​
cURL Example

# Get all users with pagination
curl -X GET "https://app.hipp.health/api/v1/users?page=1&pageSize=25" \
  -H "Authorization: Bearer your-api-key"

# Get users with filtering and sorting
curl -X GET "https://app.hipp.health/api/v1/users?role=CLINICIAN&search=john&sort=createdAt_desc" \
  -H "Authorization: Bearer your-api-key"

​
JavaScript Example

const getUsers = async (params = {}) => {
  const queryParams = new URLSearchParams(params);
  const response = await fetch(`/api/v1/users?${queryParams}`, {
    method: "GET",
    headers: {
      Authorization: "Bearer your-api-key",
    },
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error || "Failed to fetch users");
  }

  return response.json();
};

// Usage
try {
  const result = await getUsers({
    page: 1,
    pageSize: 25,
    role: "CLINICIAN",
    sort: "createdAt_desc",
  });
  console.log("Users:", result.data);
  console.log("Pagination:", result.pagination);
} catch (error) {
  console.error("Error fetching users:", error.message);
}

Authorizations

​
Authorization
string
header
required

API key authentication. Include your API key in the Authorization header as 'Bearer '

Query Parameters

​
page
integer
default:1

Page number (1-indexed)

Required range: x >= 1
​
pageSize
integer
default:25

Number of items per page

Required range: 1 <= x <= 100
​
search
string

Search term to filter users

​
role
enum<string>

Filter by user role User role. All values may be returned by the API; a smaller subset may be assigned when creating a user (see the create user endpoint). Note that HIPP_ADMIN users are never returned by the list users endpoint.

Available options:
ADMIN,
BILLING_MANAGER,
SCHEDULING_MANAGER,
CLINICIAN,
TECHNICIAN,
PATIENT,
CAREGIVER,
HIPP_ADMIN,
HIPP_BILLING_MANAGER,
CLINICAL_ADMIN,
PAYROLL_ADMIN,
CLINICAL_SUPERADMIN
​
email
string<email>

Filter by email address

​
sort
string

Sort order in format 'field_direction' (e.g., 'createdAt_desc'). Multiple sorts can be comma-separated (e.g., 'createdAt_desc,updatedAt_asc'). Allowed fields: createdAt, updatedAt. Allowed directions: asc, desc

Pattern: ^(createdAt|updatedAt)_(asc|desc)(,(createdAt|updatedAt)_(asc|desc))*$

Response

Successful response

​
data
object[]
required

Array of users

​
pagination
object
required