Documents

Overview

The Documents resource group provides endpoints for retrieving benefit-related documents generated for individuals within the WEX Health and Benefits platform. Documents include account statements, tax documents, and HSA summaries – all accessible through a unified, person-scoped interface.

This resource group is part of the Communications & Content section of the WEX API and contains two endpoints: one for listing documents with filtering and pagination, and one for retrieving the full content of a specific document.

What is a document?

A Document represents a generated benefit-related file associated with a specific person. All document types are surfaced through the same endpoints and distinguished by a document_type field. Supported types are:

• ACCOUNT_STATEMENTS Periodic account statements summarizing spending account activity, balances, and transactions.
• TAX_DOCUMENTS Year-end tax forms related to health savings and spending accounts (for example, IRS Form 1099-SA, 5498-SA).
• HSA_SUMMARY Health Savings Account summary reports covering contributions, distributions, and account balances.

Documents are read-only through this API. They are generated by the WEX platform and associated with a person_id obtained from the Benefits Platform Identity System.

Key Concepts

person_id Both endpoints are scoped to a specific person. The person_id required by GET /documents is obtained by looking up a consumer in the Benefits Platform Identity System (via POST /consumers/lookup or GET /person). It is not the same as an employee_id or individual_id used in other resource groups.

person_id is a required parameter on GET /documents. A missing or empty person_id returns 400 Bad Request.

Mixed Document Types in a Single List GET /documents returns all document types (account statements, tax documents, HSA summaries) together in a single documents array, each item identified by its document_type field. Use the document_type query parameter to filter to a single type when needed. Omitting document_type returns all types.

Content Negotiation on GET /documents/{document_id} The single-document retrieval endpoint supports two response formats, controlled by the Accept header:

• Accept: application/json Returns a JSON object containing the document content as a base64-encoded string, along with mime_type and content_length. Use this for programmatic processing or rendering in a web application.
• Accept: application/pdf Returns the raw PDF binary directly. Use this when you want to serve or save the file directly without base64 decoding.

If the Accept header is omitted, the API defaults to application/json.

This is different from the Agreement File endpoint (GET /agreements/{id}/file) which always returns base64-encoded JSON regardless of Accept header.

Empty Results Are Not Errors GET /documents returns a 200 with an empty documents array when the person is not found or has no documents matching the supplied filters. There is no 404 for a person with no documents. Only GET /documents/{document_id} returns 404, when the specific document_id does not exist.

total_items vs. has_next Unlike most other paginated endpoints in this API that use only has_next, GET /documents also returns total_items – the total count of matching documents across all pages. This allows your application to display “showing X of Y documents” without paginating to the end.

Year Filtering GET /documents accepts an optional year integer parameter. When omitted, results span all available years. When supplied, only documents from that year are returned. A year value out of range returns 400.

Endpoint Summary

GET /documents

• Required: person_id (query)
• Optional: year (integer), document_type (ACCOUNT_STATEMENTS | TAX_DOCUMENTS | HSA_SUMMARY), page (default 0), page_size (default 25, max 100)
• Returns: Paginated documents array with total_items, has_next, page, page_size. Empty array if person not found or no matches.
• Errors: 400 if person_id is empty or year is out of range. No 404 – missing person returns empty list.

GET /documents/{document_id}

• Required: document_id (path), Accept header (application/json or application/pdf)
• Returns: application/json: { contents, mime_type, content_length }; application/pdf: raw PDF binary
• Errors: 400 if document_id is invalid. 404 if document not found. 500 on internal server fault.

Common Workflows

### Display All Documents for a Person

# Step 1: Obtain person_id from the Identity System
POST /consumers/lookup (or GET /person)

# Step 2: List all documents for the person
  
GET /documents?person_id={person_id}


### Display Tax Documents for a Specific Year
GET /documents?person_id={person_id}&document_type=TAX_DOCUMENTS&year=2024


### Render a Document in a Web Application (JSON / base64)

# Step 1: List documents to get document_id values
GET /documents?person_id={person_id}&document_type=ACCOUNT_STATEMENTS

# Step 2: Retrieve the specific document as base64 JSON
GET /documents/{document_id}
Accept: application/json

# Step 3: Decode and render
const bytes = atob(response.contents);
// Render using mime_type (application/pdf or text/html)


### Serve or Save a PDF Directly

GET /documents/{document_id}
Accept: application/pdf

# Response body is the raw PDF binary; pipe directly to file or HTTP response


### Paginate Through a Large Document List

GET /documents?person_id={person_id}&page=0&page_size=100

Use `total_items` from the first response to determine how many pages exist:

const totalPages = Math.ceil(response.total_items / response.page_size);

Or iterate while `has_next` = `true`:


let page = 0;
let hasNext = true;
while (hasNext) {
  const response = await getDocuments({ person_id, page, page_size: 100 });
  process(response.documents);
  hasNext = response.has_next;
  page++;
}
```[cite: 1]
### Display All Documents for a Person

# Step 1: Obtain person_id from the Identity System
POST /consumers/lookup (or GET /person)

# Step 2: List all documents for the person
  
GET /documents?person_id={person_id}


### Display Tax Documents for a Specific Year
GET /documents?person_id={person_id}&document_type=TAX_DOCUMENTS&year=2024


### Render a Document in a Web Application (JSON / base64)

# Step 1: List documents to get document_id values
GET /documents?person_id={person_id}&document_type=ACCOUNT_STATEMENTS

# Step 2: Retrieve the specific document as base64 JSON
GET /documents/{document_id}
Accept: application/json

# Step 3: Decode and render
const bytes = atob(response.contents);
// Render using mime_type (application/pdf or text/html)


### Serve or Save a PDF Directly

GET /documents/{document_id}
Accept: application/pdf

# Response body is the raw PDF binary; pipe directly to file or HTTP response


### Paginate Through a Large Document List

GET /documents?person_id={person_id}&page=0&page_size=100

Use `total_items` from the first response to determine how many pages exist:

const totalPages = Math.ceil(response.total_items / response.page_size);

Or iterate while `has_next` = `true`:


let page = 0;
let hasNext = true;
while (hasNext) {
  const response = await getDocuments({ person_id, page, page_size: 100 });
  process(response.documents);
  hasNext = response.has_next;
  page++;
}
```[cite: 1]

Pagination

GET /documents uses offset-based pagination.

Response fields:

GET /documents/{document_id} returns a single document. Pagination does not apply.

Authentication

Both endpoints require a valid Bearer token:

Authorization: Bearer {your_token}
Missing or invalid tokens return 401 Unauthorized.
Authorization: Bearer {your_token}
Missing or invalid tokens return 401 Unauthorized.

Error Handling

All error responses follow the RFC 7807 Problem Details format:

{
  "type": "https://developer.wex.com/errors/...",
  "title": "Short summary.",
  "status": 400,
  "detail": "Specific explanation.",
  "instance": "/documents",
  "invalid_params": [ { "name": "...", "reason": "..." } ]
}

NOTE – No 403 on these endpoints:

The Documents resource group does not define a 403 Forbidden response. Access control is enforced at the token level (401) rather than at the resource level.

Documents vs. Agreement Files

The WEX API has two distinct patterns for document content delivery. Use this table to choose the right endpoint for your use case:

Related Resource Groups