Consent Management

The Consent Management section of the WEX Health and Benefits API provides the tools to build and operate a complete consent lifecycle – from publishing consent documents to presenting them to individuals, recording acceptance, and auditing the consent history over time.

Health and benefits platforms operate in a regulated environment where consent is not optional.HIPAA Authorizations must be obtained before processing protected health information.Privacy Notices must be acknowledged before benefits enrollment.Consent records must be retained and auditable.The Consent Management section addresses all of these requirements through a single, cohesive set of API endpoints.

This section currently contains one resource group:

Why Consent Management Matters

Consent is a prerequisite for data access and benefits processing across much of the WEX platform. Before an individual’s health data can be accessed, before a benefits election can be processed, and before certain plan communications can be sent, an active consent record must often be on file.

The Consent Management endpoints serve three distinct audiences:

• Platform administrators and custodians - Create and manage consent agreements – defining the documents, document types, and file content that will be presented to individuals.
• Application and enrollment developers - Build the consent collection flows that present agreements to individuals, collect their acceptance, and record consent responses before initiating downstream transactions.
• Compliance and audit teams - Query consent history for individuals across all agreements to support regulatory reporting, dispute resolution, and consent expiry workflows.

Resource Group: Agreements

The Agreements resource group covers the full consent lifecycle through six endpoints organized around two closely related sub-resources.

SUB-RESOURCE 1: Agreements (the documents)

SUB-RESOURCE 2: Agreement Responses (the consent records)

The Consent Lifecyle

The typical end-to-end flow for a consent workflow using these endpoints:

Step 1: Discover

GET /agreements?active=true&has_file=true

List agreements that are active and have a renderable document attached. Filter by custodian_id to scope to your organization’s agreements.

Step 2: Retrieve

GET /agreements/{agreementId}

Confirm the agreement is active (active=true).Note doc_type:

• 0 = Agreement (requires explicit acceptance)
• 1 = Guide (informational; no response needed)

Step 3: Display

GET /agreements/{agreementId}/file

Download the document as base64-encoded content. Decode and render to the individual before collecting acceptance.

Step 4: Record

POST /agreement-responses

Once the individual accepts, record the consent response. The record is immutable once created.Use accepted_by for proxy or delegated acceptance.Include response_text to capture the exact acknowledgment wording shown.

Step 5 – Audit

GET /agreement-responses?individual_id={id}

Retrieve the full consent history for an individual at any time. Filter by agreement_id for a targeted status check before a downstream transaction.

For platform administrators managing agreement documents:

Publish

POST /agreements/{agreementId}/file

Upload a new PDF or HTML file to an agreement. The uploaded file becomes the default returned by GET /agreements/{agreementId}/file immediately.

Key Concepts Across this Section

Agreements vs. Agreement Responses

These are distinct resources with distinct concerns. Agreements define what an individual is being asked to consent to. Agreement Responses record whether and when they did. An agreement can exist with no responses (not yet presented), and a response cannot exist without a valid agreement.

Active vs. Retired Agreements

Agreements have a lifecycle. An active agreement (active=true) is eligible for presentation in consent flows. A retired agreement (active=false) has been superseded or withdrawn and must not be presented to individuals for new consent. The GET /agreements endpoint returns all statuses by default; use active=true to filter to current agreements.

Document Types

Two document types are supported via the doc_type field:

• 0 = Agreement: Requires an explicit accepted/declined response. Always follow a successful display with POST /agreement-responses.
• 1 = Guide: Informational.No formal response is expected or recorded. Do not submit a consent response for a Guide.

Immutability of Consent Records

Once a consent record is created via POST /agreement-responses, it cannot be modified or deleted through this API. Consent history is append-only. If a new version of an agreement requires fresh consent, a new agreement record is created and a new response is recorded against it.

Custodian Scoping

Each agreement is owned by a Custodian (typically an employer, TPA, or plan sponsor). Custodian and administrator identifiers are not returned by default – pass include_admin_properties=true on GET /agreements or GET /agreements/{id} to include them. Use custodian_id as a filter on GET /agreements to scope results to a specific organization.

Idempotent Writes

Both write endpoints require a UUID v4 Idempotency-Key header. The first successful (2xx) response is cached for 24 hours, enabling safe retry on network failures without creating duplicate records or duplicate file uploads. Requests without this header are rejected with 400.

File Delivery Format

Agreement documents are delivered as base64-encoded JSON, not as raw binary streams. The response envelope includes mime_type (application/pdf or text/html) and content_length alongside the encoded content field. Your application must decode the content field before rendering.

This is distinct from the Documents resource group (Communications & Content), which supports raw PDF delivery via content negotiation.

Authentication and Authorization

All endpoints in this section require a valid Bearer token:

Authorization: Bearer {your_token}
Tokens must resolve to a known customer shard.[cite: 1] All results are automatically scoped to the caller's shard -- individuals, agreements, and consent records from other shards are not accessible.



| Code | Description |
| :--- | :--- |
| `401` | Token is missing or malformed.|
| `403` | Token does not resolve to a known customer shard, or the caller lacks permission for the requested operation.|
Authorization: Bearer {your_token}
Tokens must resolve to a known customer shard.[cite: 1] All results are automatically scoped to the caller's shard -- individuals, agreements, and consent records from other shards are not accessible.



| Code | Description |
| :--- | :--- |
| `401` | Token is missing or malformed.|
| `403` | Token does not resolve to a known customer shard, or the caller lacks permission for the requested operation.|

Error Handling

All endpoints return RFC 7807 Problem Details on error:

{
  "type": "https://developer.wex.com/errors/...",
  "title": "Short summary.",
  "status": 400,
  "detail": "Explanation of this specific occurrence.",
  "instance": "/agreements/75",
  "invalid_params": [ { "name": "...", "reason": "..." } ]
}

Pagination

GET /agreements uses offset-based pagination:

GET /agreement-responses returns all matching consent records in a single response. There is no pagination on this endpoint.

Related Sections