wex-health-sdk 0.1.0a2

Python SDK for Wex Health and Benefits Platform APIs. Provides comprehensive access to claims, business, consumer, and administrative APIs with built-in authentication, logging, and error handling.

wex-health-sdk

Official Python SDK for the WEX Health and Benefits Platform APIs. Provides programmatic access to HSA, FSA, HRA management, COBRA coverage, and claims processing.

Features

• Async-first: Built on aiohttp for high-performance async operations
• Type-safe: Full type hints for IDE autocompletion and static analysis
• Resilient: Automatic retries with exponential backoff and jitter
• Secure: OAuth2 Client Credentials and Bearer token authentication
• Observable: Structured logging with request correlation IDs

Requirements

Python 3.9+

Quick Start

Get started in minutes with this minimal example:

import os
import asyncio
from wex_health import Configuration, ApiClient, ClaimsApi

async def main():
    config = Configuration(
        host=os.environ.get('API_HOST', 'https://api.example.com'),
        access_token=os.environ.get('ACCESS_TOKEN')
    )
    async with ApiClient(config) as client:
        api = ClaimsApi(client)
        claims = await api.get_claims_for_participant("person-id-123")
        print(f"Found {len(claims.claims)} claims")

asyncio.run(main())

For OAuth2 authentication and more examples, see the Authentication section below.

Installation & Usage

Install from PyPI

pip install wex-health-sdk

Verify Installation

import wex_health
print(f"SDK Version: {wex_health.__version__}")

Authentication

The SDK supports multiple authentication methods:

OAuth2 Client Credentials (Recommended)

configuration = wex_health.Configuration(
    host=os.environ.get('API_HOST', 'https://api.example.com'),  # Replace with your API endpoint
    oauth2_credentials={
        'client_id': os.environ['OAUTH2_CLIENT_ID'],
        'client_secret': os.environ['OAUTH2_CLIENT_SECRET'],
        'access_token_url': os.environ.get('OAUTH2_TOKEN_URL', 'https://api.example.com/oauth/token'),
        'audience': os.environ.get('OAUTH2_AUDIENCE', 'https://api.example.com')
    }
)

Bearer Token

configuration = wex_health.Configuration(
    access_token=os.environ['BEARER_TOKEN']
)

Retry Logic

The SDK implements a layered resilience strategy with automatic retry handling for transient failures:

Key Features

• Exponential Backoff with Jitter: 500ms initial delay, 2s maximum cap
• Smart 429 Handling: Only retries rate limits when Retry-After header is present
• Automatic Retry: Handles 5xx errors, 408 Request Timeout automatically
• Three-Layer Protection: Global timeout (30s) + Retry policy (3 attempts) + Per-request timeout (30s)
• Server-Aware: Respects Retry-After headers (capped at 30 seconds)

Default Configuration

configuration = wex_health.Configuration(
    retries=3,              # Retry failed requests up to 3 times
    request_timeout=30.0,   # 30 second timeout per individual request
    overall_timeout=30.0    # 30 second global timeout for entire operation (all retries)
)

Retry Behavior

The SDK automatically retries the following scenarios:

1. 5xx Server Errors: 500, 502, 503, 504, 507, etc.
2. 408 Request Timeout: Client timeout waiting for response
3. 429 Rate Limiting: Only if Retry-After header is present
4. Retry-After Header: Any response with server-provided retry guidance

Backoff Strategy: Exponential backoff with jitter

• Initial delay: 500ms
• Maximum delay: 2 seconds
• Algorithm: Randomized jitter to prevent thundering herd

Error Handling

from wex_health.exceptions import NotFoundException, ApiException

try:
    claim = await claims_api.get_claim(person_id, claim_number)
except NotFoundException:
    print("Claim not found")
except ApiException as e:
    print(f"API Error: {e.status} - {e.reason}")

Best Practices

• Use environment variables for credentials—never hardcode secrets
• Use context managers (async with ApiClient(...)) for automatic resource cleanup
• Pass correlation IDs via x_request_id parameter for request tracking
• Reuse ApiClient instances across multiple API calls for connection pooling
• Enable debug logging with logging.basicConfig(level=logging.DEBUG) when troubleshooting

API Endpoints

All URIs are relative to the host URL you configure when creating the Configuration object.

Class	Method	HTTP request	Description
ClaimsApi	get_claim	GET /claims/v1/consumers/{person_id}/claims/{claim_number}	Get Claim
ClaimsApi	get_claims_for_business	GET /claims/v1/businesses/{business_id}/claims	Get Claims for Business
ClaimsApi	get_claims_for_participant	GET /claims/v1/consumers/{person_id}/claims	Get Claims for Participant
ClaimsApi	get_payees_for_participant	GET /claims/v1/consumers/{person_id}/payees	Get Payees
ClaimsApi	get_receipt_for_participant	GET /claims/v1/consumers/{person_id}/receipts/{receipt_id}	Get Receipt
ClaimsApi	get_receipts_for_participant	GET /claims/v1/consumers/{person_id}/receipts	Get Receipts
HealthApi	get_liveness	GET /claims/health/liveness	Get Liveness

Models

• ClaimDTO
• ClaimsDTO
• DenialReasonDTO
• PayeeDTO
• PayeesDTO
• ProblemDetails
• ReceiptDTO
• ReceiptsDTO
• RmiDTO

Support

To report bugs, request features, or get help with SDK integration:

• Support Portal: https://developers.wexhealth.com/wex-health-api/sdks/support
• Email: [e-mail]

License

Copyright (c) 2025 Wex Inc. All rights reserved. This software is proprietary and confidential.

See the LICENSE for full license terms.