Get paginated list of users

curl --request GET \
  --url https://app.hipp.health/api/v1/users \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://app.hipp.health/api/v1/users', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.hipp.health/api/v1/users",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://app.hipp.health/api/v1/users"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://app.hipp.health/api/v1/users")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "data": [
    {
      "publicId": "<string>",
      "firstName": "<string>",
      "lastName": "<string>",
      "email": "<string>",
      "phoneNumber": "<string>",
      "userStatus": "LEAD",
      "isActive": true,
      "sex": "MALE",
      "birthDate": "2023-12-25",
      "caregiverId": "<string>",
      "addressLine1": "<string>",
      "addressLine2": "<string>",
      "city": "<string>",
      "state": "<string>",
      "postalCode": "<string>",
      "role": "PATIENT",
      "internalRecordId": "<string>",
      "payors": [
        {
          "payorName": "<string>",
          "priority": "PRIMARY",
          "relationshipToPatient": "SELF",
          "insuredBirthDate": "2023-12-25",
          "insuredAddress": {
            "addressLine1": "<string>",
            "addressLine2": "<string>",
            "city": "<string>",
            "state": "<string>",
            "postalCode": "<string>"
          },
          "memberId": "<string>",
          "groupId": "<string>",
          "planHolder": "<string>",
          "effectiveStartDate": "2023-12-25",
          "effectiveEndDate": "2023-12-25"
        }
      ],
      "authorizations": [
        {
          "publicId": "<string>",
          "authorizationNumber": "<string>",
          "authorizationStatus": "AUTHORIZED",
          "authorizedUnitsQuantity": 123,
          "authorizedUnitFrequency": "DAILY",
          "serviceLine": {
            "publicId": "<string>",
            "name": "<string>"
          },
          "authorizationDate": "2023-12-25",
          "authorizationExpirationDate": "2023-12-25"
        }
      ],
      "authorizationPools": [
        {
          "publicId": "<string>",
          "totalUnits": 123,
          "unitFrequency": "DAILY",
          "isUnlimited": true,
          "payor": {
            "publicId": "<string>",
            "name": "<string>"
          },
          "authorizations": [
            {
              "publicId": "<string>",
              "authorizationNumber": "<string>",
              "authorizationStatus": "AUTHORIZED",
              "serviceLine": {
                "publicId": "<string>",
                "name": "<string>"
              },
              "authorizationDate": "2023-12-25",
              "authorizationExpirationDate": "2023-12-25"
            }
          ]
        }
      ],
      "locationIds": [
        "<string>"
      ],
      "clinicianIds": [
        "<string>"
      ],
      "primaryClinicianId": "<string>"
    }
  ],
  "pagination": {
    "page": 123,
    "pageSize": 123,
    "totalCount": 123,
    "totalPages": 123
  }
}

{
  "message": "Validation Error",
  "statusCode": 400,
  "validationErrors": [
    {
      "code": "invalid_type",
      "message": "Required",
      "path": [
        "email"
      ]
    }
  ]
}

{
  "error": "API key required",
  "statusCode": 401
}

Users

Get All Users

Retrieve a paginated list of users with optional filtering and sorting. Each user includes contact info and an isActive flag (soft-deleted users are returned with isActive=false). Patients also include payors, standalone authorizations, authorizationPools (a shared bucket of hours across service lines), locationIds, and their attached clinicians (clinicianIds plus primaryClinicianId, the provider marked primary); staff include credentials (each with per-payor credentialing records), compliance credentials (HIPAA/CPR/BLS, providers only) and specializations (providers only) plus locationIds and primaryLocationId.

GET

users

Get paginated list of users

curl --request GET \
  --url https://app.hipp.health/api/v1/users \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://app.hipp.health/api/v1/users', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.hipp.health/api/v1/users",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://app.hipp.health/api/v1/users"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://app.hipp.health/api/v1/users")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "data": [
    {
      "publicId": "<string>",
      "firstName": "<string>",
      "lastName": "<string>",
      "email": "<string>",
      "phoneNumber": "<string>",
      "userStatus": "LEAD",
      "isActive": true,
      "sex": "MALE",
      "birthDate": "2023-12-25",
      "caregiverId": "<string>",
      "addressLine1": "<string>",
      "addressLine2": "<string>",
      "city": "<string>",
      "state": "<string>",
      "postalCode": "<string>",
      "role": "PATIENT",
      "internalRecordId": "<string>",
      "payors": [
        {
          "payorName": "<string>",
          "priority": "PRIMARY",
          "relationshipToPatient": "SELF",
          "insuredBirthDate": "2023-12-25",
          "insuredAddress": {
            "addressLine1": "<string>",
            "addressLine2": "<string>",
            "city": "<string>",
            "state": "<string>",
            "postalCode": "<string>"
          },
          "memberId": "<string>",
          "groupId": "<string>",
          "planHolder": "<string>",
          "effectiveStartDate": "2023-12-25",
          "effectiveEndDate": "2023-12-25"
        }
      ],
      "authorizations": [
        {
          "publicId": "<string>",
          "authorizationNumber": "<string>",
          "authorizationStatus": "AUTHORIZED",
          "authorizedUnitsQuantity": 123,
          "authorizedUnitFrequency": "DAILY",
          "serviceLine": {
            "publicId": "<string>",
            "name": "<string>"
          },
          "authorizationDate": "2023-12-25",
          "authorizationExpirationDate": "2023-12-25"
        }
      ],
      "authorizationPools": [
        {
          "publicId": "<string>",
          "totalUnits": 123,
          "unitFrequency": "DAILY",
          "isUnlimited": true,
          "payor": {
            "publicId": "<string>",
            "name": "<string>"
          },
          "authorizations": [
            {
              "publicId": "<string>",
              "authorizationNumber": "<string>",
              "authorizationStatus": "AUTHORIZED",
              "serviceLine": {
                "publicId": "<string>",
                "name": "<string>"
              },
              "authorizationDate": "2023-12-25",
              "authorizationExpirationDate": "2023-12-25"
            }
          ]
        }
      ],
      "locationIds": [
        "<string>"
      ],
      "clinicianIds": [
        "<string>"
      ],
      "primaryClinicianId": "<string>"
    }
  ],
  "pagination": {
    "page": 123,
    "pageSize": 123,
    "totalCount": 123,
    "totalPages": 123
  }
}

{
  "message": "Validation Error",
  "statusCode": 400,
  "validationErrors": [
    {
      "code": "invalid_type",
      "message": "Required",
      "path": [
        "email"
      ]
    }
  ]
}

{
  "error": "API key required",
  "statusCode": 401
}

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, CLINICAL_ADMIN, PAYROLL_ADMIN, CLINICAL_SUPERADMIN
- Note: HIPP internal accounts (HIPP_ADMIN, HIPP_BILLING_MANAGER) are never included in the results, even when filtered for.
email (optional): Filter by email address
isActive (optional): Filter by active state. true returns only active users; false returns only inactive (soft-deleted) users. Omit to return both. Any other value returns a 400.
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)

Each user’s shape is discriminated by its role. Every user carries the same base fields — contact info (publicId, firstName, lastName, email, phoneNumber, userStatus, isActive, role) plus demographics (sex, birthDate, caregiverId) and home address (addressLine1, addressLine2, city, state, postalCode). publicId is the record’s Hipp ID — Hipp’s own stable, automatically assigned identifier — and is returned for every role, including providers. Demographic and address fields are always present but are null for roles that have no such concept (for example a caregiver has no address, and only patients have a birthDate or caregiverId). On top of the base, each role adds only the arrays that are meaningful for it. HIPP internal accounts are never returned.

PATIENT: base + internalRecordId (the client’s Internal Record ID, e.g. an MRN, set by your organization, or null if none is recorded), payors (each with relationshipToPatient, insuredBirthDate, insuredAddress), authorizations (standalone only; each includes its own publicId, which you can pass to Get Authorization Utilization), authorizationPools (shared bucket of hours across service lines; each pool and each authorization inside it has its own publicId), locationIds, clinicianIds (the providers attached to the patient), primaryClinicianId (the provider marked primary, or null if none)
Providers (CLINICIAN, TECHNICIAN, CLINICAL_ADMIN, CLINICAL_SUPERADMIN): base + credentials (each with a payorCredentialing array of per-payor credentialing records), complianceCredentials (HIPAA/CPR/BLS), specializations, locationIds, primaryLocationId, plus a role-dependent care team link. Clinician roles (CLINICIAN, CLINICAL_ADMIN, CLINICAL_SUPERADMIN) include careTeamTechnicianIds (technicians they supervise); a TECHNICIAN includes careTeamLeadIds (clinicians supervising them). Only the field for the user’s role is returned, never both.
Admins (ADMIN, BILLING_MANAGER, SCHEDULING_MANAGER, PAYROLL_ADMIN): base + locationIds, primaryLocationId
CAREGIVER: base fields only

{
  "data": [
    {
      "publicId": "usr_patient_abc123",
      "firstName": "John",
      "lastName": "Doe",
      "email": "john.doe@example.com",
      "phoneNumber": "+1234567890",
      "userStatus": "ACTIVE",
      "isActive": true,
      "role": "PATIENT",
      "internalRecordId": "MRN-12345",
      "sex": "MALE",
      "birthDate": "1990-01-15",
      "addressLine1": "123 Main St",
      "addressLine2": "Apt 4B",
      "city": "New York",
      "state": "NY",
      "postalCode": "10001",
      "caregiverId": null,
      "payors": [
        {
          "payorName": "Blue Cross",
          "memberId": "M123456",
          "groupId": "G7890",
          "priority": "PRIMARY",
          "planHolder": "Jane Doe",
          "relationshipToPatient": "PARENT",
          "insuredBirthDate": "1985-07-20",
          "insuredAddress": {
            "addressLine1": "123 Main St",
            "addressLine2": "Apt 4B",
            "city": "New York",
            "state": "NY",
            "postalCode": "10001"
          },
          "effectiveStartDate": "2024-01-01",
          "effectiveEndDate": null
        }
      ],
      "authorizations": [
        {
          "publicId": "auth_7xK2mQ9aLp",
          "authorizationNumber": "AUTH-001",
          "authorizationStatus": "AUTHORIZED",
          "authorizedUnitsQuantity": 40,
          "authorizedUnitFrequency": "WEEKLY",
          "authorizationDate": "2024-01-01",
          "authorizationExpirationDate": "2024-12-31",
          "serviceLine": {
            "publicId": "svl_abc123",
            "name": "ABA Therapy"
          }
        }
      ],
      "authorizationPools": [
        {
          "publicId": "aup_xyz789",
          "totalUnits": 320,
          "unitFrequency": "WEEKLY",
          "isUnlimited": false,
          "payor": {
            "publicId": "pay_abc123",
            "name": "Blue Cross"
          },
          "authorizations": [
            {
              "publicId": "auth_Hn3VbT5cJw",
              "authorizationNumber": "AUTH-POOL-001",
              "authorizationStatus": "AUTHORIZED",
              "authorizationDate": "2024-02-01",
              "authorizationExpirationDate": "2024-12-31",
              "serviceLine": {
                "publicId": "svl_def456",
                "name": "Speech Therapy"
              }
            }
          ]
        }
      ],
      "locationIds": ["loc_abc123"],
      "clinicianIds": ["usr_provider_def456", "usr_provider_mno345"],
      "primaryClinicianId": "usr_provider_def456"
    },
    {
      "publicId": "usr_provider_def456",
      "firstName": "Jane",
      "lastName": "Smith",
      "email": "jane.smith@example.com",
      "phoneNumber": "+1234567891",
      "userStatus": null,
      "isActive": true,
      "role": "CLINICIAN",
      "sex": "FEMALE",
      "birthDate": null,
      "caregiverId": null,
      "addressLine1": "9 Clinic Rd",
      "addressLine2": null,
      "city": "New York",
      "state": "NY",
      "postalCode": "10001",
      "credentials": [
        {
          "credentialType": "BCBA",
          "practiceArea": "ABA",
          "credentialNumber": "1-23-4567",
          "expiresAt": "2025-12-31T00:00:00.000Z",
          "credentialStatus": "active",
          "payorCredentialing": [
            {
              "publicId": "pcpay_9aBcDeFgHi",
              "payor": { "publicId": "pay_1aBcDeFgHi", "name": "Aetna" },
              "status": "APPROVED",
              "startDate": "2025-01-01",
              "endDate": null,
              "notes": null
            }
          ]
        }
      ],
      "complianceCredentials": ["HIPAA", "CPR"],
      "specializations": [
        {
          "publicId": "spec_348HjqQrL-",
          "name": "Early Intervention"
        }
      ],
      "locationIds": ["loc_abc123"],
      "primaryLocationId": "loc_abc123",
      "careTeamTechnicianIds": ["usr_tech_9aBc"]
    },
    {
      "publicId": "usr_admin_ghi789",
      "firstName": "Sam",
      "lastName": "Taylor",
      "email": "sam.taylor@example.com",
      "phoneNumber": "+1234567892",
      "userStatus": null,
      "isActive": true,
      "role": "BILLING_MANAGER",
      "sex": null,
      "birthDate": null,
      "caregiverId": null,
      "addressLine1": "4 Office Blvd",
      "addressLine2": "Suite 100",
      "city": "Newark",
      "state": "NJ",
      "postalCode": "07001",
      "locationIds": ["loc_def456"],
      "primaryLocationId": null
    },
    {
      "publicId": "usr_caregiver_jkl012",
      "firstName": "Pat",
      "lastName": "Jones",
      "email": "pat.jones@example.com",
      "phoneNumber": "+1234567893",
      "userStatus": null,
      "isActive": true,
      "role": "CAREGIVER",
      "sex": null,
      "birthDate": null,
      "caregiverId": null,
      "addressLine1": null,
      "addressLine2": null,
      "city": null,
      "state": null,
      "postalCode": null
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 25,
    "totalCount": 100,
    "totalPages": 4
  }
}

Error Responses

400 - Validation Error

{
  "message": "Validation Error",
  "statusCode": 400,
  "validationErrors": [
    {
      "code": "invalid_type",
      "message": "Required",
      "path": ["page"]
    }
  ]
}

401 - Unauthorized

{
  "error": "API key required",
  "statusCode": 401
}

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

string

Search term to filter users

role

enum<string>

Filter by user role. Only public roles are accepted; HIPP internal roles (HIPP_ADMIN, HIPP_BILLING_MANAGER) are not valid values and any other unrecognized value returns 400. User role. HIPP internal accounts (HIPP_ADMIN, HIPP_BILLING_MANAGER) are never returned by the API and cannot be assigned. A smaller subset may be assigned when creating a user (see the create user endpoint).

Available options:

ADMIN,

BILLING_MANAGER,

SCHEDULING_MANAGER,

CLINICIAN,

TECHNICIAN,

PATIENT,

CAREGIVER,

CLINICAL_ADMIN,

PAYROLL_ADMIN,

CLINICAL_SUPERADMIN

string<email>

Filter by email address

isActive

boolean

Filter by active state. 'true' returns only active users; 'false' returns only inactive (soft-deleted) users. Omit to return both. Any other value returns 400.

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

A user's shape is discriminated by role. Consumers should switch on role to read the role-specific fields. HIPP internal accounts are never returned.

Option 1
Option 2
Option 3
Option 4
Option 5

Show child attributes

pagination

object

required

Show child attributes

API Documentation

Endpoints

Get All Users

Get All Users

Headers

Query Parameters

Success Response (200)

Error Responses

400 - Validation Error

401 - Unauthorized

Examples

cURL Example

JavaScript Example

Authorizations

Query Parameters

Response

​Get All Users

​Headers

​Query Parameters

​Success Response (200)

​Error Responses

​400 - Validation Error

​401 - Unauthorized

​Examples

​cURL Example

​JavaScript Example

Authorizations

Query Parameters

Response

Get All Users

Headers

Query Parameters

Success Response (200)

Error Responses

400 - Validation Error

401 - Unauthorized

Examples

cURL Example

JavaScript Example