wex-health-sdk 0.1.0a3

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+

Installation

pip install wex-health-sdk

Primary dependencies

The SDK's primary runtime dependencies include:

• aiohttp >= 3.13.3
• aiohttp-retry >= 2.8.3
• pydantic >= 2.4.0

These and any additional runtime dependencies declared by the package are installed automatically when you install the SDK.

Quick Start

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

async def main():
    config = Configuration(
        host=os.environ['WEX_API_HOST'],
        access_token=os.environ['WEX_ACCESS_TOKEN']
    )
    async with ApiClient(config) as client:
        api = ClaimsApi(client)
        # person_id must be a UUID
        person_id = UUID(os.environ['PERSON_ID'])
        claims = await api.get_claims_for_participant(person_id)
        print(f"Found {len(claims.claims)} claims")

asyncio.run(main())

Authentication

The SDK supports multiple authentication methods:

OAuth2 Client Credentials (Recommended)

import os
import wex_health

configuration = 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'],
        'audience': os.environ.get('WEX_AUDIENCE')  # Optional
    }
)

Bearer Token

import os
import wex_health

configuration = wex_health.Configuration(
    host=os.environ['WEX_API_HOST'],
    access_token=os.environ['WEX_ACCESS_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 → Retry policy → Per-request timeout
• Server-Aware: Respects Retry-After headers (capped at 30 seconds)

Default Configuration

configuration = wex_health.Configuration(
    retries=3,              # Maximum retry attempts for transient failures
    request_timeout=30.0,   # Timeout per individual HTTP request (seconds)
    overall_timeout=30.0    # Hard limit for entire operation including all retries (seconds)
)

Note: overall_timeout is a hard cap. If retries would exceed this limit, the operation fails with asyncio.TimeoutError. For example, with overall_timeout=30.0 and retries=3, if the first two attempts take 12 seconds each, the third attempt will be cancelled after 6 seconds.

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 when Retry-After header is present
4. Retry-After Header: Any response with server-provided retry guidance

Backoff Strategy: Exponential backoff with full jitter

• Initial delay: 500ms
• Maximum delay: 2 seconds
• Algorithm: Full jitter (randomized across entire backoff window) to prevent thundering herd

Error Handling

The SDK raises specific exceptions for different HTTP error responses:

Exception	HTTP Status	Description
BadRequestException	400	Invalid request parameters
UnauthorizedException	401	Authentication failed
ForbiddenException	403	Access denied
NotFoundException	404	Resource not found
ConflictException	409	Resource conflict
UnprocessableEntityException	422	Validation error
ServiceException	5xx	Server error
ApiException	Other	Base exception for all API errors

from wex_health.exceptions import (
    ApiException,
    NotFoundException,
    UnauthorizedException,
    ServiceException,
)

try:
    claim = await claims_api.get_claim(person_id, claim_number)
except NotFoundException:
    print("Claim not found")
except UnauthorizedException:
    print("Check your credentials")
except ServiceException as e:
    print(f"Server error: {e.status} - retry later")
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.