Get authorization utilization

curl --request GET \
  --url https://app.hipp.health/api/v1/authorization-utilization/{publicId} \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://app.hipp.health/api/v1/authorization-utilization/{publicId}"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

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

fetch('https://app.hipp.health/api/v1/authorization-utilization/{publicId}', 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/authorization-utilization/{publicId}",
  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/authorization-utilization/{publicId}"

	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/authorization-utilization/{publicId}")

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

{
  "subject": "AUTHORIZATION",
  "publicId": "<string>",
  "startDate": "2023-12-25",
  "endDate": "2023-12-25",
  "timezone": "America/Chicago",
  "pool": {
    "poolPublicId": "<string>",
    "periods": [
      {
        "startDate": "2023-12-25",
        "endDate": "2023-12-25",
        "unitsUtilized": 123,
        "unitsScheduled": 123
      }
    ]
  },
  "members": [
    {
      "authorizationPublicId": "<string>",
      "serviceLinePublicId": "<string>",
      "periods": [
        {
          "startDate": "2023-12-25",
          "endDate": "2023-12-25",
          "unitsUtilized": 123,
          "unitsScheduled": 123
        }
      ]
    }
  ]
}

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

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

{
  "error": "Access denied",
  "statusCode": 403
}

{
  "error": "No authorization or pool found for auth_7xK2mQ9aLp.",
  "statusCode": 404
}

{
  "error": "No timezone was provided and the patient has no supported home address timezone.",
  "statusCode": 422
}

{
  "error": "An unexpected error occurred",
  "statusCode": 500
}

Authorization Utilization

Get Authorization Utilization

Get per-period utilization for a patient authorization or an authorization pool. Pass an authorization publicId or a pool publicId; the response always includes the pool (null for a standalone authorization) and every member authorization. Each period reports unitsUtilized (delivered units, from encounters) and unitsScheduled (units from appointments). startDate defaults to the authorization start date (the earliest member start date for a pool) and endDate defaults to six weeks from today; either can be supplied on its own, and a supplied range is limited only by the one-year maximum the authorization engine enforces. timezone is an IANA timezone and defaults to the timezone of the patient’s home address; the request fails with 422 when neither is available. Results are scoped to the organization that owns the API key.

GET

authorization-utilization

{publicId}

Get authorization utilization

curl --request GET \
  --url https://app.hipp.health/api/v1/authorization-utilization/{publicId} \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://app.hipp.health/api/v1/authorization-utilization/{publicId}"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

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

fetch('https://app.hipp.health/api/v1/authorization-utilization/{publicId}', 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/authorization-utilization/{publicId}",
  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/authorization-utilization/{publicId}"

	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/authorization-utilization/{publicId}")

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

{
  "subject": "AUTHORIZATION",
  "publicId": "<string>",
  "startDate": "2023-12-25",
  "endDate": "2023-12-25",
  "timezone": "America/Chicago",
  "pool": {
    "poolPublicId": "<string>",
    "periods": [
      {
        "startDate": "2023-12-25",
        "endDate": "2023-12-25",
        "unitsUtilized": 123,
        "unitsScheduled": 123
      }
    ]
  },
  "members": [
    {
      "authorizationPublicId": "<string>",
      "serviceLinePublicId": "<string>",
      "periods": [
        {
          "startDate": "2023-12-25",
          "endDate": "2023-12-25",
          "unitsUtilized": 123,
          "unitsScheduled": 123
        }
      ]
    }
  ]
}

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

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

{
  "error": "Access denied",
  "statusCode": 403
}

{
  "error": "No authorization or pool found for auth_7xK2mQ9aLp.",
  "statusCode": 404
}

{
  "error": "No timezone was provided and the patient has no supported home address timezone.",
  "statusCode": 422
}

{
  "error": "An unexpected error occurred",
  "statusCode": 500
}

Get Authorization Utilization

Retrieve per-period utilization for a patient authorization or an authorization pool: how many units have been delivered and how many are scheduled in each period. Results are scoped to the organization that owns the API key. The endpoint returns utilization only. For the authorization details themselves (number, status, authorized units, dates), use the Users endpoints.

Headers

Authorization: Bearer <your-api-key>

Path Parameters

publicId (required): Public identifier of an authorization (auth_...) or of an authorization pool (apool_...). Both come from the Users endpoints on a patient: authorizations[].publicId for a standalone authorization and authorizationPools[].publicId for a pool. An authorization inside a pool has its own publicId too, at authorizationPools[].authorizations[].publicId (also returned in this endpoint’s members).

Query Parameters

startDate (optional): First calendar day of the window (YYYY-MM-DD), read as the start of that day in timezone. Default: the authorization start date (the earliest start date among the members for a pool)
endDate (optional): Last calendar day of the window (YYYY-MM-DD), read as the end of that day in timezone. Default: six weeks from today
timezone (optional): IANA timezone identifier, for example America/Chicago. Default: the timezone of the patient’s home address

startDate and endDate are independent: supply either, both, or neither. When you supply both, startDate must be on or before endDate.

How the window and periods work

Default window. With no dates, the window runs from the authorization start date through six weeks from today, regardless of the authorization’s unit frequency.
Your own range. A range you supply is used as given. The only limit is the one-year maximum the authorization engine enforces; an endDate beyond it is shortened to that limit rather than rejected.
Periods. Each entry in periods is one period of the authorization’s unit frequency (daily, weekly, monthly, yearly or total) that overlaps the window. An authorization or pool that is not active in the window returns an empty periods array.
Units. Units are counted in the authorization’s billing unit (for example 15-minute units, or visits). unitsUtilized is delivered units, counted from encounters. unitsScheduled is units scheduled in the period, counted from appointments.
Timezone. timezone, the window dates and every period date use the same IANA timezone. If you do not pass one and the patient has no home address timezone, the request fails with 422.

Pools and members

The response always contains both a pool and a members list:

For a standalone authorization (not part of a pool), pool is null and members contains just that authorization.
For an authorization pool, or for an authorization that belongs to a pool, pool holds the pool-wide utilization and members lists every authorization in the pool.
Each member’s periods count only that authorization’s own units. The pool’s periods count the units of all members together.

Response Fields

subject: AUTHORIZATION or POOL, depending on whether publicId was an authorization or a pool
publicId: The publicId from the request
startDate / endDate: The window that was used (YYYY-MM-DD), in timezone
timezone: The IANA timezone used for the window and for period dates
pool: Pool-wide utilization (poolPublicId and periods), or null for a standalone authorization
members: Utilization of each authorization (authorizationPublicId, serviceLinePublicId and periods)

Each entry in periods has:

startDate / endDate: First and last calendar day of the period (YYYY-MM-DD)
unitsUtilized: Units delivered in the period
unitsScheduled: Units scheduled in the period

Success Response (200)

The example below is a request for an authorization that belongs to a pool, with startDate=2026-09-14, endDate=2026-09-27 and timezone=America/Chicago. The two authorizations are on different service lines and the pool’s units are the sum of its members’ units.

{
  "subject": "AUTHORIZATION",
  "publicId": "auth_7xK2mQ9aLp",
  "startDate": "2026-09-14",
  "endDate": "2026-09-27",
  "timezone": "America/Chicago",
  "pool": {
    "poolPublicId": "apool_4tRzW8nVcD",
    "periods": [
      {
        "startDate": "2026-09-14",
        "endDate": "2026-09-20",
        "unitsUtilized": 30,
        "unitsScheduled": 10
      },
      {
        "startDate": "2026-09-21",
        "endDate": "2026-09-27",
        "unitsUtilized": 6,
        "unitsScheduled": 36
      }
    ]
  },
  "members": [
    {
      "authorizationPublicId": "auth_7xK2mQ9aLp",
      "serviceLinePublicId": "svc_1a2b3c",
      "periods": [
        {
          "startDate": "2026-09-14",
          "endDate": "2026-09-20",
          "unitsUtilized": 18,
          "unitsScheduled": 6
        },
        {
          "startDate": "2026-09-21",
          "endDate": "2026-09-27",
          "unitsUtilized": 4,
          "unitsScheduled": 20
        }
      ]
    },
    {
      "authorizationPublicId": "auth_Hn3VbT5cJw",
      "serviceLinePublicId": "svc_9z8y7x",
      "periods": [
        {
          "startDate": "2026-09-14",
          "endDate": "2026-09-20",
          "unitsUtilized": 12,
          "unitsScheduled": 4
        },
        {
          "startDate": "2026-09-21",
          "endDate": "2026-09-27",
          "unitsUtilized": 2,
          "unitsScheduled": 16
        }
      ]
    }
  ]
}

For a standalone authorization, pool is null and members has one entry:

{
  "subject": "AUTHORIZATION",
  "publicId": "auth_7xK2mQ9aLp",
  "startDate": "2026-09-14",
  "endDate": "2026-09-27",
  "timezone": "America/Chicago",
  "pool": null,
  "members": [
    {
      "authorizationPublicId": "auth_7xK2mQ9aLp",
      "serviceLinePublicId": "svc_1a2b3c",
      "periods": [
        {
          "startDate": "2026-09-14",
          "endDate": "2026-09-20",
          "unitsUtilized": 18,
          "unitsScheduled": 6
        },
        {
          "startDate": "2026-09-21",
          "endDate": "2026-09-27",
          "unitsUtilized": 4,
          "unitsScheduled": 20
        }
      ]
    }
  ]
}

Error Responses

400 - Validation Error

Returned when a query parameter is malformed (startDate or endDate that is not a valid YYYY-MM-DD calendar date, or a timezone that is not a supported IANA identifier).

{
  "message": "Validation Error",
  "statusCode": 400,
  "validationErrors": [
    {
      "code": "custom",
      "message": "date must be a valid YYYY-MM-DD calendar date",
      "path": ["startDate"]
    }
  ]
}

400 - Invalid Date Range

Returned when you supply both dates and startDate is after endDate.

{
  "error": "startDate 2026-10-01 must not be after endDate 2026-09-01.",
  "statusCode": 400
}

401 - Unauthorized

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

403 - Forbidden

Returned when the API key’s user is not allowed to read user data.

{
  "error": "Insufficient permissions for this action",
  "statusCode": 403
}

404 - Not Found

Returned when no authorization or pool with this publicId exists in your organization. An ID that belongs to another organization is indistinguishable from an unknown one.

{
  "error": "No authorization or pool found for auth_7xK2mQ9aLp.",
  "statusCode": 404
}

422 - Unprocessable Entity

Returned when you do not pass timezone and the patient has no home address timezone. Pass timezone explicitly to resolve it.

{
  "error": "No timezone was provided and the patient has no supported home address timezone.",
  "statusCode": 422
}

500 - Internal Server Error

Returned when utilization could not be computed.

{
  "error": "Unable to compute utilization.",
  "statusCode": 500
}

Examples

cURL Example

# Default window: authorization start date through six weeks from today
curl -X GET "https://app.hipp.health/api/v1/authorization-utilization/auth_7xK2mQ9aLp" \
  -H "Authorization: Bearer your-api-key"

# A specific range and timezone
curl -X GET "https://app.hipp.health/api/v1/authorization-utilization/auth_7xK2mQ9aLp?startDate=2026-09-14&endDate=2026-09-27&timezone=America/Chicago" \
  -H "Authorization: Bearer your-api-key"

# An authorization pool
curl -X GET "https://app.hipp.health/api/v1/authorization-utilization/apool_4tRzW8nVcD" \
  -H "Authorization: Bearer your-api-key"

JavaScript Example

const getAuthorizationUtilization = async (publicId, options = {}) => {
  const params = new URLSearchParams();
  if (options.startDate) params.set("startDate", options.startDate);
  if (options.endDate) params.set("endDate", options.endDate);
  if (options.timezone) params.set("timezone", options.timezone);
  const query = params.toString();

  const response = await fetch(
    `/api/v1/authorization-utilization/${publicId}${query ? `?${query}` : ""}`,
    {
      method: "GET",
      headers: {
        Authorization: "Bearer your-api-key",
      },
    }
  );

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

  return response.json();
};

// Usage
try {
  const utilization = await getAuthorizationUtilization("auth_7xK2mQ9aLp", {
    startDate: "2026-09-14",
    endDate: "2026-09-27",
    timezone: "America/Chicago",
  });
  for (const member of utilization.members) {
    for (const period of member.periods) {
      console.log(
        `${member.authorizationPublicId} ${period.startDate}: ` +
          `${period.unitsUtilized} utilized, ${period.unitsScheduled} scheduled`
      );
    }
  }
} catch (error) {
  console.error("Error fetching authorization utilization:", error.message);
}

Authorizations

Authorization

string

header

required

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

Path Parameters

publicId

string

required

Public identifier of an authorization or of an authorization pool

Minimum string length: 1

Query Parameters

startDate

string<date>

First calendar day of the window (YYYY-MM-DD), read as the start of that day in the timezone. Defaults to the authorization start date (the earliest member start date for a pool).

endDate

string<date>

Last calendar day of the window (YYYY-MM-DD), read as the end of that day in the timezone. Defaults to six weeks from today. Dates beyond the one-year maximum the authorization engine enforces are shortened to it.

timezone

string

IANA timezone identifier, for example America/Chicago. Defaults to the timezone of the patient's home address.

Response

Successful response

subject

enum<string>

required

Whether the publicId in the request was an authorization or an authorization pool

Available options:

AUTHORIZATION,

POOL

publicId

string

required

The publicId from the request

startDate

string<date>

required

First calendar day of the window in YYYY-MM-DD format, in the response timezone

endDate

string<date>

required

Last calendar day of the window in YYYY-MM-DD format, in the response timezone

timezone

string

required

IANA timezone used to interpret the window and to render period dates

Example:

"America/Chicago"

pool

object | null

required

Pool-wide utilization. Null when the authorization is not part of a pool.

Show child attributes

members

object[]

required

Every authorization in the pool, or just the requested authorization when it is not part of a pool

Show child attributes

API Documentation

Endpoints

Get Authorization Utilization

Get Authorization Utilization

Headers

Path Parameters

Query Parameters

How the window and periods work

Pools and members

Response Fields

Success Response (200)

Error Responses

400 - Validation Error

400 - Invalid Date Range

401 - Unauthorized

403 - Forbidden

404 - Not Found

422 - Unprocessable Entity

500 - Internal Server Error

Examples

cURL Example

JavaScript Example

Authorizations

Path Parameters

Query Parameters

Response

​Get Authorization Utilization

​Headers

​Path Parameters

​Query Parameters

​How the window and periods work

​Pools and members

​Response Fields

​Success Response (200)

​Error Responses

​400 - Validation Error

​400 - Invalid Date Range

​401 - Unauthorized

​403 - Forbidden

​404 - Not Found

​422 - Unprocessable Entity

​500 - Internal Server Error

​Examples

​cURL Example

​JavaScript Example

Authorizations

Path Parameters

Query Parameters

Response

Get Authorization Utilization

Headers

Path Parameters

Query Parameters

How the window and periods work

Pools and members

Response Fields

Success Response (200)

Error Responses

400 - Validation Error

400 - Invalid Date Range

401 - Unauthorized

403 - Forbidden

404 - Not Found

422 - Unprocessable Entity

500 - Internal Server Error

Examples

cURL Example

JavaScript Example