WEX H&B

Wex Health and Benefits APIs

WEX administers health benefit accounts for thousands of employers and millions of consumers across the United States. The WEX Health & Benefits API exposes core platform capabilities as RESTful endpoints - giving your engineering team programmatic access to consumer profiles, benefit plan structures, enrollments, elections, account balances, and card data.

The API is designed for WEX business partners: benefits administration platforms, HRIS vendors, payroll providers, and employer portals that need to surface real-time benefits data in their own products without building or maintaining the underlying account administration layer.

Partner access only. These APIs require a WEX partnership agreement and credentialed API access. If you're not yet a partner, contact our sales team to explore integration opportunities.

Introduction

WEX Health Benefits Platform APIs provide a comprehensive suite of tools to streamline your benefits administration, enhance your offerings, and deliver a seamless customer experience. By integrating with WEX, you can:

Automate Key Processes
----------------------

Automate tasks such as account creation, claims processing, payment reconciliation, and benefits administration, freeing up your team to focus on higher-value activities.

Expand Your Services
--------------------

Offer a wider range of financial products and services, including HSAs, FSAs, and HRAs.

Improve Consumer Satisfaction
-----------------------------

Provide your consumers with a user-friendly and efficient experience through seamless integrations and real-time data access.

Reduce Costs
------------

Streamline your workflows and reduce manual effort, leading to cost savings and increased efficiency.

Reliability and Performance
---------------------------

WEX is committed to providing highly reliable and performant APIs. We proactively monitor our APIs, employ rigorous performance testing, and provide health/readiness endpoints to help you ensure the stability and responsiveness of your integrations. Learn more about our API performance and availability.

Benefits of Integrating with WEX APIs

#### **Step 1: Confirm your partnership**

API access is available exclusively to credentialed WEX business partners. If you're already a partner, your WEX account manager will provision your integration. Not yet a partner? Contact your Partner Account Executive to get started.

#### **Step 2: Obtain your API credentials**

Create and manage your applications using the CDH Admin Portal. Each application has a `client_id` and a corresponding `client_secret`. Each application should be assigned permissions following the principles of least privilege. Store your credentials securely - never expose them in client-side code or version control.

#### **Step 3: Authenticate and get a token**

Use the OAuth 2.0 Client Credentials flow to exchange your credentials for a bearer token. Tokens expire after one hour - build token refresh into your integration from the start.

#### **Step 4: Explore the API reference**

Browse the endpoint reference for each domain - Claims and Financial Operations, Communications and Content, Lifecycle Actions, Plans, Enrollment and Elections, Platform Security, Users and Identity. The interactive API explorer lets you run live requests directly in the portal without writing any code.

#### **Step 5: Build and certify your integration**

Develop against your sandbox environment, then work with your WEX account manager to validate your integration before promoting to production.

Getting Started

Authentication

WEX Health & Benefits Platform APIs follow a structured lifecycle to ensure stability, predictability, and clear communication with our partners. Understanding this lifecycle helps you plan integrations and manage changes effectively.

<Divider />

API Lifecycle Stages
--------------------

All WEX APIs progress through four distinct stages:

<CodeBlock attributes='{"isFitToPage":false,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>Preview → Public → Deprecated → Retired   </CodeLine>
</CodeBlock>

### 1\. Preview

**Status:** Experimental and subject to change

**Characteristics:**

*   New APIs or features in active development
    
*   Available for testing and early adoption
    
*   May undergo breaking changes without notice
    
*   Limited or no SLA guarantees
    
*   Ideal for proof-of-concept and feedback
    

**Identification:**

*   Marked with `[PREVIEW]` in documentation
    
*   May include version suffix (e.g., `/v1-preview/`)
    
*   Clearly labeled in API Reference
    

**Best Practices:**

*   Use in non-production environments only
    
*   Provide feedback to help shape the final API
    
*   Expect potential changes to endpoints, parameters, and responses
    
*   Do not build production systems on Preview APIs
    

**Support:**

*   Community support and documentation
    
*   Direct feedback channels to product team
    
*   No guaranteed response times
    

<Divider />

### 2\. Public

**Status:** Generally available and production-ready

**Characteristics:**

*   Stable and fully supported
    
*   Covered by SLA commitments
    
*   Breaking changes follow deprecation policy
    
*   Recommended for production use
    
*   Comprehensive documentation and support
    

**Identification:**

*   Standard version numbering (for example, `/v1/`, `/v2/`)
    
*   No special labels in documentation
    
*   Listed in production API catalog
    

**Best Practices:**

*   Use for all production integrations
    
*   Monitor release notes for updates
    
*   Implement proper error handling
    
*   Follow security best practices
    

**Support:**

*   Full technical support
    
*   SLA-backed availability
    
*   Regular updates and bug fixes
    
*   Security patches and improvements
    

<Divider />

### 3\. Deprecated

**Status:** Scheduled for retirement

**Characteristics:**

*   Still functional but not recommended for new integrations
    
*   Minimum 12-month notice before retirement
    
*   Security updates and critical bug fixes only
    
*   Migration path to replacement API provided
    
*   No new features added
    

**Identification:**

*   Marked with `[DEPRECATED]` in documentation
    
*   Deprecation notice in API responses (via headers)
    
*   Retirement date clearly communicated
    

**Deprecation Notice:** When an API is deprecated, you'll receive:

*   Email notification to registered contacts
    
*   In-app notifications in Dev Portal
    

**Timeline:**

*   **T+0 (Announcement):** Deprecation announced with retirement date
    
*   **T+6 months:** Migration guide and replacement API available
    
*   **T+9 months:** Reminder notifications sent
    
*   **T+12 months:** API retired (minimum timeline)
    

**Best Practices:**

*   Plan migration as soon as deprecation is announced
    
*   Test replacement API in non-production environment
    
*   Update integrations before retirement date
    
*   Monitor deprecation headers in API responses
    

**Support:**

*   Migration assistance available
    
*   Documentation for replacement APIs
    
*   Extended support for critical issues
    
*   Consultation for complex migrations
    

<Divider />

### 4\. Retired

**Status:** No longer available

**Characteristics:**

*   API endpoints return `410 Gone` status
    
*   No longer accessible or supported
    
*   All traffic redirected or blocked
    
*   Documentation archived
    

**What Happens:**

*   All requests return `410 Gone`
    
*   No data processing occurs
    
*   Monitoring and logging discontinued
    
*   Documentation moved to archive
    

**If You're Still Using a Retired API:**

*   Immediate action required
    
*   Contact WEX Support for emergency assistance
    
*   Expedited migration support available
    
*   Temporary extension may be possible (fees may apply)
    

<Divider />

Versioning Strategy
-------------------

### Version Numbering

WEX APIs use semantic versioning in the URL path:

<CodeBlock attributes='{"isFitToPage":false,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>https://platform.benefits.wexglobal.com/v{major}/resource</CodeLine>
</CodeBlock>

**Examples:**

*   `/v1/consumers` - Version 1
    
*   `/v2/consumers` - Version 2
    
*   `/v1-preview/new-feature` - Preview version
    

### Breaking vs. Non-Breaking Changes

**Breaking Changes** (require new major version):

*   Removing or renaming endpoints
    
*   Removing or renaming request/response fields
    
*   Changing field data types
    
*   Adding required parameters
    
*   Changing authentication methods
    
*   Modifying error response structures
    

**Non-Breaking Changes** (can be added to existing version):

*   Adding new endpoints
    
*   Adding optional parameters
    
*   Adding new response fields
    
*   Adding new error codes
    
*   Performance improvements
    
*   Bug fixes
    

### Backward Compatibility

*   Public APIs maintain backward compatibility within major versions
    
*   New optional fields may be added without version change
    
*   Clients should ignore unknown fields in responses
    
*   Deprecated fields remain functional until version retirement
    

<Divider />

Emergency Changes
-----------------

In rare cases, WEX may need to make emergency changes:

### Security Vulnerabilities

*   Immediate patches may be applied
    
*   Notification within 24 hours
    
*   Backward compatibility maintained when possible
    
*   Extended support for affected partners
    

### Critical Bugs

*   Fixes deployed as soon as possible
    
*   May affect API behavior
    
*   Detailed communication provided
    
*   Rollback procedures available
    

### Service Disruptions

*   Temporary changes to ensure stability
    
*   Real-time status updates
    
*   Post-incident reports published
    
*   Compensation per SLA terms
    

<Divider />

Frequently Asked Questions
--------------------------

### How long will a Public API be supported?

Public APIs are supported indefinitely until officially deprecated.

### Can I continue using a Deprecated API?

Yes, deprecated APIs remain functional until the retirement date. However, we strongly recommend migrating to the replacement API as soon as possible.

### What if I need more time to migrate?

Contact your WEX account manager to discuss extension options. Extensions may be available for complex integrations (fees may apply).

### How do I know which version to use?

Always use the latest Public (non-deprecated) version for new integrations. Check the API Reference for current recommendations.

### Will Preview APIs always become Public?

Not necessarily. Preview APIs may be modified significantly or discontinued based on feedback. Only use Preview APIs for testing.

### What happens to my data when an API is retired?

Data is not affected by API retirement. Only the API endpoint is retired. Data remains accessible through replacement APIs.

Lifecycle and Deprecation Policy

API Endpoints

Manage claims, payments, and financial account operations. **Claims & Financial Operations** enables developers to manage the movement of funds and financial events across benefit accounts. It includes claim processing, payment methods, card and bank account management, investment activity, and compliance workflows such as substantiation and reclaim. Use these resources to support end-to-end financial operations - from claim adjudication and payment execution to account servicing and investment management - while ensuring compliance and accurate financial tracking.

Core Financial Services
-----------------------

### 1\. Transactions API

The **Transactions API** provides a high-fidelity, detailed ledger of all financial activities within a consumer's benefit plans. This service acts as the definitive audit trail for a specific plan year, capturing every movement of capital.

*   **Comprehensive Auditing**: Track contributions, claims, payments, and adjustments with a standard historical lookback of up to three years.
    
*   **Running Balances**: Optionally include a "checkbook" style view by calculating the account state after each transaction.
    
*   **Flexible Querying**: Deep-dive into specific data by defining ISO 8601 date ranges or requesting recent activity feeds.
    
*   **Implementation Note**: If `number_of_transactions` is set to 0, both `start_date` and `end_date` must be provided to execute the query.
    

### 2\. Spending Accounts API

The **Spending Accounts API** serves as the central hub for retrieving structural and balance information for various financial benefit products, such as **HSAs**, **FSAs**, or **HRAs**.

*   **Dual-Pivot Scoping**: Query data at the individual `consumer_id` level for member portals or at the `plan_id` level for broad employer reporting.
    
*   **Targeted Filtering**: Isolate specific benefit cycles using the `plan_year_id` or filter by up to two specific `account_type` categories simultaneously.
    
*   **High-Volume Ready**: Built-in pagination handles up to 100 items per request, ensuring performance across massive corporate benefit plans.
    

### 3\. Reimbursement Methods API

Manage the "where" and "how" of fund distribution with the **Reimbursement Methods API**. These endpoints control the channels used to return funds to consumers, such as Direct Deposit (ACH) or physical Checks.

*   Method Management: List all available reimbursement channels for a consumer or retrieve granular metadata for a single method.
    
*   Primary Destination Logic: Identify or set the `is_primary` flag to designate which method receives funds for a specific plan year.
    
*   Security & Privacy: Benefit from account masking and contextual security scoped via `consumer_id` and `employer_id`.
    

Integration Standards
---------------------

### Security & Authentication

All financial operations require specific OAuth scopes to ensure data privacy and regulatory compliance:

*   `read:transactions`: Required for auditing historical ledgers.
    
*   `read:accounts`: Required for accessing spending account details and balances.
    
*   `read:reimbursements / write:reimbursements`: Required for viewing or managing payment channels.
    

### Operational Consistency

*   **Identifier Standards**: All system identifiers (Consumer, Plan, Account, and Reimbursement IDs) utilize **UUID v4** format.
    
*   **Temporal Tracking**: All timestamps are formatted according to **ISO 8601** (for example, `2026-04-23T18:30:00Z`).
    
*   **Pagination**: Services utilize a zero-based index. The default `page_size` is 20, with a maximum limit of 100 items per page to maintain optimal response times.
    
*   **Troubleshooting**: Use the `X-Request-Id` header across all requests to assist in cross-system correlation and error logging within the WEX ecosystem.
    

Global Error Reference
----------------------

<Table style="width:100%;min-width:100%" colSizes='["initial","initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"029605c5-b111-4be7-bd2e-a6565c548869","title":"Title"},{"id":"d879e9df-38a8-44a9-bce3-f06d3fce673f","title":"Description"},{"id":"25861c01-7756-4e59-b546-65186303a0b6","title":""}]'>
  <table-row>
    <table-cell>Status Code</table-cell>
    <table-cell>Meaning</table-cell>
    <table-cell>Common Causes</table-cell>
  </table-row>
  <table-row>
    <table-cell>400</table-cell>
    <table-cell>Bad Request</table-cell>
    <table-cell>Missing required IDs; providing more than 2 account_type filters.</table-cell>
  </table-row>
  <table-row>
    <table-cell>401</table-cell>
    <table-cell>Unauthorized</table-cell>
    <table-cell>Invalid, expired, or missing Bearer token.</table-cell>
  </table-row>
  <table-row>
    <table-cell>404</table-cell>
    <table-cell>Not Found</table-cell>
    <table-cell>The specified resource ID (Consumer, Account, or Method) does not exist.</table-cell>
  </table-row>
  <table-row>
    <table-cell>500</table-cell>
    <table-cell>Internal Error</table-cell>
    <table-cell>Unexpected server-side failure during transaction or account aggregation.</table-cell>
  </table-row>
</Table>

Claims & Financial Operations

Access user communications, documents, and forms. Communications & Content enables developers to retrieve and manage user-facing communications and supporting content, including messages, documents, and forms. It provides access to key artifacts that support user engagement, compliance, and workflow completion across WEX platforms. Use this resource to surface important communications, retrieve required documents, and present forms needed for user interaction and benefit administration.

Core Communication Services
---------------------------

### Communications API (Messages)

The **Communications API** provides a robust framework for managing secure, high-stakes interactions with consumers, acting as the primary engine for claim notifications, account alerts, and tax communications.

*   **Inbox Lifecycle Management**: Build a full-service messaging center with capabilities to list messages, view detailed body text, and track real-time `unread_count` metrics.
    
*   **State Tracking**: Support user-driven status updates, including marking communications as read, archiving them to historical views, or favoriting important items.
    
*   **Compliance & Auditing**: Record exact `acknowledged_date` timestamps for legal disclosures and plan-specific requirements.
    
*   **Historical Access**: The system provides a default lookback of three years, which can be refined using specific `start_date` and `end_date` parameters.
    

### Document & Form Integration

The platform integrates messaging with vital benefit artifacts to ensure users have the necessary documentation for workflow completion.

**Attachment Support**: Messages include a `documents` array containing metadata for linked files. **Document Referencing**: The API returns unique `document_id` references. To download the actual file, these IDs must be passed to the dedicated Document or Reporting service. **Unified Requirements**: All identification fields, including `person_id`, `message_id`, and `document_id`, must follow the **UUID v4** standard.

Integration Standards
---------------------

### Scopes & Permissions

Interaction with the Communications & Content suite requires specific OAuth authorizations:

<Table style="width:100%;min-width:100%" colSizes='["initial","initial","initial"]' isHeaderAdded='false' tableHeader='[{"id":"ab443025-cef4-43ab-981a-e31f1649a99b","title":"Title"},{"id":"d6cc0c1f-8ff0-4aaa-b30a-9901323f99b6","title":"Description"},{"id":"8c6feb64-dba6-46ff-acfc-236a7b692b9f","title":""}]'>
  <table-row>
    <table-cell>Scope</table-cell>
    <table-cell>Description</table-cell>
    <table-cell>Required For</table-cell>
  </table-row>
  <table-row>
    <table-cell>read:messages</table-cell>
    <table-cell>View message lists and full message content</table-cell>
    <table-cell>GET operations</table-cell>
  </table-row>
  <table-row>
    <table-cell>write:messages</table-cell>
    <table-cell>Update message status (read, favorite, archive)</table-cell>
    <table-cell>PUT operations</table-cell>
  </table-row>
</Table>

### Operational Logic

*   **Pagination Model**: The list endpoint uses an index-based model with a default `page_size` of 25 (max 100). Use the `has_next` boolean to determine if additional pages are available.
    
*   **Idempotency**: `PUT`requests are idempotent by design; for example, updating a message to `read: true` multiple times consistently results in the same server state.
    
*   **Correlation**: Including a 36-character `X-Request-Id` header is highly recommended for all write operations to assist in troubleshooting across the ecosystem.
    
*   **Time Standards**: All timestamps are returned in **ISO 8601** format (for example, `2026-04-23T12:00:00Z`).
    

Global Error Reference
----------------------

<Table style="width:100%;min-width:100%" colSizes='["initial","initial","initial"]' isHeaderAdded='false' tableHeader='[{"id":"2be20027-0709-44e6-acd5-0c78f2e02220","title":"Title"},{"id":"3b47e7de-4c65-4b79-90f4-6fa46167eac3","title":"Description"},{"id":"a5c572ed-241b-4308-8f74-a14916a8ebe9","title":""}]'>
  <table-row>
    <table-cell>Status Code</table-cell>
    <table-cell>Meaning</table-cell>
    <table-cell>Common Causes</table-cell>
  </table-row>
  <table-row>
    <table-cell>400</table-cell>
    <table-cell>Bad Request</table-cell>
    <table-cell>Invalid UUID format or ID mismatch between Path and Body in PUT requests.</table-cell>
  </table-row>
  <table-row>
    <table-cell>401</table-cell>
    <table-cell>Unauthorized</table-cell>
    <table-cell>Missing or expired Bearer token.</table-cell>
  </table-row>
  <table-row>
    <table-cell>404</table-cell>
    <table-cell>Not Found</table-cell>
    <table-cell>The message_id or person_id provided does not exist.</table-cell>
  </table-row>
  <table-row>
    <table-cell>500</table-cell>
    <table-cell>Server Error</table-cell>
    <table-cell>Internal failure during message processing.</table-cell>
  </table-row>
</Table>

Communications & Content

Manage consumer lifecycle transitions and benefit coverage updates. Lifecycle Actions provide a robust, discovery-driven framework for handling complex offboarding events and mid-year coverage changes. By combining impact analysis, synchronous execution, and asynchronous status tracking, these resources ensure that transitions—such as ending consumer benefit coverage—are accurate, transparent, and compliant with plan rules. Use these tools to automate the complexities of plan bundles, dependent coverage loss, and prorated financial adjustments while maintaining a clear audit trail of all lifecycle events.

Core Termination Services
-------------------------

### Discovery: Get Termination Form Data

The Discovery endpoint acts as the prerequisite for any offboarding workflow by retrieving a "menu" of valid options tailored to a specific consumer.

*   **Menu Retrieval**: Dynamically obtain available\_plans, available\_bundles, and reason\_codes to populate administrative interfaces.
    
*   **Date Validation**: Access the `valid_termination_dates` list to ensure the selected date adheres to business rules and plan configurations.
    

### Execution & Impact Analysis (Requests)

The Termination Request engine is the central component for both simulating and committing coverage changes.

*   **Impact Analysis (Preview Mode)**: Use `PREVIEW` mode to perform a "dry-run" analysis, which identifies `affected_dependents` losing coverage and the `financial_impact` of prorated refunds or premium adjustments.
    
*   **Commitment (Execute Mode)**: Transition to `EXECUTE` mode to finalize the offboarding process and commit changes.
    
*   **Processing Strategies**: Choose `SYNCHRONOUS` for immediate results or `ASYNCHRONOUS` to queue high-volume requests for background processing.
    

### Tracking & Auditing

Maintain full visibility into the lifecycle process with dedicated status and history endpoints.

*   **Request Tracking**: Poll for the status of asynchronous requests to monitor transitions through PENDING, PROCESSING, COMPLETED, or FAILED states.
    
*   **Lifecycle Auditing**: Retrieve a paginated list of all historical termination activity for a specific consumer.
    

Integration Standards
---------------------

### Scopes & Permissions

Lifecycle operations require specific administrative authorizations:

<Table style="width:100%;min-width:100%" colSizes='["initial","initial","initial"]' isHeaderAdded='false' tableHeader='[{"id":"ad92cee1-9dcb-42d6-b529-6511b1440efc","title":"Title"},{"id":"dbb7cb98-a639-4c2c-91ba-e2f52aceee63","title":"Description"},{"id":"bd17fb01-fc2d-49f5-9e68-8fd43f2bc357","title":""}]'>
  <table-row>
    <table-cell>Scope</table-cell>
    <table-cell>Description</table-cell>
    <table-cell>Required For</table-cell>
  </table-row>
  <table-row>
    <table-cell>read:termination</table-cell>
    <table-cell>View eligibility, form data, and request history</table-cell>
    <table-cell>GET operations</table-cell>
  </table-row>
  <table-row>
    <table-cell>write:termination</table-cell>
    <table-cell>Execute or Preview termination requests</table-cell>
    <table-cell>POST operations</table-cell>
  </table-row>
</Table>

### Operational Guardrails

*   **Retry Safety**: All `POST` requests require an `Idempotency-Key` (UUID) to ensure the termination is not processed twice if a timeout occurs.
    
*   **Organizational Context**: Requests must include a `Business-Entity-Id` (Max 50 characters) that matches the consumer's organizational context.
    
*   **Standardized Formats**: Dates follow **ISO 8601** (`YYYY-MM-DD`) , and processing timestamps utilize RFC 3339 in UTC.
    
*   **Request Identification**: Generated Request IDs follow the specific pattern ^REQ-\\d{4}-\\d{6}$.
    

Global Error Reference
----------------------

<Table style="width:100%;min-width:100%" colSizes='["initial","initial","initial"]' isHeaderAdded='false' tableHeader='[{"id":"7e19489d-c57e-4a8a-8d89-55519fe6c153","title":"Title"},{"id":"fa658605-7cba-42f7-ba55-0ddd3ca84b9a","title":"Description"},{"id":"26b80b1c-d469-4ebe-945e-8743fbc0a261","title":""}]'>
  <table-row>
    <table-cell>Status Code</table-cell>
    <table-cell>Meaning</table-cell>
    <table-cell>Resolution</table-cell>
  </table-row>
  <table-row>
    <table-cell>400</table-cell>
    <table-cell>Bad Request</table-cell>
    <table-cell>Verify UUID formats and ensure the selected date is in the valid_termination_dates list.</table-cell>
  </table-row>
  <table-row>
    <table-cell>403</table-cell>
    <table-cell>Forbidden</table-cell>
    <table-cell>Ensure the Business-Entity-Id matches the consumer's organization.</table-cell>
  </table-row>
  <table-row>
    <table-cell>409</table-cell>
    <table-cell>Conflict</table-cell>
    <table-cell>Occurs when the Idempotency-Key is reused with different request parameters.</table-cell>
  </table-row>
  <table-row>
    <table-cell>422</table-cell>
    <table-cell>Unprocessable Entity</table-cell>
    <table-cell>Indicates a business rule violation, such as terminating a plan that is already closed.</table-cell>
  </table-row>
</Table>

Lifecycle Actions

Configure plans, capture elections, and manage enrollment lifecycle. **Plans, Elections & Enrollments** allow developers to define available benefit offerings, capture participant selections, and manage enrollment records over time. It represents the full lifecycle of benefits administration: from plan configuration to user enrollment and ongoing updates. Use this resource to set up plan structures, support open enrollment and life event changes, and maintain accurate records of participant elections and active enrollments across benefit programs.

Core Administration Services
----------------------------

### Plan Years API

The **Plan Years API** establishes the foundational temporal cycles for all benefit offerings. It defines the specific periods for active coverage, contribution collection, and claim incurrence.

*   **Lifecycle Management**: Transition benefit cycles through Upcoming, Active, and Closed states.
    
*   **Temporal Boundaries**: Configure three distinct sub-periods: the **Active Period** for coverage, the **Enrollment Window** for user elections, and **Run-out/Grace Periods** for late claim submissions.
    
*   **Actionable Discovery**: Utilize high-level filtering (for example, relevance=ACTIONABLE) to identify years currently requiring administrative or user attention.
    

### Plans API

The **Plans API** defines the actual financial or healthcare products (for example, HSA, Medical FSA, Commuter) offered to consumers within a specific plan year.

*   **Granular Rule Engine**: Configure over 50 parameters, including contribution caps, reimbursement types, and medical enrollment prerequisites.
    
*   **Financial Tiering**: Support complex employer contribution schedules based on coverage tiers, such as Individual vs. Family.
    
*   **Merchant Controls**: Restrict debit card usage to specific networks (for example, Pharmacies) through merchant category network configurations.
    

### Elections API

The **Elections API** manages specific consumer choices, representing the financial commitments and coverage levels selected for a benefit period.

*   **Contribution Transparency**: Access detailed annual totals and calculated per-pay-period deduction amounts to ensure payroll accuracy.
    
*   **Flexible Querying**: Pivot election data by enrollment event, plan year, or specific benefit plan to verify participant choices.
    
*   **Status Monitoring**: Track whether a selection is Active, Pending, or Historical to maintain accurate benefit representation.
    

### Enrollments API

The **Enrollments API** serves as the definitive record of a consumer’s actual participation in benefit plans over time.

*   **Coverage Tracking**: Monitor the entire state of benefits from initial enrollment through termination, including effective start and end dates.
    
*   **Flexible Identification**: Query portfolios using multiple identifier types, including Person ID, Employee Number, or Employer-specific IDs.
    
*   **Eligibility Verification**: Confirm active coverage before authorizing transactions or secondary plan enrollments.
    

Integration Standards
---------------------

### Scopes & Permissions

Access to these services is governed by specific OAuth scopes:

<Table style="width:100%;min-width:100%" colSizes='["initial","initial","initial"]' isHeaderAdded='false' tableHeader='[{"id":"646154a1-afa8-4f49-bbe5-634d9bed802c","title":"Title"},{"id":"a2dc2047-5c0b-47dc-b436-1430ec894a96","title":"Description"},{"id":"dbb1baa1-8193-48ce-b526-4bf2143e1022","title":""}]'>
  <table-row>
    <table-cell>Scope</table-cell>
    <table-cell>Description</table-cell>
    <table-cell>Required For</table-cell>
  </table-row>
  <table-row>
    <table-cell>read:planyears</table-cell>
    <table-cell>View plan year configurations and deadlines</table-cell>
    <table-cell>GET operations</table-cell>
  </table-row>
  <table-row>
    <table-cell>write:planyears</table-cell>
    <table-cell>Create or modify benefit cycles</table-cell>
    <table-cell>POST, PUT operations</table-cell>
  </table-row>
  <table-row>
    <table-cell>read:plans</table-cell>
    <table-cell>View benefit catalogs and granular rules</table-cell>
    <table-cell>GET operations</table-cell>
  </table-row>
  <table-row>
    <table-cell>write:plans</table-cell>
    <table-cell>Configure new benefit offerings or update logic</table-cell>
    <table-cell>POST, PUT operations</table-cell>
  </table-row>
  <table-row>
    <table-cell>read:enrollments</table-cell>
    <table-cell>Access consumer participation records</table-cell>
    <table-cell>GET operations</table-cell>
  </table-row>
  <table-row>
    <table-cell>read:elections</table-cell>
    <table-cell>Access consumer contribution and selection data</table-cell>
    <table-cell>GET operations</table-cell>
  </table-row>
</Table>

### Data Integrity & Safety

**Idempotency**: All `POST`operations require a unique `Idempotency-Key` (**UUID v4**) to prevent duplicate record creation during network retries. **Optimistic Locking**: Update operations (`PUT`) utilize version control (ETags or version integers) to prevent concurrent update conflicts. **Standardized Formats**: All identifiers must be **UUID v4**. Timestamps and dates must follow **ISO 8601** standards (for example, `YYYY-MM-DDTHH:MM:SSZ`).

Global Error Reference
----------------------

<Table style="width:100%;min-width:100%" colSizes='["initial","initial","initial"]' isHeaderAdded='false' tableHeader='[{"id":"ec42bd17-30dc-4477-befc-1eabe4e10dbc","title":"Title"},{"id":"9a44bc7a-9782-4191-bbc3-a655d93cfe91","title":"Description"},{"id":"91445139-7402-4cd5-816c-96907f7af129","title":""}]'>
  <table-row>
    <table-cell>Status Code</table-cell>
    <table-cell>Meaning</table-cell>
    <table-cell>Common Causes</table-cell>
  </table-row>
  <table-row>
    <table-cell>400</table-cell>
    <table-cell>Bad Request</table-cell>
    <table-cell>Missing required identifiers or invalid date-time logic (for example, end date before start date).</table-cell>
  </table-row>
  <table-row>
    <table-cell>409</table-cell>
    <table-cell>Conflict</table-cell>
    <table-cell>Duplicate idempotency key or overlapping plan year configurations for the same employer.</table-cell>
  </table-row>
  <table-row>
    <table-cell>412</table-cell>
    <table-cell>Precondition Failed</table-cell>
    <table-cell>The provided version or ETag is outdated, indicating a concurrent modification.</table-cell>
  </table-row>
  <table-row>
    <table-cell>404</table-cell>
    <table-cell>Not Found</table-cell>
    <table-cell>The specified plan_id, plan_year_id, enrollment_id, or election_id does not exist.</table-cell>
  </table-row>
</Table>

Plans, Enrollment & Elections

Core operations for managing user profiles, identity verification, and account-level preferences. Users & Identity provides the foundation for managing participant records, identity validation, and user-level configurations across WEX platforms. It enables developers to create and maintain user profiles, verify identity and banking details, and manage communication preferences. Use this resource to onboard users, ensure compliance through verification workflows, and maintain accurate, up-to-date identity and account data that supports downstream benefits and financial operations.

Core Identity Services
----------------------

### Identity & Person Management API

This suite serves as the central repository for unified identity data, providing a single view of all individuals within the platform, including **Consumers**, **Dependents**, **Authorized Signers**, and **Business Contacts**.

*   **Unified Identity Resolver**: Resolve any unique `person_id` into a name, role type, and business association to facilitate cross-entity routing.
    
*   **Family & Delegation Mapping**: Establish a "Household View" by anchoring dependents and account delegates to primary consumers.
    
*   **On-Demand Data Expansion**: Optimize performance by selectively retrieving secondary data blocks such as addresses, employment records, or protected personal data.
    
*   **Identity Hierarchy**: Consumers are anchored to a Business (Employer), while their respective dependents and signers are anchored directly to the Consumer.
    

### Notification Preferences API

Manage how and why consumers receive communications through a comprehensive two-tier preference model.

*   **Internal Triggers**: Manage core event triggers—such as enrollment success or claim denials—that determine if an alert is generated.
    
*   **External Delivery**: Control the delivery channels—**Email**, **SMS**, or **Push**—used to send generated alerts to the consumer.
    
*   **Hierarchy of Choice**: The system follows a gatekeeping flow, checking if a trigger is enabled internally before validating if the external delivery channel and category opt-ins are active.
    
*   **Master Switches**: Utilize global toggles to enable or disable entire communication mediums across the platform.
    

Organizational Foundations
--------------------------

### Administrators API

The foundational step in setting up a new domain by establishing the root business entity.

*   **Hierarchical Anchor**: Represents TPAs or large corporate entities that oversee all downstream employers and plans.
    
*   **Safe Provisioning**: Mandatory idempotency ensures that only one Administrator entity is created per unique key during onboarding.
    

### Business Management API

Manages the operational tiers of the hierarchy, including Employers, Divisions, and Departments.

*   **Multi-Tenant Hierarchy**: Supports deeply nested parent-child relationships for complex corporate structures.
    
*   **Lineage Awareness**: Specialized tools to "walk" up the organizational tree from child nodes to the root Administrator.
    

Integration Standards
---------------------

### Security & Privacy Controls

Managing sensitive data requires rigorous compliance and visibility settings:

<Table style="width:100%;min-width:100%" colSizes='["initial","initial","initial"]' isHeaderAdded='false' tableHeader='[{"id":"5da4b812-3d98-404a-af81-3836696760b1","title":"Title"},{"id":"262e9e3b-65ff-46f8-b0f6-86d402e6b8da","title":"Description"},{"id":"b0dc11bd-a506-4b9f-833f-d06243cfe0b1","title":""}]'>
  <table-row>
    <table-cell>Mode</table-cell>
    <table-cell>Format Example</table-cell>
    <table-cell>Access Level</table-cell>
  </table-row>
  <table-row>
    <table-cell>MASKED</table-cell>
    <table-cell>xxx-xx-1234</table-cell>
    <table-cell>Default for standard users.</table-cell>
  </table-row>
  <table-row>
    <table-cell>LAST4</table-cell>
    <table-cell>1234</table-cell>
    <table-cell>For verification and support workflows.</table-cell>
  </table-row>
  <table-row>
    <table-cell>UNMASKED</table-cell>
    <table-cell>555441234</table-cell>
    <table-cell>Restricted to high-level admin and tax operations.</table-cell>
  </table-row>
</Table>

### Scopes & Permissions

<Table style="width:100%;min-width:100%" colSizes='["initial","initial","initial"]' isHeaderAdded='false' tableHeader='[{"id":"3c952b2e-c62e-4973-b3b1-a823748a97c9","title":"Title"},{"id":"7fe38480-9231-4023-a60e-accea8512a1c","title":"Description"},{"id":"e57afd3d-dc66-4ecb-a691-5b622dd0f3d8","title":""}]'>
  <table-row>
    <table-cell>Scope</table-cell>
    <table-cell>Description</table-cell>
    <table-cell>Required For</table-cell>
  </table-row>
  <table-row>
    <table-cell>read:person</table-cell>
    <table-cell>View unified identity and demographic data.</table-cell>
    <table-cell>All GET operations.</table-cell>
  </table-row>
  <table-row>
    <table-cell>read:notifications</table-cell>
    <table-cell>Access consumer communication settings.</table-cell>
    <table-cell>GET operations.</table-cell>
  </table-row>
  <table-row>
    <table-cell>write:notifications</table-cell>
    <table-cell>Modify internal and external preferences.</table-cell>
    <table-cell>PUT operations.</table-cell>
  </table-row>
  <table-row>
    <table-cell>admin:domain</table-cell>
    <table-cell>Manage top-level domain entities.</table-cell>
    <table-cell>Administrator creation (POST).</table-cell>
  </table-row>
  <table-row>
    <table-cell>write:business</table-cell>
    <table-cell>Create or modify business entities.</table-cell>
    <table-cell>POST/PATCH operations.</table-cell>
  </table-row>
</Table>

Global Error Reference
----------------------

<Table style="width:100%;min-width:100%" colSizes='["initial","initial","initial"]' isHeaderAdded='false' tableHeader='[{"id":"940dc517-39a6-4bef-ae5e-01baf76396d6","title":"Title"},{"id":"e5d11b56-20d5-48b3-8b94-d710aad40eb5","title":"Description"},{"id":"7914b949-4f97-404a-89b0-992bd69e76b6","title":""}]'>
  <table-row>
    <table-cell>Status Code</table-cell>
    <table-cell>Meaning</table-cell>
    <table-cell>Common Causes</table-cell>
  </table-row>
  <table-row>
    <table-cell>400</table-cell>
    <table-cell>Invalid Request</table-cell>
    <table-cell>Missing required IDs, malformed UUIDs, or invalid data formats.</table-cell>
  </table-row>
  <table-row>
    <table-cell>403</table-cell>
    <table-cell>Forbidden</table-cell>
    <table-cell>Insufficient permissions for unmasked data or unauthorized domains.</table-cell>
  </table-row>
  <table-row>
    <table-cell>404</table-cell>
    <table-cell>Not Found</table-cell>
    <table-cell>No person, consumer, or business record matches the provided UUID.</table-cell>
  </table-row>
  <table-row>
    <table-cell>405</table-cell>
    <table-cell>Not Enabled</table-cell>
    <table-cell>The specific feature module is not active for the requester's domain.</table-cell>
  </table-row>
  <table-row>
    <table-cell>409</table-cell>
    <table-cell>Conflict</table-cell>
    <table-cell>Duplicate Idempotency-Key or business EIN already exists.</table-cell>
  </table-row>
</Table>

Users & Identity

SDKs

The WEX Health SDK wraps the WEX Health and Benefits OpenAPI specification into a fully typed stable client. Each language-specific SDK handles the same core concerns — authentication, retry, and logging — so your team only writes business logic.

<Table style="width:100%;min-width:100%" colSizes='["initial","initial"]' isHeaderAdded='false' tableHeader='[{"id":"80dd59a7-ede0-414f-ab77-50bdfb689b24","title":"Title"},{"id":"5ec27775-d1f7-4a89-b4fd-ae6f1547f74a","title":"Description"},{"id":"e716c2f7-a632-4abd-8fd4-8dd15d4703b3","title":"Title"}]'>
  <table-row>
    <table-cell>Feature</table-cell>
    <table-cell>SDK Handles (Automated)</table-cell>
    <table-cell>Your Implementation</table-cell>
  </table-row>
  <table-row>
    <table-cell>Auth</table-cell>
    <table-cell>OAuth 2.0 fetching, caching, and refresh</table-cell>
    <table-cell>Provide credentials once</table-cell>
  </table-row>
  <table-row>
    <table-cell>Resiliency</table-cell>
    <table-cell>Exponential backoff + jitter</table-cell>
    <table-cell>Standard await calls</table-cell>
  </table-row>
  <table-row>
    <table-cell>Type Safety</table-cell>
    <table-cell>Models and typed clients</table-cell>
    <table-cell>Business logic</table-cell>
  </table-row>
  <table-row>
    <table-cell>Errors</table-cell>
    <table-cell>RFC 7807 / ApiException translation</table-cell>
    <table-cell>try/catch blocks</table-cell>
  </table-row>
  <table-row>
    <table-cell>Tracing</table-cell>
    <table-cell>Structured logging and x-request-id</table-cell>
    <table-cell>App-level logging</table-cell>
  </table-row>
  <table-row>
    <table-cell>Telemetry</table-cell>
    <table-cell>Identification headers</table-cell>
    <table-cell>Handled automatically</table-cell>
  </table-row>
</Table>


1\. Prerequisites
-----------------


### Credentials

Partners are provisioned with unique credentials for each API service they integrate. Before writing any code, contact the API team you are integrating with — to ensure the API team has enabled your application:

<Table style="width:100%;min-width:100%" colSizes='["initial","initial"]' isHeaderAdded='false' tableHeader='[{"id":"02b7a6b5-16cf-4aab-a7ff-2d6b609ced63","title":"Title"},{"id":"cc4d5d77-ad7c-4dc8-82bc-95977a1080c1","title":"Description"}]'>
  <table-row>
    <table-cell>Credential</table-cell>
    <table-cell>Description</table-cell>
  </table-row>
  <table-row>
    <table-cell>CLIENT_ID</table-cell>
    <table-cell>Your OAuth 2.0 client identifier — issued per integration by the API team</table-cell>
  </table-row>
  <table-row>
    <table-cell>CLIENT_SECRET</table-cell>
    <table-cell>Your OAuth 2.0 client secret — treat this like a password</table-cell>
  </table-row>
  <table-row>
    <table-cell>TOKEN_URL</table-cell>
    <table-cell>Token endpoint for that team's auth server, for example, https://auth.wexglobal.com/oauth/token</table-cell>
  </table-row>
  <table-row>
    <table-cell>AUDIENCE</table-cell>
    <table-cell>OAuth audience — service-specific, may be optional</table-cell>
  </table-row>
  <table-row>
    <table-cell>SCOPES</table-cell>
    <table-cell>Available scopes, such as claims:read and consumers:read, are configured at the API level and granted during client provisioning</table-cell>
  </table-row>
</Table>

⚠️ Never hardcode credentials in source code. Store them in environment variables, a secrets vault (Azure Key Vault, AWS Secrets Manager, HashiCorp Vault), or your CI/CD secrets store.


All four SDKs read credentials from the same environment variables:

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>export WEX_OAUTH2_TOKEN_URL="https://your-auth-server.com/oauth/token"</CodeLine>
  <CodeLine>export WEX_OAUTH2_CLIENT_ID="your-client-id"</CodeLine>
  <CodeLine>export WEX_OAUTH2_CLIENT_SECRET="your-client-secret"  </CodeLine>
</CodeBlock>


### Environments

<Table style="width:100%;min-width:100%" colSizes='["initial","initial"]' isHeaderAdded='false' tableHeader='[{"id":"a0218ec4-cfeb-4770-967e-42f76894acb2","title":"Title"},{"id":"e0908c89-4aee-4570-a8a8-7ddc0969c660","title":"Description"}]'>
  <table-row>
    <table-cell>Environment</table-cell>
    <table-cell>Base URL</table-cell>
  </table-row>
  <table-row>
    <table-cell>UAT / Staging</table-cell>
    <table-cell>https://platform.uat.benefits.wexglobal.com</table-cell>
  </table-row>
  <table-row>
    <table-cell>Production</table-cell>
    <table-cell>Provided separately — after UAT sign-off with the WEX team</table-cell>
  </table-row>
</Table>

Always build and validate against UAT before requesting production access.


### Runtime Requirements

<Table style="width:100%;min-width:100%" colSizes='["initial","initial"]' isHeaderAdded='false' tableHeader='[{"id":"3d1fa062-fa44-428c-a4b4-3fb6b44b396b","title":"Title"},{"id":"62aa4e30-70f7-4bbc-8cb4-a5674d83d54c","title":"Description"}]'>
  <table-row>
    <table-cell>Platform</table-cell>
    <table-cell>Minimum Requirement</table-cell>
  </table-row>
  <table-row>
    <table-cell>.NET</table-cell>
    <table-cell>.NET 6+ (net8.0 recommended)</table-cell>
  </table-row>
  <table-row>
    <table-cell>JavaScript / TypeScript</table-cell>
    <table-cell>Node.js v20.10+ (v22.20+ recommended); npm 10.x+</table-cell>
  </table-row>
  <table-row>
    <table-cell>Java</table-cell>
    <table-cell>Java 17+; Maven or Gradle; Spring Boot 3.x recommended</table-cell>
  </table-row>
  <table-row>
    <table-cell>Python</table-cell>
    <table-cell>Python 3.x; pip</table-cell>
  </table-row>
</Table>


2\. Retry Contract — Consistent Across All SDKs
-----------------------------------------------

All four SDKs ship the same retry behavior out of the box — no configuration required. This table applies regardless of which language you are integrating with.

<Table style="width:100%;min-width:100%" colSizes='["initial","462px"]' isHeaderAdded='false' tableHeader='[{"id":"d9245ef8-ca5d-4142-9bdd-dfd4f87c1816","title":"Title"},{"id":"3d2ec826-871f-4a9d-b796-bbb5406c05b2","title":"Description"}]'>
  <table-row>
    <table-cell>Condition</table-cell>
    <table-cell>Behaviour</table-cell>
  </table-row>
  <table-row>
    <table-cell>5xx server errors</table-cell>
    <table-cell>Retry up to 3 times (4 total attempts)</table-cell>
  </table-row>
  <table-row>
    <table-cell>408 Request Timeout</table-cell>
    <table-cell>Retry</table-cell>
  </table-row>
  <table-row>
    <table-cell>429 with Retry-After header</table-cell>
    <table-cell>Retry after the server-specified delay (capped at 30 s)</table-cell>
  </table-row>
  <table-row>
    <table-cell>429 without Retry-After</table-cell>
    <table-cell>Not retried</table-cell>
  </table-row>
  <table-row>
    <table-cell>4xx (other)</table-cell>
    <table-cell>Not retried — these are client errors</table-cell>
  </table-row>
  <table-row>
    <table-cell>Network failures</table-cell>
    <table-cell>Retry</table-cell>
  </table-row>
  <table-row>
    <table-cell>Backoff strategy</table-cell>
    <table-cell>Exponential with full jitter: 500 ms → 1 s → 2 s</table-cell>
  </table-row>
  <table-row>
    <table-cell>Global timeout</table-cell>
    <table-cell>30 seconds across all attempts</table-cell>
  </table-row>
</Table>


Retries happen automatically — a `5xx` exception only surfaces to your code after all retry attempts are exhausted. The jitter adds a randomized delay to retries, preventing a 'thundering herd'—where a surge of simultaneous requests from recovering services overwhelms the system.


**HTTP status code reference:**

<Table style="width:100%;min-width:100%" colSizes='["initial","initial"]' isHeaderAdded='false' tableHeader='[{"id":"485b1cc2-e213-4912-83e7-731df6366f45","title":"Title"},{"id":"8b2a26c4-ca83-4cb4-8805-50a9734d7de8","title":"Description"}]'>
  <table-row>
    <table-cell>Status</table-cell>
    <table-cell>Meaning</table-cell>
    <table-cell>What to do</table-cell>
  </table-row>
  <table-row>
    <table-cell>400</table-cell>
    <table-cell>Bad Request</table-cell>
    <table-cell>Fix request parameters</table-cell>
  </table-row>
  <table-row>
    <table-cell>401</table-cell>
    <table-cell>Unauthorized</table-cell>
    <table-cell>Check credentials / token URL</table-cell>
  </table-row>
  <table-row>
    <table-cell>403</table-cell>
    <table-cell>Forbidden</table-cell>
    <table-cell>Check scopes granted to your client</table-cell>
  </table-row>
  <table-row>
    <table-cell>404</table-cell>
    <table-cell>Not Found</table-cell>
    <table-cell>Resource does not exist — not retried</table-cell>
  </table-row>
  <table-row>
    <table-cell>408</table-cell>
    <table-cell>Timeout</table-cell>
    <table-cell>Retried automatically</table-cell>
  </table-row>
  <table-row>
    <table-cell>429</table-cell>
    <table-cell>Rate Limited</table-cell>
    <table-cell>Retried only if Retry-After header is present</table-cell>
  </table-row>
  <table-row>
    <table-cell>5xx</table-cell>
    <table-cell>Server Error</table-cell>
    <table-cell>Retried automatically</table-cell>
  </table-row>
</Table>


Jump to Your Language
---------------------

*   [**.NET**](https://app-staging.theneo.io/editor/69e0ee5bc0d28c7a4dacf542/69e0ee5bc0d28c7a4dacf545?type=sections&current=69e0f17a705aeb2fd63c9551&path=sdks%2Fnet) ← Primary integration path - most detailed
    
*   [JavaScript / TypeScript](https://app-staging.theneo.io/editor/69e0ee5bc0d28c7a4dacf542/69e0ee5bc0d28c7a4dacf545?type=sections&current=69e0f18c705aeb2fd63c9565&path=sdks%2Fjavascript)
    
*   [Java](https://app-staging.theneo.io/editor/69e0ee5bc0d28c7a4dacf542/69e0ee5bc0d28c7a4dacf545?type=sections&current=69e0f199ad395f0e8c527750&path=sdks%2Fjava)
    
*   [Python](https://app-staging.theneo.io/editor/69e0ee5bc0d28c7a4dacf542/69e0ee5bc0d28c7a4dacf545?type=sections&current=69e0f1a7db360de60a599370&path=sdks%2Fpython)

Overview

The .NET section is the most complete. The same concepts — singleton configuration, OAuth 2.0, retry, error handling, logging — apply to every other language. Skip ahead if you're using a different stack.

### Step 0 — Configure the nuget feed

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"xml","label":"XML"}'>
  <CodeLine>&lt;?xml version="1.0" encoding="utf-8"?&gt;</CodeLine>
  <CodeLine>&lt;configuration&gt;</CodeLine>
  <CodeLine>  &lt;packageSources&gt;</CodeLine>
  <CodeLine>    &lt;add key="WexHealth-Public" value="https://pkgs.dev.azure.com/wexhealth/_packaging/SDK/nuget/v3/index.json" /&gt;</CodeLine>
  <CodeLine>  &lt;/packageSources&gt;</CodeLine>
  <CodeLine>&lt;/configuration&gt; </CodeLine>
</CodeBlock>

Add the following in your project file and replace the version you want to pin:

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"xml","label":"XML"}'>
  <CodeLine>&lt;ItemGroup&gt;</CodeLine>
  <CodeLine>  &lt;PackageReference Include="WexHealth.SDK" Version="1.2.3" /&gt;</CodeLine>
  <CodeLine>&lt;/ItemGroup&gt;  </CodeLine>
</CodeBlock>

### Step 1 — Install

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"bash","label":"Bash"}'>
  <CodeLine>dotnet add package WexHealth</CodeLine>
</CodeBlock>

### Step 2 — Configure

The SDK's `AddWexHealthSdk` extension method wires `IHttpClientFactory`, connection pooling, logger injection, and transient DI lifetimes — all in a single call in `Program.cs`. The underlying IHttpClientFactory is a singleton: one registered, shared connection pool for the lifetime of the application. Creating HttpClient instances directly per request defeats connection pooling and can cause socket exhaustion.

**What** `**AddWexHealthSdk**` **handles automatically:**

<Table style="width:100%;min-width:100%" colSizes='["initial","initial"]' isHeaderAdded='false' tableHeader='[{"id":"dfbdba4e-179f-4b7a-b9f7-d092171bf521","title":"Title"},{"id":"b8d96e60-d7d0-4bb2-b7ad-41e9411995c7","title":"Description"}]'>
  <table-row>
    <table-cell>Concern</table-cell>
    <table-cell>What the SDK does</table-cell>
  </table-row>
  <table-row>
    <table-cell>IHttpClientFactory wiring</table-cell>
    <table-cell>Registers a named HttpClient per API</table-cell>
  </table-row>
  <table-row>
    <table-cell>Connection pooling</table-cell>
    <table-cell>Managed by the factory — no socket exhaustion risk</table-cell>
  </table-row>
  <table-row>
    <table-cell>Fail-fast misconfiguration</table-cell>
    <table-cell>InvalidOperationException if BaseAddress is missing</table-cell>
  </table-row>
  <table-row>
    <table-cell>Duplicate registrations</table-cell>
    <table-cell>Safe no-op — first registration wins</table-cell>
  </table-row>
  <table-row>
    <table-cell>Transient DI Lifetime</table-cell>
    <table-cell>A new API instance per injection - stateless and safe for concurrent use</table-cell>
  </table-row>
  <table-row>
    <table-cell>Logger injection</table-cell>
    <table-cell>ILogger resolved from DI automatically</table-cell>
  </table-row>
</Table>

The following example demonstrates how the SDK handles the `IClaimsApi` registration and resolution:

`Program.cs`

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"csharp","label":"C#"}'>
  <CodeLine>using WexHealth.Api;
using WexHealth.DependencyInjection;</CodeLine>
  <CodeLine>// Register your auth handler before AddWexHealthSdk</CodeLine>
  <CodeLine>builder.Services.AddTransient&lt;OAuthTokenHandler&gt;();</CodeLine>
  <CodeLine>builder.Services.AddWexHealthSdk(sdk =&gt;</CodeLine>
  <CodeLine>{</CodeLine>
  <CodeLine>    sdk.AddApi<IClaimsApi, ClaimsApi>(</CodeLine>
  <CodeLine>        configureClient: client =&gt;</CodeLine>
  <CodeLine>            client.BaseAddress = new Uri(builder.Configuration["WexHealth:BaseUrl"]!),</CodeLine>
  <CodeLine>        configureHttpClientBuilder: http =&gt;</CodeLine>
  <CodeLine>        {</CodeLine>
  <CodeLine>            http.AddHttpMessageHandler&lt;OAuthTokenHandler&gt;();</CodeLine>
  <CodeLine>        },</CodeLine>
  <CodeLine>        configureResilience: polly =&gt;</CodeLine>
  <CodeLine>        {</CodeLine>
  <CodeLine>            polly.AddRetry(new Polly.Retry.RetryStrategyOptions&lt;HttpResponseMessage&gt;</CodeLine>
  <CodeLine>            {</CodeLine>
  <CodeLine>                MaxRetryAttempts = 3,</CodeLine>
  <CodeLine>                BackoffType = Polly.DelayBackoffType.Exponential,</CodeLine>
  <CodeLine>                Delay = TimeSpan.FromSeconds(1)</CodeLine>
  <CodeLine>            });</CodeLine>
  <CodeLine>        });</CodeLine>
  <CodeLine>    // Register every additional API your service uses the same way</CodeLine>
  <CodeLine>    sdk.AddApi&lt;IHealthApi, HealthApi&gt;(</CodeLine>
  <CodeLine>        configureClient: client =&gt;</CodeLine>
  <CodeLine>            client.BaseAddress = new Uri(builder.Configuration["WexHealth:BaseUrl"]!),</CodeLine>
  <CodeLine>        configureHttpClientBuilder: http =&gt;</CodeLine>
  <CodeLine>        {</CodeLine>
  <CodeLine>            http.AddHttpMessageHandler&lt;OAuthTokenHandler&gt;();</CodeLine>
  <CodeLine>        });</CodeLine>
  <CodeLine>});</CodeLine>
</CodeBlock>

After registration, inject `IClaimsApi` anywhere in your application — controllers, services, background workers:

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"csharp","label":"C#"}'>
  <CodeLine>public class ClaimsService(IClaimsApi api)</CodeLine>
  <CodeLine>{</CodeLine>
  <CodeLine>    public Task GetClaimAsync(Guid personId, string claimNumber, CancellationToken ct)</CodeLine>
  <CodeLine>=&gt; api.GetClaimAsync(personId, claimNumber, cancellationToken: ct);</CodeLine>
  <CodeLine>}</CodeLine>
</CodeBlock>

That is the entirety of the integration code your team owns.

`appsettings.json` — set the base URL here (never put secrets in this file):

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine>{
  "WexHealth": {
    "BaseUrl": "https://platform.uat.benefits.wexglobal.com"
  }
}</CodeLine>
</CodeBlock>

### Step 3 — Authenticate

The API uses [OAuth 2.0 Client Credentials](https://oauth.net/2/grant-types/client-credentials/) for machine-to-machine (M2M) authentication. Choose the integration path that fits your service architecture:

**Path 1: Environment variables** — quick start. The SDK auto-detects these and handles token acquisition, caching, and thread-safe refresh 60 seconds before expiry:

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"bash","label":"Bash"}'>
  <CodeLine>export WEX_OAUTH2_TOKEN_URL="https://your-auth-server.com/oauth/token"
export WEX_OAUTH2_CLIENT_ID="your-client-id"
export WEX_OAUTH2_CLIENT_SECRET="your-client-secret"</CodeLine>
</CodeBlock>

**Path 2**: `DelegatingHandler` — recommended for production. Your service owns the token lifecycle and secrets. Plug it in via the DI builder:

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"csharp","label":"C#"}'>
  <CodeLine>public interface ITokenProvider
{
    Task&lt;string&gt; GetAccessTokenAsync(CancellationToken ct);
}

// Skeleton implementation — fill in your secrets manager and token endpoint calls
public class MyTokenProvider : ITokenProvider
{
    private string? cachedToken;
    private DateTime tokenExpiry = DateTime.MinValue;
    private readonly SemaphoreSlim sync = new(1, 1);

    public async Task GetAccessTokenAsync(CancellationToken ct)
    {
        if (cachedToken != null && DateTime.UtcNow < tokenExpiry.AddSeconds(-60))
            return cachedToken;

        await sync.WaitAsync(ct);
        try
        {
            if (cachedToken != null && DateTime.UtcNow < tokenExpiry.AddSeconds(-60))
                return cachedToken;

            // Fetch credentials from your secrets manager, request a new token,
            // then set cachedToken and tokenExpiry from the response.
            return cachedToken!;
        }
        finally { sync.Release(); }
    }
}

public class OAuthTokenHandler : DelegatingHandler
{
    private readonly ITokenProvider tokenProvider;
    public OAuthTokenHandler(ITokenProvider provider) =&gt; tokenProvider = provider;
    protected override async Task&lt;HttpResponseMessage&gt; SendAsync(
        HttpRequestMessage request, CancellationToken ct)
    {
        var token = await tokenProvider.GetAccessTokenAsync(ct);
        request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
        return await base.SendAsync(request, ct);
    }
}
</CodeLine>
</CodeBlock>

Register both before `AddWexHealthSdk`. `ITokenProvider` is a singleton so the token cache is shared; `OAuthTokenHandler` is transient because `DelegatingHandler` instances are short-lived:

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"csharp","label":"C#"}'>
  <CodeLine>builder.Services.AddSingleton&lt;ITokenProvider, MyTokenProvider&gt;();</CodeLine>
  <CodeLine>builder.Services.AddTransient&lt;OAuthTokenHandler&gt;();</CodeLine>
</CodeBlock>

Secrets (Client ID, Client Secret, Token URL) belong outside `appsettings.json`: use environment variables or a secrets manager (Azure Key Vault, AWS Secrets Manager) in deployed environments.

### Step 4 — Call APIs

Every parameter is named, typed, and optional where the spec says so:

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"csharp","label":"C#"}'>
  <CodeLine>// Get a single claim</CodeLine>
  <CodeLine>ClaimDTO claim = await api.GetClaimAsync(</CodeLine>
  <CodeLine>    personId:          Guid.Parse("550e8400-e29b-41d4-a716-446655440000"),</CodeLine>
  <CodeLine>    claimNumber:       "11BPEB1210513P0000101",</CodeLine>
  <CodeLine>    xRequestId:        "my-correlation-id",  // optional — see below</CodeLine>
  <CodeLine>    cancellationToken: ct);</CodeLine>
  <CodeLine>// Get all claims for a participant (paginated)</CodeLine>
  <CodeLine>ClaimsDTO page = await api.GetClaimsForParticipantAsync(</CodeLine>
  <CodeLine>    personId:          personId,</CodeLine>
  <CodeLine>    pageSize:          25,</CodeLine>
  <CodeLine>    index:             0,</CodeLine>
  <CodeLine>    cancellationToken: ct);</CodeLine>
  <CodeLine>// page.Items    → list of ClaimDTO</CodeLine>
  <CodeLine>// page.HasNext  → bool</CodeLine>
  <CodeLine>// page.Index    → current page index</CodeLine>
  <CodeLine>// page.PageSize → page size used</CodeLine>
</CodeBlock>

**Correlation IDs** — pass your trace ID as `xRequestId` to correlate WEX platform logs with your own. Accepts up to 36 alphanumeric/hyphen characters:

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"csharp","label":"C#"}'>
  <CodeLine>await api.GetClaimAsync(personId, claimNumber,
   xRequestId: Activity.Current?.TraceId.ToString());</CodeLine>
</CodeBlock>

### Step 5 — Handle Errors

The SDK throws an `ApiException` for any non-2xx response. The error body follows [RFC 7807: Problem Details for HTTP APIs](https://datatracker.ietf.org/doc/html/rfc7807) — the same standard used natively by [ASP.NET Core](https://asp.net/) for consistent error reporting:

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"csharp","label":"C#"}'>
  <CodeLine>try
{
    var claim = await api.GetClaimAsync(personId, claimNumber, cancellationToken: ct);
    return Ok(claim);
}
catch (ApiException ex) when (ex.ErrorCode == 404) { return NotFound(); }
catch (ApiException ex)
{
    return StatusCode(ex.ErrorCode,
        new { error = ex.Message, detail = ex.ErrorContent });
}</CodeLine>
</CodeBlock>

See the [Retry Contract](https://app-staging.theneo.io/preview/69e0ee5bc0d28c7a4dacf542/69e0ee5bc0d28c7a4dacf545/sdks/overview#2--Retry-Contract---Consistent-Across-All-SDKs) table for which status codes are retried automatically before the exception reaches your code.

### Step 6 — Override Retry (optional)

The defaults (3 retries, exponential backoff with jitter, 30 s global timeout) cover the majority of cases. Override when you need different settings:

#### Option A — Per-API via configureResilience (Preferred)

Scoped to one API client, does not affect others:

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"csharp","label":"C#"}'>
  <CodeLine>sdk.AddApi(</CodeLine>
  <CodeLine>    configureClient: client =&gt;</CodeLine>
  <CodeLine>        client.BaseAddress = new Uri(builder.Configuration["WexHealth:BaseUrl"]!),</CodeLine>
  <CodeLine>    configureHttpClientBuilder: http =&gt;</CodeLine>
  <CodeLine>    {</CodeLine>
  <CodeLine>        http.AddHttpMessageHandler();</CodeLine>
  <CodeLine>    },</CodeLine>
  <CodeLine>    configureResilience: polly =&gt;</CodeLine>
  <CodeLine>    {</CodeLine>
  <CodeLine>        polly.AddTimeout(TimeSpan.FromSeconds(60));</CodeLine>
  <CodeLine>        polly.AddRetry(new Polly.Retry.RetryStrategyOptions</CodeLine>
  <CodeLine>        {</CodeLine>
  <CodeLine>            MaxRetryAttempts = 5,</CodeLine>
  <CodeLine>            BackoffType = Polly.DelayBackoffType.Exponential,</CodeLine>
  <CodeLine>            Delay = TimeSpan.FromSeconds(1)</CodeLine>
  <CodeLine>        });</CodeLine>
  <CodeLine>    });</CodeLine>
</CodeBlock>

#### Option B — Global via RetryConfiguration.HttpPipeline

Replaces the pipeline for every SDK client in the process. Use only when you want a uniform policy across all APIs and have not set `configureResilience` on any `AddApi` call:

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"csharp","label":"C#"}'>
  <CodeLine>// ⚠️ Global — affects IClaimsApi, IHealthApi, and every other registered SDK client</CodeLine>
  <CodeLine>RetryConfiguration.HttpPipeline = RetryConfiguration.CreatePipeline(</CodeLine>
  <CodeLine>    maxRetries: 5,</CodeLine>
  <CodeLine>    timeoutSeconds: 60</CodeLine>
  <CodeLine>);  </CodeLine>
</CodeBlock>

### Step 7 — Logging

`ILogger<T>` is resolved from DI automatically — no extra wiring needed. Control verbosity per SDK namespace in `appsettings.json`:

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine>{
  "Logging": {
    "LogLevel": {
      "WexHealth":                           "Information",
      "WexHealth.Client.RetryConfiguration": "Warning"
    }
  }
}</CodeLine>
</CodeBlock>

<Table style="width:100%;min-width:100%" colSizes='["initial","initial"]' isHeaderAdded='false' tableHeader='[{"id":"aa61fb30-6fdc-4a93-b228-72da3b9414b6","title":"Title"},{"id":"a9dca697-925d-4cbf-849e-e9f2938992fc","title":"Description"}]'>
  <table-row>
    <table-cell>Log Category</table-cell>
    <table-cell>What is logged</table-cell>
  </table-row>
  <table-row>
    <table-cell>WexHealth.Api.ClaimsApi</table-cell>
    <table-cell>Method call start, completion, HTTP status code</table-cell>
  </table-row>
  <table-row>
    <table-cell>WexHealth.Client.ApiClient</table-cell>
    <table-cell>HTTP request / response details</table-cell>
  </table-row>
  <table-row>
    <table-cell>WexHealth.Client.RetryConfiguration</table-cell>
    <table-cell>Retry attempt number, delay, reason, sanitized URI</table-cell>
  </table-row>
</Table>

Never log raw `Authorization` headers, token values, or response bodies containing participant data. Use `Information` or `Warning` in production — never `Trace`.

### Step 8 — Health Check

Wire the SDK's liveness endpoint into [ASP.NET Core](https://asp.net/) health checks to surface WEX platform availability in your own `/health` probe:

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"csharp","label":"C#"}'>
  <CodeLine>builder.Services.AddHealthChecks()</CodeLine>
  <CodeLine>    .AddCheck&lt;WexHealthCheck&gt;("wexhealth-api");</CodeLine>
  <CodeLine>app.MapHealthChecks("/health");</CodeLine>
  <CodeLine>public class WexHealthCheck(IHealthApi healthApi) : IHealthCheck</CodeLine>
  <CodeLine>{</CodeLine>
  <CodeLine>    public async Task&lt;HealthCheckResult&gt; CheckHealthAsync(</CodeLine>
  <CodeLine>        HealthCheckContext context, CancellationToken ct)</CodeLine>
  <CodeLine>    {</CodeLine>
  <CodeLine>        try   </CodeLine>
  <CodeLine>        { </CodeLine>
  <CodeLine>            await healthApi.GetLivenessAsync(cancellationToken: ct);</CodeLine>
  <CodeLine>            return HealthCheckResult.Healthy(); </CodeLine>
  <CodeLine>        }</CodeLine>
  <CodeLine>        catch (Exception ex)</CodeLine>
  <CodeLine>        {</CodeLine>
  <CodeLine>            return HealthCheckResult.Unhealthy("WexHealth unreachable", ex);</<CodeLine>
  <CodeLine>        }</CodeLine>
  <CodeLine>     }</CodeLine>
  <CodeLine>}</CodeLine>
</CodeBlock>

.NET

The concepts from the .NET section all apply here. This section covers the specifics for the JS/TS SDK.

Install
-------

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"javascript","label":"JavaScript"}'>
  <CodeLine>npm install @wexinc/wex-health-sdk</CodeLine>
</CodeBlock>

Pin to a minor-compatible range so you receive non-breaking updates automatically:

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"javascript","label":"JavaScript"}'>
  <CodeLine>"dependencies": {
  "@wexinc/wex-health-sdk": "^1.0.10"
}</CodeLine>
</CodeBlock>

Configure
---------

Create **one** <span style="color:rgb(41, 42, 46);background-color:rgba(5, 21, 36, 0.06)">`Configuration`</span> object at startup and pass it to every API class. Do not create a new instance per request — this defeats token caching and issues a fresh OAuth token on every call.

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"javascript","label":"JavaScript"}'>
  <CodeLine>// config.ts
import { Configuration } from '@wexinc/wex-health-sdk';</CodeLine>

  <CodeLine>
    export const sdkConfig = new Configuration({
      basePath: 'https://platform.uat.benefits.wexglobal.com',
      oauth2Credentials: {
        clientId: process.env.WEX_CLIENT_ID!,
        clientSecret: process.env.WEX_CLIENT_SECRET!,
        accessTokenUrl: process.env.WEX_TOKEN_URL!,
        audience: process.env.WEX_AUDIENCE, // optional
        scopes: ['claims:read', 'consumers:read'], // optional
      },
    });
  </CodeLine>
</CodeBlock>

Call APIs
---------

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"javascript","label":"JavaScript"}'>
  <CodeLine>
      import { ClaimsApi, ConsumersApi } from '@wexinc/wex-health-sdk';
import { sdkConfig } from './config';

      const claimsApi    = new ClaimsApi(sdkConfig);
      const consumersApi = new ConsumersApi(sdkConfig);

      // Single claim — third arg is optional xRequestId for tracing
      const { data: claim } = await claimsApi.getClaim(
          'person-uuid-here', '11BPEB1210513P0000101', 'my-correlation-id');

      // All claims for a participant
      const { data: claims } = await claimsApi.getClaimsForParticipant('person-uuid-here');

      // Consumer profile
      const { data: consumer } = await consumersApi.getConsumer('consumer-uuid-here');
  </CodeLine>
</CodeBlock>

Handle Errors
-------------

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"javascript","label":"JavaScript"}'>
  <CodeLine>
    try {
    const { data } = await claimsApi.getClaim(personId, claimNumber);
} 
catch (error: any) {
    if (error.response) {
      // error.response.data is typed as ProblemDetails
      console.error(`API error ${error.response.status}:`, error.response.data);
    } else {
      console.error('Network error:', error.message);
    }
   }
  </CodeLine>
</CodeBlock>

Retry overrides (see [Retry Contract](https://app-staging.theneo.io/preview/69e0ee5bc0d28c7a4dacf542/69e0ee5bc0d28c7a4dacf545/sdks/overview#2--Retry-Contract---Consistent-Across-All-SDKs) for defaults):

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"javascript","label":"JavaScript"}'>
  <CodeLine>
    const config = new Configuration({
      // ...
      retryConfig: {
        retries: 5,
        retryCondition: (err: any) => [500, 502, 503, 408].includes(err.response?.status),
      },
    });
  </CodeLine>
</CodeBlock>

Logging
-------

Logging is **off by default**. Pass a logger in the <span style="color:rgb(41, 42, 46);background-color:rgba(5, 21, 36, 0.06)">`Configuration`</span> constructor — setting it after construction will not be picked up by retry callbacks.

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"javascript","label":"JavaScript"}'>
  <CodeLine>
    import { Configuration, ConsoleLogger, LogLevel } from '@wexinc/wex-health-sdk';

    const sdkConfig = new Configuration({
      // ...
      logger: new ConsoleLogger(LogLevel.Information), // use Warning or Information in production
    });
  </CodeLine>
</CodeBlock>

Log levels: <span style="color:rgb(41, 42, 46);background-color:rgba(5, 21, 36, 0.06)">`Trace`</span> (0) · <span style="color:rgb(41, 42, 46);background-color:rgba(5, 21, 36, 0.06)">`Debug`</span> (1) · <span style="color:rgb(41, 42, 46);background-color:rgba(5, 21, 36, 0.06)">`Information`</span> (2) · <span style="color:rgb(41, 42, 46);background-color:rgba(5, 21, 36, 0.06)">`Warning`</span> (3) · <span style="color:rgb(41, 42, 46);background-color:rgba(5, 21, 36, 0.06)">`Error`</span> (4) · <span style="color:rgb(41, 42, 46);background-color:rgba(5, 21, 36, 0.06)">`Critical`</span> (5) · <span style="color:rgb(41, 42, 46);background-color:rgba(5, 21, 36, 0.06)">`None`</span> (6). Never use <span style="color:rgb(41, 42, 46);background-color:rgba(5, 21, 36, 0.06)">`Trace`</span> in production.

To plug in your own logger (Winston, Pino, etc.), implement the <span style="color:rgb(41, 42, 46);background-color:rgba(5, 21, 36, 0.06)">`ILogger`</span> interface:

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"javascript","label":"JavaScript"}'>
  <CodeLine>
    import { ILogger, LogLevel } from '@wexinc/wex-health-sdk';

    class WinstonAdapter implements ILogger {
      isEnabled(level: LogLevel) { return level &gt;= LogLevel.Information; }
      log(level: LogLevel, message: string, ...args: any[]) {
        winston.info(message, ...args);
      }
    }
  </CodeLine>
</CodeBlock>

JavaScript

The same concepts apply. This section covers the Java-specific install, configuration, and patterns.

Install
-------

### **Maven**

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"xml","label":"XML"}'>
  <CodeLine>&lt;dependency&gt;</Codeline>
<CodeLine>    &lt;groupId&gt;com.wexinc&lt;/groupId&gt;</CodeLine>
<CodeLine>    &lt;artifactId&gt;wex-health-sdk&lt;artifactId&gt;</CodeLine>
<CodeLine>    &lt;version&gt;1.0.16&lt;/version&gt;</CodeLine>
<CodeLine>&lt;/dependency&gt;</CodeLine>
  <CodeLine>&lt;dependency&gt;</CodeLine>
<CodeLine>    &lt;groupId&gt;com.wexinc&lt;/groupId&gt;
<CodeLine>    &lt;artifactId&gt;wex-health-sdk&lt;/artifactId&gt;
<CodeLine>    &lt;version&gt;1.0.16&lt;/version&gt;
<CodeLine>&lt;/dependency&gt;</CodeLine>
</CodeBlock>

Configure
---------

Register <span style="color:rgb(41, 42, 46);background-color:rgba(5, 21, 36, 0.06)">`ApiClient`</span> as a Spring <span style="color:rgb(41, 42, 46);background-color:rgba(5, 21, 36, 0.06)">`@Bean`</span> (singleton by default). All API classes share the same instance and the same cached token:

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"java","label":"Java"}'>
  <CodeLine>
    @Configuration
  public class WexHealthConfig {
    
      @Value("${wex.health.base-path}")
      private String basePath;

      @Bean
      public ApiClient wexApiClient() {
          ApiClient apiClient = new ApiClient();
          apiClient.setBasePath(basePath);
          // OAuth2 auto-configured from WEX_OAUTH2_* environment variables
          return apiClient;
      }

      @Bean
      public ClaimsApi claimsApi(ApiClient apiClient) {
          return new ClaimsApi(apiClient);
      }
    }
  </CodeLine>
</CodeBlock>

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"yaml","label":"YAML"}'>
  <CodeLine># application.yml
  wex:
    health:
      base-path: https://platform.uat.benefits.wexglobal.com
    oauth2:
      token-url: ${WEX_OAUTH2_TOKEN_URL}
      client-id: ${WEX_OAUTH2_CLIENT_ID}
      client-secret: ${WEX_OAUTH2_CLIENT_SECRET}</CodeLine>
</CodeBlock>

To provide a bearer token manually when your service manages its own token lifecycle:

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"java","label":"Java"}'>
  <CodeLine>HttpBearerAuth bearerAuth = (HttpBearerAuth) apiClient.getAuthentication("bearerAuth");
bearerAuth.setBearerToken("your-bearer-token");</CodeLine>
</CodeBlock>

Call APIs
---------

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"java","label":"Java"}'>
  <CodeLine>
    // Single claim — pass a correlation ID as the third argument
    ClaimDTO claim = claimsApi.getClaim(personId, claimNumber, UUID.randomUUID().toString())
      .toEntity(ClaimDTO.class)
      .getBody();
    // Paginated claims
    ClaimsDTO claims = claimsApi.getClaimsForParticipant(personId, 0, 50, "DESC", requestId)
      .toEntity(ClaimsDTO.class)
      .getBody();
    // Health check
    boolean isHealthy = new HealthApi(apiClient).getLiveness()
      .toBodilessEntity().getStatusCode().is2xxSuccessful();
  </CodeLine>
</CodeBlock>

Handle Errors
-------------

Retry (see [<span style="color:rgb(24, 104, 219)"><u>Retry Contract</u></span>](https://app-staging.theneo.io/preview/69e0ee5bc0d28c7a4dacf542/69e0ee5bc0d28c7a4dacf545/sdks/overview#2--Retry-Contract---Consistent-Across-All-SDKs)) runs automatically before any exception reaches your code.

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"java","label":"Java"}'>
  <CodeLine>
    try {
      return claimsApi.getClaim(personId, claimNumber, requestId)
            .toEntity(ClaimDTO.class).getBody();
    } catch (HttpClientErrorException e) {
        // 4xx — bad request, not found, unauthorized
        log.error("Client error: {} - {}", e.getStatusCode(), e.getResponseBodyAsString());
        throw new BusinessException("Invalid request", e);
    } catch (HttpServerErrorException e) {
        // 5xx — reached here only after all retries exhausted
        log.error("Server error: {} - {}", e.getStatusCode(), e.getResponseBodyAsString());
        throw new ServiceException("Service unavailable", e);
    }
  </CodeLine>
</CodeBlock>

Logging
-------

Add an SLF4J binding (Logback recommended) and logs appear automatically — no additional configuration needed:

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"xml","label":"XML"}'>
  <CodeLine>&lt;dependency&gt;</CodeLine>
  <CodeLine>    &lt;groupId&gt;ch.qos.logback&lt;/groupId&gt;</CodeLine>
  <CodeLine>    &lt;artifactId>logback-classic&lt;/artifactId&gt;</CodeLine>
  <CodeLine>&lt;/dependency&gt; </CodeLine>
</CodeBlock>

Java

Install
-------

<CodeBlock attributes='{"isFitToPage":false,"style":{},"lang":"bash","label":"Bash"}'>
  <CodeLine>pip install wex-health-sdk</CodeLine>
</CodeBlock>

Configure
---------

Create one <span style="color:rgb(41, 42, 46);background-color:rgba(5, 21, 36, 0.06)">`ApiClient`</span> at application startup. In FastAPI, use the <span style="color:rgb(41, 42, 46);background-color:rgba(5, 21, 36, 0.06)">`lifespan`</span> hook to share it across all requests:

<CodeBlock attributes='{"isFitToPage":false,"style":{},"lang":"python","label":"Python"}'>
    <CodeLine>
        import os, wex_health
        from contextlib import asynccontextmanager
        from fastapi import FastAPI
    </CodeLine>
    <CodeLine>
        config = wex_health.Configuration(
            host=os.environ["WEX_API_HOST"],
            oauth2_credentials={
                "client_id":        os.environ["WEX_CLIENT_ID"],
                "client_secret":    os.environ["WEX_CLIENT_SECRET"],
                "access_token_url": os.environ["WEX_TOKEN_URL"],
            },
            retries=3, # default — override as needed
            request_timeout=30.0,
        )
    </CodeLine>
    <CodeLine>
        @asynccontextmanager
        async def lifespan(app: FastAPI):
            app.state.wex_client = wex_health.ApiClient(config)
            await app.state.wex_client.__aenter__()
            yield
            await app.state.wex_client.__aexit__(None, None, None)
    </CodeLine>
</CodeBlock>

For non-FastAPI applications, use <span style="color:rgb(41, 42, 46);background-color:rgba(5, 21, 36, 0.06)">`async with ApiClient(config) as client:`</span> and keep that client alive for the lifetime of the process.

Call APIs
---------

<CodeBlock attributes='{"isFitToPage":false,"style":{},"lang":"python","label":"Python"}'>
  <CodeLine>
    async with ApiClient(config) as client:
        claims_api = ClaimsApi(client)
    </CodeLine>
    <CodeLine>
        # Single claim
        claim = await claims_api.get_claim(
            person_id="person-uuid-here",
            claim_number="11BPEB1210513P0000101",
            x_request_id="my-correlation-id"   # optional — for tracing
        )
    </CodeLine>
    <CodeLine>
        # All claims for a participant
        claims = await claims_api.get_claims_for_participant(
            person_id="person-uuid-here",
            x_request_id="correlation-123"
        )
    </CodeLine>
</CodeBlock>

Handle Errors
-------------

<CodeBlock attributes='{"isFitToPage":false,"style":{},"lang":"python","label":"Python"}'>
  <CodeLine>
    from wex_health.rest import ApiException
  </CodeLine>
  <CodeLine>
    try:
        return await api.get_consumer(consumer_id=consumer_id)
    except ApiException as e:
        if e.status == 401:
            raise AuthenticationError("Invalid credentials")
        elif e.status == 404:
            return None  # resource does not exist — not retried
        elif e.status == 429:
            raise RateLimitError("Too many requests")
        raise  # 5xx will have been retried before reaching here
  </CodeLine>
</CodeBlock>

Logging
-------

The SDK integrates with Python's standard <span style="color:rgb(41, 42, 46);background-color:rgba(5, 21, 36, 0.06)">`logging`</span> module:

<CodeBlock attributes='{"isFitToPage":false,"style":{},"lang":"python","label":"Python"}'>
  <CodeLine>import logging
logging.getLogger("wex_health").setLevel(logging.INFO)</CodeLine>
</CodeBlock>

Python

*   \[ \] Credentials stored in environment variables or a secrets vault — not in source code
    
*   \[ \] Integrating against different env credentials requested only after sign-off with the API team
    
*   \[ \] One shared client / configuration instance created at startup (singleton pattern confirmed)
    
*   \[ \] Error handling covers 401, 403, 404, 408, 429, and 5xx
    
*   \[ \] Correlation IDs (`xRequestId`) passed on all calls for end-to-end traceability
    
*   \[ \] Log level set to `Warning` or `Information` in production — never `Trace`
    
*   \[ \] No raw `Authorization` headers, tokens, or participant data written to logs
    
*   \[ \] SDK / package version pinned and kept up to date

Pre-Launch Checklist

Thank you for helping us improve the Wex Health developer experience! This document outlines the process for reporting issues across our SDK ecosystem (Java, Python, JavaScript/TypeScript, and .NET).

How to Report an Issue
----------------------

Since our SDK source repositories are hosted privately, we provide a centralized triage process via our Developer Portal.

### Step 1: Submit a Report

Please visit the [Wex Health Developer Support Portal](https://developers.wexhealth.com/support/sdk-issues) to submit a bug report or feature request.

### Step 2: Provide a “Minimum Reproducible Example”

Developers hate vague reports like "It doesn't work." To help us resolve your issue quickly, please provide:

*   **Your Environment**: Language version (Node version, Python version, and so on), OS, and SDK version.
    
*   **The Exact Error Message**: The full stack trace or the specific error returned by the SDK.
    
*   **A Small Code Snippet**: A minimal, self-contained piece of code that triggers the bug.
    

### Bug Report Template

Please copy and fill out this template when submitting your report via the portal:

**SDK Type**: \[for example, Java, Python, JS, .NET\]

**SDK Version**: \[for example, 0.1.0a1\]

**Environment Details**: Runtime: \[for example, Node.js 20.x, Python 3.11, JDK 17\]

**OS**: \[for example, Windows 11, macOS, Linux\]

**Issue Description**: \[A brief description of the bug.\]

#### Exact Error Message:

<CodeBlock attributes='{"isFitToPage":false,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>[Paste full error/stack trace here] </CodeLine>
</CodeBlock>

#### Minimum Reproducible Snippet:

<CodeBlock attributes='{"isFitToPage":false,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>// Paste the small code snippet/descriptive steps that triggers the bug here </CodeLine>
</CodeBlock>

Feature Requests
----------------

We welcome suggestions for improvements. When submitting a feature request, please include:

*   **Motivation**: Why is this feature needed?
    
*   **Proposed Usage**: A short example of how you'd like the new API to look.
    

Security Disclosures
--------------------

If you have identified a security vulnerability, please do not report it via the standard support form. Instead, follow our [Security Disclosure Policy](https://developers.wexhealth.com/security) or email: [gl-sdk-support@wexinc.com](https://gl-sdk-support@wexinc.com) .

Contact
-------

For general developer support and SDK inquiries: gl-sdk-support@wexinc.com

<Table style="width:100%;min-width:100%" colSizes='["initial","initial"]' isHeaderAdded='false' tableHeader='[{"id":"d1ddaaba-c67a-4656-b1f7-a021a3e519fa","title":"Title"},{"id":"dae34301-24ef-4422-b9e8-b0d36ba8cd02","title":"Description"}]'>
  <table-row>
    <table-cell>Need</table-cell>
    <table-cell>Contact</table-cell>
  </table-row>
  <table-row>
    <table-cell>API credentials & onboarding</table-cell>
    <table-cell>Contact the API team you are integrating with</table-cell>
  </table-row>
  <table-row>
    <table-cell>Bug reports / feature requests</table-cell>
    <table-cell>See /docs folder and SDK release notes. Contact gl-sdk-support@wexinc.com</table-cell>
  </table-row>
  <table-row>
    <table-cell>General developer support and SDK inquiries</table-cell>
    <table-cell>gl-sdk-support@wexinc.com</table-cell>
  </table-row>
  <table-row>
    <table-cell>API endpoint reference</table-cell>
    <table-cell>See /docs folder for per-endpoint documentation</table-cell>
  </table-row>
  <table-row>
    <table-cell>Model reference</table-cell>
    <table-cell>ClaimDTO, ReceiptDTO, and others documented in /docs</table-cell>
  </table-row>
</Table>

Support

WEX Software Development Kit (SDK) License Agreement v.4.1.26

1.  SDK LICENSE AGREEMENT
    

This Software Development Kit (SDK) License Agreement (Agreement) is between you (both the individual downloading the SDK and any legal entity on behalf of which such individual is acting) (You or Your) and WEX Inc. (WEX).

IT IS IMPORTANT THAT YOU READ CAREFULLY AND UNDERSTAND THIS AGREEMENT. BY CLICKING THE “I ACCEPT” BUTTON OR AN EQUIVALENT INDICATOR OR BY DOWNLOADING, INSTALLING OR USING THE SDK OR THE DOCUMENTATION, YOU AGREE TO BE BOUND BY THIS AGREEMENT, AND IF ACTING ON BEHALF OF A LEGAL ENTITY ALSO REPRESENT AND WARRANT THAT YOU AS AN INDIVIDUAL HAVE THE LEGAL AUTHORITY TO BIND SUCH LEGAL ENTITY TO THIS AGREEMENT. IF YOU DO NOT HAVE SUCH AUTHORITY OR DO NOT AGREE TO BE BOUND BY THIS AGREEMENT YOU WILL NOT BE PERMITTED TO (AND YOU WILL HAVE NO RIGHT TO) DOWNLOAD, INSTALL OR USE THE SDK OR THE DOCUMENTATION.

1.  DEFINITIONS 1.1 “Application(s)” means software programs that You develop to operate with the Gateway using components of the SDK. 1.2 “Documentation” means the materials made available to You in connection with the SDK by or on behalf of WEX pursuant to this Agreement. 1.3 “Gateway” means any electronic platform maintained and operated by WEX and any of its affiliates. 1.4 “SDK” means the software development kit, including all software made available to You by or on behalf of WEX pursuant to this Agreement, including but not limited to sample source code, code snippets, software tools, code libraries, sample applications, Documentation and any upgrades, modified versions, updates, and/or additions thereto, if any, made available to You by or on behalf of WEX pursuant to this Agreement.
    
2.  GRANT OF LICENSE; RESTRICTIONS 2.1 Limited License. Subject to and conditioned upon Your compliance with the terms of this Agreement, WEX hereby grants to You a limited, revocable, non-exclusive, non-transferable, royalty-free license during the term of this Agreement to:(a) within the United States, use the SDK solely for the purpose of developing, testing and manufacturing Applications;(b) distribute, sell or otherwise provide Your Applications that include components of the SDK to Your end users; and© use the Documentation in connection with the foregoing activities.The license to distribute Applications that include components of the SDK as set forth in subsection (b) above includes the right to grant sublicenses to Your end users to use such components of the SDK as incorporated into such Applications, subject to the limitations and restrictions set forth in this Agreement. 2.2 Restrictions. You shall not (and shall have no right to): (a) make or distribute copies of the SDK or the Documentation, in whole or in part, except as expressly permitted pursuant to Section 2.1; (b) reverse engineer, decompile, or disassemble the SDK; © alter or remove any copyright, trademark, trade name or other proprietary notices, legends, symbols or labels appearing on or in the SDK or Documentation; (d) sublicense (or purport to sublicense) the SDK or the Documentation, in whole or in part, to any third party except as expressly permitted pursuant to Section 2.1; (e) engage in any activity with the SDK, including the development or distribution of an Application, that is illegal, or interferes with, disrupts, damages, circumvents security or access controls, or accesses in an unauthorized manner the Gateway, SDK, or platform, servers, or systems of WEX, any of its affiliates, or any third party; (f) make any statements that Your Application is “certified” or otherwise endorsed, or that its performance is guaranteed, by WEX or any of its affiliates; or (g) otherwise use or exploit the SDK or the Documentation for any purpose other than to develop and distribute Applications as expressly permitted by this Agreement. 2.3 Ownership. You shall retain ownership of Your Applications developed in accordance with this Agreement, subject to WEX’s ownership of the SDK and Documentation (including WEX’s ownership of any portion of the SDK or Documentation incorporated in Your Applications). You acknowledge and agree that all right, title and interest in and to the SDK and Documentation shall, at all times, be and remain the exclusive property of WEX and that You do not have or acquire any rights, express or implied, in the SDK or Documentation except those rights expressly granted under this Agreement. 2.4 No Support, Upgrades. WEX has no obligation to, but may in its sole discretion, provide support, maintenance, upgrades, modifications or new releases of the SDK. If WEX makes any upgrades, modifications or new releases available, prior version(s)of the SDK may cease to function and You may need to adopt the current version for continued use of the SDK. 2.5 License to WEX. In the event You choose to submit any suggestions, feedback or other information or materials related to the SDK or Documentation or Your use thereof (collectively, “Feedback”) to WEX, You hereby grant to WEX a worldwide, non-exclusive, royalty-free, transferable, sublicensable, perpetual and irrevocable license to use and otherwise exploit such Feedback in connection with the SDK, Documentation, and other products and services. 2.6 Use. (a) You represent, warrant and agree to use the SDK and write Applications only for purposes permitted by (i) this Agreement; (ii) applicable law and regulation, including, without limitation, the Payment Card Industry Data Security Standard (PCI DSS), and the Health Insurance Portability and Accountability Act of 1996 and Health Information Technology for Economic and Clinical Health Act including their implementing regulations, as amended (collectively “HIPAA”); and (iii) industry standards or guidelines in the relevant jurisdictions. (b) You represent, warrant and agree that if You use the SDK to develop Applications for end users, that You will protect the privacy and legal rights of those users. If the Application receives or stores personal or sensitive information provided by end users, it must do so securely and in compliance with all applicable laws and regulations, including without limitation privacy and banking laws, card association regulations, and HIPAA. If You use the SDK to access or share any personal data, You acknowledge and agree that You shall access or share personal data only with consent as required by applicable law and only when, and for the limited purposes for which, the individual has given You permission to do so. © You represent, warrant and agree that You are solely responsible for (and that neither WEX nor its affiliates have any responsibility to You or to any third party for): (i) any data, content, or resources that You obtain, transmit or display via the Application; and (ii) any breach of Your obligations under this Agreement, any applicable third party license, or any applicable law or regulation, and for the consequences of any such breach.
    
3.  WARRANTY DISCLAIMER; LIMITATION OF LIABILITY 3.1 Disclaimer. THE SDK AND THE DOCUMENTATION ARE PROVIDED ON AN “AS IS” AND “AS AVAILABLE” BASIS WITH NO WARRANTIES. YOU AGREE THAT YOUR USE OF THE SDK AND THE DOCUMENTATION IS AT YOUR SOLE RISK AND YOU ARE SOLELY RESPONSIBLE FOR ANY DAMAGE TO YOUR COMPUTER SYSTEM OR OTHER DEVICE OR LOSS OF DATA THAT RESULTS FROM SUCH USE. TO THE FULLEST EXTENT PERMISSIBLE UNDER APPLICABLE LAW, WEX AND ITS AFFILIATES EXPRESSLY DISCLAIM ALL WARRANTIES OF ANY KIND, EXPRESS OR IMPLIED, WITH RESPECT TO THE SDK AND THE DOCUMENTATION, INCLUDING ALL WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, SATISFACTORY QUALITY, ACCURACY, TITLE AND NON-INFRINGEMENT, AND ANY WARRANTIES THAT MAY ARISE OUT OF COURSE OF PERFORMANCE, COURSE OF DEALING OR USAGE OF TRADE. NEITHER WEX NOR ITS AFFILIATES WARRANT THAT THE FUNCTIONS OR INFORMATION CONTAINED IN THE SDK OR THE DOCUMENTATION WILL MEET ANY REQUIREMENTS OR NEEDS YOU MAY HAVE, OR THAT THE SDK OR DOCUMENTATION WILL OPERATE ERROR FREE, OR THAT THE SDK OR DOCUMENTATION IS COMPATIBLE WITH ANY PARTICULAR OPERATING SYSTEM. 3.2 Limitation of Liability. IN NO EVENT SHALL WEX AND ITS AFFILIATES BE LIABLE FOR ANY INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL OR PUNITIVE DAMAGES, OR DAMAGES FOR LOSS OF PROFITS, REVENUE, BUSINESS, SAVINGS, DATA, USE OR COST OF SUBSTITUTE PROCUREMENT, INCURRED BY YOU OR ANY THIRD PARTY, WHETHER IN AN ACTION IN CONTRACT OR TORT, EVEN IF WEX HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES OR IF SUCH DAMAGES ARE FORESEEABLE. IN NO EVENT SHALL THE ENTIRE LIABILITY OF WEX AND AFFILIATES ARISING FROM OR RELATING TO THIS AGREEMENT OR THE SUBJECT MATTER HEREOF EXCEED ONE HUNDRED U.S. DOLLARS ($100). THE PARTIES ACKNOWLEDGE THAT THE LIMITATIONS OF LIABILITY IN THIS SECTION 3.2 AND IN THE OTHER PROVISIONS OF THIS AGREEMENT AND THE ALLOCATION OF RISK HEREIN ARE AN ESSENTIAL ELEMENT OF THE BARGAIN BETWEEN THE PARTIES, WITHOUT WHICH WEX WOULD NOT HAVE ENTERED INTO THIS AGREEMENT.
    
4.  INDEMNIFICATION You shall indemnify, hold harmless and, at WEX’s request, defend WEX and its affiliates and their officers, directors, employees, and agents from and against any claim, suit or proceeding, and any associated liabilities, costs, damages and expenses, including reasonable attorneys’ fees, that arise out of or relate to: (i) Your Applications or the use or distribution thereof and Your use or distribution of the Gateway, SDK, or the Documentation (or any portion thereof), including, but not limited to, any allegation that any such Application or any such use or distribution infringes, misappropriates or otherwise violates any intellectual property (including, without limitation, copyright, patent, and trademark), privacy, publicity or other rights of any third party, or has caused the death or injury of any person or damage to any property; (ii) Your alleged or actual breach of this Agreement; (iii) the alleged or actual breach of this Agreement by any party to whom You have provided Your Applications, the Gateway, SDK, or the Documentation or (iv) Your alleged or actual violation of or non-compliance with any applicable laws, legislation, policies, rules, regulations or governmental requirements.
    
5.  TERM AND TERMINATION This Agreement and the licenses granted to You herein are effective until terminated. WEX may terminate this Agreement, or discontinue or suspend the SDK or any portion or feature thereof and the licenses granted to You, at any time, with or without notice, and without liability or other obligation to You. Upon termination of this Agreement, You shall cease all use of the SDK and the Documentation, return to WEX or destroy all copies of the SDK and Documentation and related materials in Your possession, and so certify to WEX upon request. Except for the license to You granted herein, the terms of this Agreement shall survive termination.
    
6.  CONFIDENTIAL INFORMATION a. You hereby agree (i) to hold WEX’s Confidential Information in strict confidence and to take reasonable precautions to protect such Confidential Information (including, without limitation, and without limiting the foregoing, all precautions You employ with respect to Your own confidential materials), (ii) not to divulge any such Confidential Information to any third person; (iii) not to make any use whatsoever at any time of such Confidential Information except as strictly licensed hereunder, (iv) not to remove or export from the United States or re-export any such Confidential Information or any direct product thereof. b. “Confidential Information” shall mean any data or information, oral or written, treated as confidential that relates to WEX’s past, present, or future research, development or business activities, including without limitation any current or unannounced products and services, any information relating to services, developments, inventions, trade secrets, processes, plans, financial information, customer or personal data, revenue, transaction volume, forecasts, projections, application programming interfaces, SDK, and Documentation.
    
7.  GENERAL TERMS 7.1 Law. This Agreement and all matters arising out of or relating to this Agreement shall be governed by the internal laws of the State of Delaware without giving effect to any choice of law rule. This Agreement shall not be governed by the United Nations Convention on Contracts for the International Sales of Goods, the application of which is expressly excluded. In the event of any controversy, claim or dispute between the parties arising out of or relating to this Agreement, such controversy, claim or dispute shall be resolved in binding arbitration. You and WEX agree that, by entering into this Agreement all parties are waiving their respective rights to a trial by jury or to participate in a class or representative action. THE PARTIES AGREE THAT EACH MAY BRING COMMERCIAL CLAIMS AGAINST THE OTHER ONLY IN ITS INDIVIDUAL CAPACITY, AND NOT AS A PLAINTIFF OR CLASS MEMBER IN ANY PURPORTED CLASS, REPRESENTATIVE, OR PRIVATE ATTORNEY GENERAL PROCEEDING. You may bring a commercial claim only on Your own behalf and cannot seek relief that would affect other parties. If there is a final judicial determination that any particular commercial claim (or a request for particular relief) cannot be arbitrated in accordance with this paragraph’s limitations, then only that commercial claim (or only that request for relief) may be brought in court. All other commercial claims (or requests for relief) remain subject to this paragraph. 7.2 No use of Marks. Nothing in the Agreement gives You a right to use any of WEX’s trade names, trademarks, service marks, logos, domain names, or other distinctive brand features. 7.3 Severability and Waiver. If any provision of this Agreement is held to be illegal, invalid, or otherwise unenforceable, such provision shall be modified to the minimum extent necessary to render it enforceable and most clearly reflect the intent of the original provision, and the remainder of this Agreement shall continue in full force and effect. Any inaction or waiver by either party of any default or breach of this Agreement shall not constitute a waiver of any other or subsequent default or breach. 7.4 No Assignment. You may not assign, sell, transfer, delegate or otherwise dispose of, whether voluntarily or involuntarily, by operation of law or otherwise, this Agreement or any rights or obligations under this Agreement without the prior written consent of WEX, which may be withheld in WEX’s sole discretion. Any purported assignment, transfer or delegation by You shall be null and void. Subject to the foregoing, this Agreement shall be binding upon and shall inure to the benefit of the parties and their respective successors and assigns. 7.5 Government Rights. If You (or any person or entity to whom You provide the SDK or Documentation) are an agency or instrumentality of the United States Government, the SDK and Documentation are “commercial computer software” and “commercial computer software documentation,” and pursuant to FAR 12.212 or DFARS 227.7202, and their successors, as applicable, use, reproduction and disclosure of the SDK and Documentation are governed by the terms of this Agreement. 7.6 Privacy. In order to continually innovate and improve the SDK, Licensee understands and agrees that WEX may collect anonymized data, certain usage statistics including but not limited to a unique identifier, associated IP address, version number of software, and information on which tools and/or services in the SDK are being used and how they are being used. 7.7 Headings. The headings to the Sections and Subsections of this Agreement are for convenience only and shall not affect the meaning of the language included therein. 7.8 Entire Agreement; Amendments. This Agreement constitutes the entire agreement between the parties and supersedes all prior or contemporaneous agreements or representations, written or oral, concerning the subject matter of this Agreement. WEX may make changes to this Agreement, SDK or Documentation in its sole discretion. When these changes are made, WEX will make a new version of the Agreement, SDK, or Documentation available on the website where the SDK is available. This Agreement may not be modified or amended by You except in a writing signed by a duly authorized representative of each party. You acknowledge and agree that WEX has not made any representations, warranties or agreements of any kind, except as expressly set forth herein. 7.9 Relationship of the Parties. You and WEX are independent contractors with regard to each other. This Agreement does not create any third-party beneficiary rights or any agency, partnership, employment, or joint venture.
    

BY CLICKING “I ACCEPT,” “I AGREE” OR AN EQUIVALENT INDICATOR OR BY DOWNLOADING, INSTALLING OR USING THE SDK OR THE DOCUMENTATION, YOU ACKNOWLEDGE AND AGREE THAT (1) YOU (AS DEFINED ABOVE) HAVE READ AND REVIEWED THIS AGREEMENT IN ITS ENTIRETY, (2) YOU AGREE TO BE BOUND BY THIS AGREEMENT, AND (3) YOU HAVE THE POWER, AUTHORITY AND LEGAL RIGHT TO ENTER INTO THIS AGREEMENT.

License Agreement

Default

Wex Health API

ClientID

Wex Health API Documentation

Production

Accounting

Archive Bank Account

Get Card By Id

Get Cards

List Bank Accounts

Update Card Status

Claims

Download File From Cloud With Person Id

Get Claim By Claim Number

Get Claims

Get Expense Categories And Types

Get Payees For Participant

Get Receipt For Participant

Get Receipts For Participant

Update Denial

Upload File To Cloud With Person Id

Reimbursement Methods

List Reimbursement Methods

Spending Accounts

List Spending Accounts

Transactions

List Transactions

Messages

Get Message

Get Messages

Update Message

Termination

Create Termination Request

Elections

Get Election

List Elections

Enrollments

Get Enrollment

List Enrollments

Plan Years

Create Plan Year

Get Plan Year

List Plan Years

Update Plan Year

Plans

Create Plan

Get Plan

List Plans

Update Plan

Notification Preference

Get External Notification Preferences

Get Notification Preferences

Update External Notification Preferences

Update Notification Preferences

Person

Get Authorized Signers

Get Consumer

Get Dependents

Get Person

<h4 class="slate-h4 " ><strong class="slate-bold">Step 1: Confirm your partnership</strong></h4><p class="slate-p " >API access is available exclusively to credentialed WEX business partners. If you&apos;re already a partner, your WEX account manager will provision your integration. Not yet a partner? Contact your Partner Account Executive to get started.</p><h4 class="slate-h4 " ><strong class="slate-bold">Step 2: Obtain your API credentials</strong></h4><p class="slate-p " >Create and manage your applications using the CDH Admin Portal. Each application has a <code class="slate-code">client_id</code> and a corresponding <code class="slate-code">client_secret</code>. Each application should be assigned permissions following the principles of least privilege. Store your credentials securely - never expose them in client-side code or version control.</p><h4 class="slate-h4 " ><strong class="slate-bold">Step 3: Authenticate and get a token</strong></h4><p class="slate-p " >Use the OAuth 2.0 Client Credentials flow to exchange your credentials for a bearer token. Tokens expire after one hour - build token refresh into your integration from the start.</p><h4 class="slate-h4 " ><strong class="slate-bold">Step 4: Explore the API reference</strong></h4><p class="slate-p " >Browse the endpoint reference for each domain - Claims and Financial Operations, Communications and Content, Lifecycle Actions, Plans, Enrollment and Elections, Platform Security, Users and Identity. The interactive API explorer lets you run live requests directly in the portal without writing any code.</p><h4 class="slate-h4 " ><strong class="slate-bold">Step 5: Build and certify your integration</strong></h4><p class="slate-p " >Develop against your sandbox environment, then work with your WEX account manager to validate your integration before promoting to production.</p><p class="slate-p " ></p>

API access is available exclusively to credentialed WEX business partners. If you're already a partner, your WEX account manager will provision your integration. Not yet a partner? Contact your Partner Account Executive to get started.

Create and manage your applications using the CDH Admin Portal. Each application has a 

. Each application should be assigned permissions following the principles of least privilege. Store your credentials securely - never expose them in client-side code or version control.

Use the OAuth 2.0 Client Credentials flow to exchange your credentials for a bearer token. Tokens expire after one hour - build token refresh into your integration from the start.

Browse the endpoint reference for each domain - Claims and Financial Operations, Communications and Content, Lifecycle Actions, Plans, Enrollment and Elections, Platform Security, Users and Identity. The interactive API explorer lets you run live requests directly in the portal without writing any code.

Step 5: Build and certify your integration

Develop against your sandbox environment, then work with your WEX account manager to validate your integration before promoting to production.

Sections

Getting Started

Step 1: Confirm your partnership

Step 2: Obtain your API credentials

Step 3: Authenticate and get a token

Step 4: Explore the API reference

Step 5: Build and certify your integration

On this page

Ask an AI

Code with AI