> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hipp.health/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

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](/api-reference/endpoint/users/get-by-id) 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](/api-reference/endpoint/users/get-by-id) 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.

```json theme={null}
{
  "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:

```json theme={null}
{
  "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).

```json theme={null}
{
  "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`.

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

#### 401 - Unauthorized

```json theme={null}
{
  "error": "API key required",
  "statusCode": 401
}
```

#### 403 - Forbidden

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

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "error": "Unable to compute utilization.",
  "statusCode": 500
}
```

## Examples

### cURL Example

```bash theme={null}
# 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

```javascript theme={null}
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);
}
```


## OpenAPI

````yaml GET /v1/authorization-utilization/{publicId}
openapi: 3.0.0
info:
  title: Hipp Health API
  version: 1.0.0
  description: API for managing users and resources within your Hipp Health organization
servers:
  - url: https://app.hipp.health/api
    description: Production Server
security: []
paths:
  /v1/authorization-utilization/{publicId}:
    get:
      tags:
        - authorization-utilization
      summary: Get authorization utilization
      description: >-
        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.
      operationId: getAuthorizationUtilization
      parameters:
        - name: publicId
          in: path
          description: Public identifier of an authorization or of an authorization pool
          required: true
          schema:
            type: string
            minLength: 1
        - name: startDate
          in: query
          description: >-
            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).
          required: false
          schema:
            type: string
            format: date
        - name: endDate
          in: query
          description: >-
            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.
          required: false
          schema:
            type: string
            format: date
        - name: timezone
          in: query
          description: >-
            IANA timezone identifier, for example America/Chicago. Defaults to
            the timezone of the patient's home address.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizationUtilizationResponse'
        '400':
          description: >-
            Bad Request - a query parameter is malformed, or startDate is after
            endDate
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ValidationError'
                  - $ref: '#/components/schemas/ApiErrorResponse'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          description: >-
            Not Found - no authorization or pool with this publicId exists in
            your organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
              example:
                error: No authorization or pool found for auth_7xK2mQ9aLp.
                statusCode: 404
        '422':
          description: >-
            Unprocessable Entity - no timezone was provided and the patient has
            no home address timezone
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
              example:
                error: >-
                  No timezone was provided and the patient has no supported home
                  address timezone.
                statusCode: 422
        '500':
          $ref: '#/components/responses/500'
      security:
        - BearerAuth: []
components:
  schemas:
    AuthorizationUtilizationResponse:
      type: object
      properties:
        subject:
          type: string
          enum:
            - AUTHORIZATION
            - POOL
          description: >-
            Whether the publicId in the request was an authorization or an
            authorization pool
        publicId:
          type: string
          description: The publicId from the request
        startDate:
          type: string
          format: date
          description: >-
            First calendar day of the window in YYYY-MM-DD format, in the
            response timezone
        endDate:
          type: string
          format: date
          description: >-
            Last calendar day of the window in YYYY-MM-DD format, in the
            response timezone
        timezone:
          type: string
          description: >-
            IANA timezone used to interpret the window and to render period
            dates
          example: America/Chicago
        pool:
          allOf:
            - $ref: '#/components/schemas/PoolUtilization'
          nullable: true
          description: >-
            Pool-wide utilization. Null when the authorization is not part of a
            pool.
        members:
          type: array
          items:
            $ref: '#/components/schemas/MemberAuthorizationUtilization'
          description: >-
            Every authorization in the pool, or just the requested authorization
            when it is not part of a pool
      required:
        - subject
        - publicId
        - startDate
        - endDate
        - timezone
        - pool
        - members
    ValidationError:
      type: object
      required:
        - message
        - statusCode
        - validationErrors
      properties:
        message:
          type: string
          example: Validation Error
        statusCode:
          type: integer
          example: 400
        validationErrors:
          type: array
          description: Zod validation issues
          items:
            type: object
            properties:
              code:
                type: string
                example: invalid_type
              message:
                type: string
                example: Required
              path:
                type: array
                items:
                  oneOf:
                    - type: string
                    - type: integer
                example:
                  - email
    ApiErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Human-readable error message
          example: User not found
        statusCode:
          type: integer
          example: 404
      required:
        - error
        - statusCode
    PoolUtilization:
      type: object
      description: >-
        Per-period utilization of an authorization pool, counting the units of
        all of its member authorizations together.
      properties:
        poolPublicId:
          type: string
          description: Public identifier of the authorization pool
        periods:
          type: array
          items:
            $ref: '#/components/schemas/AuthorizationUtilizationPeriod'
          description: >-
            One entry per period in the requested window. Empty when the pool is
            not active in the window.
      required:
        - poolPublicId
        - periods
    MemberAuthorizationUtilization:
      type: object
      description: >-
        Per-period utilization of a single authorization, counting only that
        authorization's own units.
      properties:
        authorizationPublicId:
          type: string
          description: Public identifier of the authorization
        serviceLinePublicId:
          type: string
          description: Public identifier of the authorization's service line
        periods:
          type: array
          items:
            $ref: '#/components/schemas/AuthorizationUtilizationPeriod'
          description: >-
            One entry per period in the requested window. Empty when the
            authorization is not active in the window.
      required:
        - authorizationPublicId
        - serviceLinePublicId
        - periods
    AuthorizationUtilizationPeriod:
      type: object
      description: >-
        Units for one period of an authorization or pool. Periods follow the
        authorization's unit frequency (daily, weekly, monthly, yearly or
        total).
      properties:
        startDate:
          type: string
          format: date
          description: >-
            First calendar day of the period in YYYY-MM-DD format, in the
            response timezone
        endDate:
          type: string
          format: date
          description: >-
            Last calendar day of the period in YYYY-MM-DD format, in the
            response timezone
        unitsUtilized:
          type: number
          description: Units delivered in the period, counted from encounters
        unitsScheduled:
          type: number
          description: Units scheduled in the period, counted from appointments
      required:
        - startDate
        - endDate
        - unitsUtilized
        - unitsScheduled
  responses:
    '401':
      description: Unauthorized - API key required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorResponse'
          example:
            error: API key required
            statusCode: 401
    '403':
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorResponse'
          example:
            error: Access denied
            statusCode: 403
    '500':
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorResponse'
          example:
            error: An unexpected error occurred
            statusCode: 500
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        API key authentication. Include your API key in the Authorization header
        as 'Bearer <your-api-key>'

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.