Documents Report API Documentation

Overview
Fields
Filters
- Relative Date Ranges
Operations
- List
- Read
Finding Expiring Documents

Overview

This collection is the documents report: it returns one row for each customer on each completed document. A document that covers several people (for example, a waiver an adult signs for themselves and two minors) yields one row per person, each with its own role, status, and expiration date. The rows of such a document share a document_id; each row's id is unique.

Documents signed on retired templates are included. Incomplete documents and customers who have been removed are not.

This collection searches documents across all customers. To list the documents of a single customer, see the Customer Documents sub-collection.

This collection is read-only: only the list and read operations are supported. Results are ordered by completion time, most recently completed first.

Access requires the can_access_reports permission on the API user (see the Staff collection); requests without it receive HTTP 403.

Results are paginated with the standard count / next / previous / results envelope and a default page size of 10. Unlike most collections, page_size may be as large as 3000. See the pagination documentation.

Fields

All fields are read-only. They are grouped below by purpose for readability; all groups appear together in each row.

Row & Customer

Name	Type	Description
id	integer	The unique identifier of the row (one customer on one document). This is placed in the URL when making API calls for the row.
document_id	string (UUID)	The identifier of the document. Shared by every customer on the document.
customer_id	integer	The identifier of the customer this row is about.
customer_first_name	string	The customer's first name.
customer_last_name	string	The customer's last name.
role	string	The customer's role on the document. One of the roles.
other_customer_names	string	A comma-separated list of the full names of the other customers on the same document. Empty if there are none.

Document

Name	Type	Description
document_template_id	integer	The identifier of the document template the document was signed on.
document_template_name	string	The name of the document template.
document_type	string	The type of the document template. One of the document types.
template_version_name	string	The name of the template version that was signed.
completed_at	string (ISO-8601 datetime)	When the document was completed. This is the field that `completed_min` / `completed_max` filter on, and the field results are ordered by.
completed_via	string or null	How the document was completed. One of the completed via codes. Null for documents completed before this was recorded and for imported documents.
pdf_url	string (URL) or null	A link to the document's PDF. Null when no PDF has been stored.
proficiency_names	string	A comma-separated list of the names of the proficiencies this document granted this customer. Empty if none.

Status & Expiration

Name	Type	Description
status	string	The status of the document for this customer. One of the statuses.
expiration_date	string (ISO-8601 date) or null	The day the document expires (or expired) for this customer. Null if it never expires. For a minor on a template set to expire when a minor becomes an adult, this is the earlier of the document's own expiration date and the date the minor reaches adult age. The document counts as expired from the start of this date, in the local time of your organization.

Staff Review

Name	Type	Description
requires_staff_approval	boolean	Whether the template version requires staff approval.
approved_by_first_name	string or null	The first name of the staff member who approved the document.
approved_by_last_name	string or null	The last name of the staff member who approved the document.
approved_at	string (ISO-8601 datetime) or null	When the document was approved.
denied_by_first_name	string or null	The first name of the staff member who denied the document.
denied_by_last_name	string or null	The last name of the staff member who denied the document.
denied_at	string (ISO-8601 datetime) or null	When the document was denied.

Statuses

A row has exactly one status. The conditions are evaluated in the order listed below, and the first that applies wins; a row that meets none of them is valid.

Name	Syntax	Description
Pending Staff Review	`PEN`	The document is awaiting staff approval.
Denied by Staff	`DEN`	Staff denied the document.
Expired	`EXP`	The row's `expiration_date` is today or earlier.
Invalid	`INV`	The document has been marked invalid, so it no longer counts for its intended purpose.
Valid	`VAL`	None of the above.

Roles

Name	Syntax
Participant	`PAR`
Minor	`MIN`
Unsupervised Minor	`UMI`
Supervised Adult	`SAD`
Non-Participant	`NON`
Supervisor	`SUP`
Supervisee	`SWE`

Document Types

Name	Syntax
Waiver	`WAI`
Supervisor Form	`SUP`
Proficiency	`PRO`
Membership Agreement	`MEM`
Custom	`CUS`

Completed Via

Name	Syntax	Description
Kiosk	`KIO`	Completed at a kiosk.
Climber App	`APP`	Completed by the customer in the Climber App.
Climber App (Staff)	`APS`	A staff member completed it in the Climber App on the customer's behalf.
Staff Site	`STA`	Completed in the Staff Site.

Filters

See the filtering documentation for more information on how to use filters in the Capitan API.

Name	Syntax	Description
Document Template	`document_template_id_in`	A comma-separated list of document template IDs. For example, `12,15`.
Document Type	`document_type_in`	A comma-separated list of document type codes. For example, `WAI,CUS`.
Status	`status_in`	A comma-separated list of status codes. For example, `VAL,PEN`.
Role	`role_in`	A comma-separated list of role codes. For example, `MIN,UMI`.
Completed Via	`completed_via_in`	A comma-separated list of completed via codes. For example, `KIO,APP`.
Requires Staff Approval	`requires_staff_approval`	`true` or `false`. Filters for rows whose template version does (or does not) require staff approval.
Customer	`customer_id`	Filters for the rows of the customer with the given ID.
Minimum Completed Date	`completed_min`	Filters for documents completed on or after the given ISO-8601 date or datetime. A bare date (`YYYY-MM-DD`) starts at the beginning of that day in the local time of your organization; a datetime without a UTC offset is read in your organization's time zone.
Maximum Completed Date	`completed_max`	Filters for documents completed on or before the given ISO-8601 date or datetime. A bare date is inclusive of its whole local day; a datetime without a UTC offset is read in your organization's time zone.
Completed Range	`completed_range`	Filters for documents completed within a relative date range. For example, `last_7_days`.
Minimum Expiration Date	`expiration_min`	Filters for rows whose `expiration_date` is on or after the given ISO-8601 date.
Maximum Expiration Date	`expiration_max`	Filters for rows whose `expiration_date` is on or before the given ISO-8601 date. Inclusive of the given date.
Expiration Range	`expiration_range`	Filters for rows whose `expiration_date` falls within a relative date range. The `next_*` ranges are the useful ones for finding upcoming expirations.

The _in filters match codes exactly and case-insensitively. Unknown codes are ignored, and a value containing no recognized codes applies no filter. Documents that never expire (a null expiration_date) never match an expiration filter. When a _min or _max is supplied together with the matching _range, the explicit bound wins and the range is ignored. An unparseable date, or an unknown range key, returns HTTP 400.

Relative Date Ranges

The completed_range and expiration_range filters accept the keys below. All are computed in the local time zone of your organization, relative to today.

Key	Range
`today`	Today.
`yesterday`	Yesterday.
`last_24_hours`	The 24 hours ending now (a rolling window, not whole days).
`last_7_days`	Six days ago through today.
`last_28_days`	27 days ago through today.
`last_31_days`	30 days ago through today.
`last_90_days`	89 days ago through today.
`last_365_days`	364 days ago through today.
`this_week_starting_monday`	The Monday-to-Sunday week containing today.
`this_week_starting_sunday`	The Sunday-to-Saturday week containing today.
`last_week_starting_monday`	The Monday-to-Sunday week before the current one.
`last_week_starting_sunday`	The Sunday-to-Saturday week before the current one.
`this_month`	The calendar month containing today.
`last_month`	The previous calendar month.
`this_quarter`	The calendar quarter containing today.
`last_quarter`	The previous calendar quarter.
`this_year`	January 1 through December 31 of the current year.
`last_year`	The previous calendar year.
`year_to_date`	January 1 of the current year through today.
`next_7_days`	Today through 6 days from today.
`next_30_days`	Today through 29 days from today.
`next_90_days`	Today through 89 days from today.
`next_month`	The next calendar month.
`next_quarter`	The next calendar quarter.

Operations

List

Request
GET /api/documents-report/

Response
200 OK
{
    "count": 1284,
    "next": "https://api.hellocapitan.com/api/documents-report/?page=2",
    "previous": null,
    "results": [
        {
            "id": 90417,
            "document_id": "6f1d2c3e-8a4b-4c5d-9e0f-1a2b3c4d5e6f",
            "customer_id": 73188,
            "customer_first_name": "Alex",
            "customer_last_name": "Stone",
            "role": "PAR",
            "other_customer_names": "Riley Stone, Jordan Stone",
            "document_template_id": 12,
            "document_template_name": "Liability Waiver",
            "document_type": "WAI",
            "template_version_name": "Liability Waiver 2026",
            "completed_at": "2026-09-14T17:30:42.118203Z",
            "completed_via": "KIO",
            "pdf_url": "https://.../document-pdfs/liability-waiver.pdf",
            "proficiency_names": "",
            "status": "VAL",
            "expiration_date": "2027-09-14",
            "requires_staff_approval": false,
            "approved_by_first_name": null,
            "approved_by_last_name": null,
            "approved_at": null,
            "denied_by_first_name": null,
            "denied_by_last_name": null,
            "denied_at": null
        },
        ...
    ]
}

Read

Request
GET /api/documents-report/90417/

Response
200 OK
{
    "id": 90417,
    "document_id": "6f1d2c3e-8a4b-4c5d-9e0f-1a2b3c4d5e6f",
    "customer_id": 73188,
    "customer_first_name": "Alex",
    "customer_last_name": "Stone",
    "role": "PAR",
    ...
}

Finding Expiring Documents

To find the waivers that are still valid and expire within the next 30 days, combine the document type, status, and expiration range filters:

GET /api/documents-report/?document_type_in=WAI&status_in=VAL&expiration_range=next_30_days&page_size=1000

Use expiration_min and expiration_max for explicit dates; both ends are inclusive. For example, the waivers expiring during November 2026:

GET /api/documents-report/?document_type_in=WAI&status_in=VAL&expiration_min=2026-11-01&expiration_max=2026-11-30&page_size=1000

Page through results using the next link until it is null; see the pagination documentation.

Keep in mind:

A customer who has since signed a newer document still has a row for the older one. If you only want customers with nothing newer on file, look for a later row for the same customer_id and template (document_template_id) and skip those customers.
Rows carry no membership information. To split a result into members and non-members, match each row's customer_id against the customer_id values returned by the Members collection, which lists every person covered by an active, frozen, or payment-failed membership. Customers who are absent from it are non-members.