Claims
The Claims API provides programmatic access to manage health benefit claims and their associated financial data. This RESTful API enables developers to retrieve claim details, inspect and resolve denial records, manage receipts and supporting documents, and look up payee and expense information.
Key Features
Retrieve Individual Claims: Fetch complete claim details by claim number, including status, amounts, and denial history.
List Claims: Query paginated claim lists by person or business entity.
Denial Management: Retrieve the full denial history for a claim and update denials by reallocating denied amounts.
Receipt Management: List, retrieve, upload, and download receipt documents linked to claims.
Payee Lookup: Retrieve payee information associated with a participant.
Expense Categories: Look up eligible expense categories and their types for a given account.
Idempotent Writes: Safe denial updates using the Idempotency-Key header.
Use Cases
Participant Self-Service: Allow members to view their claims, understand denial reasons, and upload receipts to resolve issues.
Administrator Workflows: Enable benefits administrators to review and update denial statuses on behalf of participants.
Employer Reporting: Query claims by business entity ID for reporting and reconciliation.
Document Vault: Store and retrieve receipt images and documents tied to specific claims.
Expense Submission: Drive claim submission forms by fetching valid expense categories and types for a participant’s account.
Scopes & Permissions
All endpoints use Bearer JWT authentication (bearerAuth). Contact the WEX Health platform team for the appropriate scopes required for your integration.
Permission Model:
- Participants can access only claims associated with their own
person_id - Service accounts acting on behalf of a business require a valid
business_entity_id - Administrative operations (for example, updating denials) require elevated permissions
Core Concepts
Claim Resource Model
A Claim represents a reimbursement request submitted by a participant for an eligible health expense.
Person (Participant)
└── Claims (one or many)
├── Denial Reasons (if denied)
├── Requests for More Information (RMI)
└── Receipts (supporting documents)
Key Identifiers:
- claim_number: Alphanumeric string uniquely identifying a claim (for example,
11BPEB1210513P0000101) - person_id: UUID of the participant who submitted the claim
- business_entity_id: UUID of the employer/business for employer-level queries
Claim Status Lifecycle
The claim_status field reflects the current processing state of a claim:
Status | Description |
PENDING_RECEIPT_STATUS | Claim submitted; awaiting receipt |
PENDING_REIMBURSEMENT_STATUS | Receipts validated; awaiting payment |
SCHEDULED_REIMBURSEMENT_STATUS | Payment scheduled |
PAID_STATUS | Claim has been paid |
DENIED_STATUS | Claim was denied |
DENIED_COLLECTING_REPAYMENT_STATUS | Denied; collecting repayment |
HOLD_STATUS | Claim is on hold pending review |
FREEZE_STATUS | Claim is frozen |
BANKING_FAILED_STATUS | Payment attempted but banking operation failed |
UNSPECIFIED | Status is not yet determined |
Receipt Status Values
Status | Description |
RECEIPT_REQUIRED | A receipt must be submitted |
RECEIPT_RECEIVED | Receipt has been received and is under review |
RECEIPT_OVERDUE | Receipt was required but not submitted in time |
RECEIPT_NOT_NEEDED | No receipt is required for this claim |
RECEIPT_AVAILABLE | Receipt is on file |
RECEIPT_NEW_NEEDED | A new or additional receipt is required |
RECEIPT_RE_UPLOADED | Receipt was re-submitted |
RECEIPT_PENDING | Receipt submission is pending |
UNSPECIFIED | Status is not yet determined |
Claim Data Model
{
"claim_number": "11BPEB1210513P0000101",
"claim_amount": 250.00,
"claim_status": "PAID_STATUS",
"submission_date": "2025-01-15T13:45:22Z",
"start_date_of_service": "2025-01-10T00:00:00Z",
"end_date_of_service": "2025-01-12T00:00:00Z",
"processed_date": "2025-01-15T13:45:22Z",
"provider_name": "Acme Medical Group",
"paid_amount": 250.00,
"submitted_amount": 250.00,
"is_ptp": false,
"denial_reasons": null,
"requests_for_more_information": null,
"receipt_status": "RECEIPT_NOT_NEEDED",
"denied_amount": 0.00,
"applied_copay_amount": 0.00,
"applied_coinsurance_amount": 0.00,
"applied_deductible_amount": 0.00,
"claim_source": "CONSUMER",
"scheduled_for_reimbursement_date": null,
"plan_year_name": "2025 Plan Year",
"plan_year_start_date": "2025-01-01T00:00:00Z",
"plan_name": "FSA Basic",
"final_filing_date": "2025-12-31T23:59:59Z",
"expense_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"receipt_status_dt": "2025-01-15T13:45:22Z",
"category": "Medical",
"expense_type": "Doctor Visit",
"issue_response": null,
"offering_id": null,
"payee": "John Doe",
"plan_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
Field Descriptions
Field | Type | Required | Description |
claim_number | string | Yes | Unique alphanumeric claim identifier |
claim_amount | number | Yes | Total amount of the claim submitted |
claim_status | enum | Yes | Current processing status |
submission_date | datetime | No | ISO 8601 datetime when claim was submitted |
start_date_of_service | datetime | No | First date of service |
end_date_of_service | datetime | No | Last date of service |
processed_date | datetime | No | Date the claim was processed |
provider_name | string | No | Name of the healthcare provider |
paid_amount | number | Yes | Amount reimbursed |
submitted_amount | number | Yes | Original amount submitted |
is_ptp | boolean | Yes | Whether this is a pay-the-provider claim |
denial_reasons | array | No | List of denial reasons, if denied |
requests_for_more_information | array | No | Pending RMI requests, if any |
receipt_status | enum | Yes | Current status of receipt submission |
denied_amount | number | Yes | Amount denied |
applied_copay_amount | number | Yes | Amount applied to copay |
applied_coinsurance_amount | number | Yes | Amount applied to coinsurance |
applied_deductible_amount | number | Yes | Amount applied to deductible |
claim_source | enum | Yes | Origin of the claim submission |
scheduled_for_reimbursement_date | datetime | No | Date the claim is scheduled for reimbursement |
plan_year_name | string | No | Name of the plan year associated with the claim |
plan_year_start_date | datetime | No | Start date of the applicable plan year |
plan_name | string | No | Name of the plan associated with the claim |
final_filing_date | datetime | No | Final date on which the claim can be filed |
expense_id | uuid | Yes | Expense identifier associated with the claim |
receipt_status_dt | datetime | No | Date and time the receipt status was last updated |
category | string | No | High-level category of the expense related to this claim |
expense_type | string | No | Specific type of expense submitted for this claim |
issue_response | string | No | Denial code description; populated only for denied claims |
offering_id | integer | No | Identifier of the benefit offering associated with the claim |
payee | string | No | Designated recipient of payment |
plan_id | uuid | No | Identifier of the benefit plan to which this claim belongs |
Denial Record Model
A Denial is a record attached to a claim indicating that some or all of the submitted amount was not approved.
{
"denial_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"denial_code": "DEN-001",
"denial_reason": "Invalid procedure code",
"denied_amount": "1250.75",
"status": "DENIED",
"action_date": "2026-01-15T10:30:00Z"
}
Updating a Denial reallocates the denied amount to one or more categories. The PATCH /v1/claims/{claim_number}/denials/{denial_id} endpoint accepts a request body with one or more of:
Field | Description |
reallocate_to_pending_amount | Amount to move to pending reimbursement |
reallocate_to_paid_amount | Amount to move to paid |
reallocate_to_deductible_applied_amount | Amount applied toward the deductible |
reallocate_to_coinsurance_applied_amount | Amount applied toward coinsurance |
reallocate_to_copay_applied_amount | Amount applied toward copay |
Monetary amounts use a string format with exactly two decimal places (for example, "125.50").
Receipt Model
A Receipt is a supporting document uploaded to validate an eligible expense.
{
"receipt_id": "rcpt-abc12345",
"file_name": "receipt_2025_01.pdf",
"file_size": 204800,
"content_type": "PDF",
"upload_date": "2025-08-29T09:00:00Z",
"tracked_expense_number": "EXP-9876",
"claim_numbers": ["11BPEB1210513P0000101"],
"download_url": "https://storage.wexglobal.com/receipts/rcpt-abc12345"
}
Common Use Cases
Use Case 1: List Claims for a Participant
Scenario: A participant logs into the benefits portal and wants to see all their recent claims.
curl -X GET "https://platform.sandbox.wexglobal.com/api/v1/claims?person_id=8b6f2c2e-9a7e-4a6d-9b6d-1f92c3c5a441&page_size=10&index=0" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Accept: application/json"
Response
{
"index": 0,
"page_size": 10,
"has_next": true,
"items": [
{
"claim_number": "11BPEB1210513P0000101",
"claim_amount": 250.00,
"claim_status": "PAID_STATUS",
"submission_date": "2025-01-15T13:45:22Z",
"paid_amount": 250.00,
"submitted_amount": 250.00,
"is_ptp": false,
"receipt_status": "RECEIPT_NOT_NEEDED",
"denied_amount": 0.00,
"applied_copay_amount": 0.00,
"applied_coinsurance_amount": 0.00,
"applied_deductible_amount": 0.00,
"claim_source": "CONSUMER",
"expense_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
]
}
Important Notes:
- ⚠️ You must provide exactly one of
person_idorbusiness_entity_id— not both, not neither - 💡 Use
indexandpage_sizeto paginate through results - ✅ Use
has_nextto determine whether more pages exist
Use Case 2: List Claims for a Business Entity
Scenario: An HR administrator wants to pull all claims submitted under their organization.
curl -X GET "https://platform.sandbox.wexglobal.com/api/v1/claims?business_entity_id=3fa85f64-5717-4562-b3fc-2c963f66afa6&page_size=20&index=0" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Accept: application/json"
Notes:
- ⚠️ Providing both
person_idandbusiness_entity_idreturns400 Bad Request - Business-level queries may require elevated service account permissions
Use Case 3: Retrieve a Specific Claim
Scenario: A user selects a claim from a list and wants to see full details, including denial reasons and RMI requests.
curl -X GET "https://platform.sandbox.wexglobal.com/api/v1/claims/11BPEB1210513P0000101" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Accept: application/json"
Response
{
"claim_number": "11BPEB1210513P0000101",
"claim_amount": 500.00,
"claim_status": "DENIED_STATUS",
"submission_date": "2025-01-10T09:00:00Z",
"start_date_of_service": "2025-01-05T00:00:00Z",
"end_date_of_service": "2025-01-06T00:00:00Z",
"provider_name": "City Health Clinic",
"paid_amount": 0.00,
"submitted_amount": 500.00,
"is_ptp": false,
"denial_reasons": [
{
"denial_code": "DEN-002",
"reason": "Expense not eligible under current plan",
"denial_date_time": "2025-01-12T10:00:00Z",
"is_upload_receipt_allowed": false,
"explanation": "The submitted expense type is not covered under the FSA plan for the current plan year.",
"action_required": "Contact your HR administrator for plan coverage details."
}
],
"receipt_status": "RECEIPT_NOT_NEEDED",
"denied_amount": 500.00,
"applied_copay_amount": 0.00,
"applied_coinsurance_amount": 0.00,
"applied_deductible_amount": 0.00,
"claim_source": "CONSUMER",
"expense_id": "8b6f2c2e-9a7e-4a6d-9b6d-1f92c3c5a441"
}
Optional Query Parameter:
person_id(UUID) — Optionally scope the lookup to a specific participant
Use Case 4: Get Denial History for a Claim
Scenario: An administrator reviews all denials recorded against a specific claim.
curl -X GET "https://platform.sandbox.wexglobal.com/api/v1/claims/OM133344251215P0000101/denials" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Accept: application/json"
Response
{
"claim_number": "OM133344251215P0000101",
"denials": [
{
"denial_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"denial_code": "DEN-001",
"denial_reason": "Invalid procedure code",
"denied_amount": "1250.75",
"status": "DENIED",
"action_date": "2026-01-15T10:30:00Z"
}
]
}
Use Case 5: Update a Denial (Reallocate Amounts)
Scenario: An administrator resolves a denial by reallocating part of the denied amount to pending reimbursement and part to a deductible.
⚠️ This is a state-changing operation. Always include an Idempotency-Key header to safely retry if the request fails.
curl -X PATCH "https://platform.sandbox.wexglobal.com/api/v1/claims/OM133344251215P0000101/denials/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: d290f1ee-6c54-4b01-90e6-d701748f0851" \
-d '{
"reallocate_to_pending_amount": "75.00",
"reallocate_to_paid_amount": "50.00"
}'
Response
{
"claim_number": "OM133344251215P0000101",
"denial_id": "8b6f2c2e-9a7e-4a6d-9b6d-1f92c3c5a441",
"claim_status": "PENDING_REIMBURSEMENT",
"denial_updated_timestamp": "2025-01-15T13:45:22Z",
"message": "Denial status successfully updated."
}
Reallocation Rules:
- At least one reallocation field must be provided
- All monetary amounts must be strings with exactly two decimal digits (for example,
"75.00") - The
claim_statusin the response reflects the new state after reallocation repayment_idis returned when a repayment is created; otherwisenull
Use Case 6: Get Receipts for a Claim
Scenario: A participant wants to see all receipts they have uploaded for a specific claim.
curl -X GET "https://platform.sandbox.wexglobal.com/api/v1/claims/11BPEB1210513P0000101/receipts?person_id=8b6f2c2e-9a7e-4a6d-9b6d-1f92c3c5a441&page_size=10&index=0" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Accept: application/json"
Response
{
"index": 0,
"page_size": 10,
"has_next": false,
"items": [
{
"receipt_id": "rcpt-abc12345",
"file_name": "receipt_2025_01.pdf",
"file_size": 204800,
"content_type": "PDF",
"upload_date": "2025-08-29T09:00:00Z",
"claim_numbers": ["11BPEB1210513P0000101"],
"download_url": "https://storage.wexglobal.com/receipts/rcpt-abc12345"
}
]
}
Optional Parameters:
number_of_months_back— Limits results to receipts from the last N months (e.g.,3returns the last 3 months)
Important Notes:
- ⚠️
person_idis required for this endpoint person_idis a required query parameter
Use Case 7: Retrieve a Single Receipt
Scenario: A support agent retrieves the details of a specific receipt by ID.
curl -X GET "https://platform.sandbox.wexglobal.com/api/v1/claims/receipts/rcpt-abc12345?person_id=8b6f2c2e-9a7e-4a6d-9b6d-1f92c3c5a441" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Accept: application/json"
Response
{
"receipt_id": "rcpt-abc12345",
"file_name": "receipt_2025_01.pdf",
"file_size": 204800,
"content_type": "PDF",
"upload_date": "2025-08-29T09:00:00Z",
"claim_numbers": ["11BPEB1210513P0000101"],
"download_url": "https://storage.wexglobal.com/receipts/rcpt-abc12345"
}
Use Case 8: Upload a Receipt to Cloud Storage
Scenario: A participant submits a receipt image to satisfy a RECEIPT_REQUIRED status on their claim.
curl -X POST "https://platform.sandbox.wexglobal.com/api/v1/claims/receipts/upload-file-to-cloud?person_id=8b6f2c2e-9a7e-4a6d-9b6d-1f92c3c5a441" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"file_name": "receipt_2025_01.pdf",
"file_content_base64": "",
"mime_type": "application/pdf",
"content_length": 204800
}'
Request Body Fields
Field | Required | Description |
file_name | Yes | Name of the file (for example, receipt_2025_01.pdf) |
file_content_base64 | Yes | Base64-encoded content of the file |
mime_type | Yes | MIME type (for example, application/pdf, image/jpeg) |
content_length | No | File size in bytes |
Supported Content Types (upload): PDF, JPEG, JPG, PNG, GIF, TIFF, BMP, DOC, DOCX, XLS, XLSX, CSV, and more (see DocumentContentTypeDTOEnum in the spec).
Use Case 9: Download a Receipt from Cloud Storage
Scenario: A participant or administrator retrieves a previously uploaded receipt file.
curl -X GET "https://platform.sandbox.wexglobal.com/api/v1/claims/receipts/download-file-from-cloud/ext-file-id-001?person_id=8b6f2c2e-9a7e-4a6d-9b6d-1f92c3c5a441" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Parameters:
external_id(path, required) — The external identifier of the stored fileperson_id(query, required) — The participant’s UUID
Use Case 10: Get Payees for a Participant
Scenario: A participant views their saved payee list before submitting a new pay-the-provider claim.
curl -X GET "https://platform.sandbox.wexglobal.com/api/v1/claims/payees?person_id=8b6f2c2e-9a7e-4a6d-9b6d-1f92c3c5a441&page_size=10&index=0" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Accept: application/json"
Response
{
"index": 0,
"page_size": 10,
"has_next": false,
"items": [
{
"payee_id": "PAY-001",
"payee_tin": "12-3456789",
"name": "City Health Clinic",
"account_number": "ACC-99887",
"address_line1": "123 Medical Drive",
"city": "Portland",
"state": "OR",
"postal_code": "97201",
"country": "US"
}
]
}
Use Case 11: Get Expense Categories and Types
Scenario: A claim submission form dynamically loads the eligible expense categories for the participant’s account before they select an expense type.
curl -X GET "https://platform.sandbox.wexglobal.com/api/v1/claims/expense-categories-and-types?person_id=8b6f2c2e-9a7e-4a6d-9b6d-1f92c3c5a441&account_type=FSA&employer_id=3fa85f64-5717-4562-b3fc-2c963f66afa6" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Accept: application/json"
Required Query Parameters:
Parameter | Description |
person_id | UUID of the participant |
account_type | Account type (for example, FSA, HSA, HRA) |
employer_id | UUID of the employer |
{
"items": [
{
"category_name": "Medical",
"category_types": ["Doctor Visit", "Hospital", "Lab Work", "Prescription"]
},
{
"category_name": "Dental",
"category_types": ["Routine Cleaning", "Orthodontics", "Oral Surgery"]
},
{
"category_name": "Vision",
"category_types": ["Eye Exam", "Glasses", "Contact Lenses"]
}
]
}
Pagination
The Claims, Receipts, and Payees list endpoints use index-based pagination.
Request Parameters
Parameter | Type | Description |
index | integer | Zero-based starting index (page number minus one) |
page_size | integer | Number of items to return per page |
Response Fields
Field | Type | Description |
index | integer | Current page index |
page_size | integer | Number of items per page |
has_next | boolean | true if more pages are available |
items | array | The list of returned resources |
Example: Paginating Through Claims
# Page 1 — first 10 claims
curl -X GET "https://platform.sandbox.wexglobal.com/api/v1/claims?person_id=8b6f2c2e-9a7e-4a6d-9b6d-1f92c3c5a441&page_size=10&index=0" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
# Page 2 — next 10 claims
curl -X GET "https://platform.sandbox.wexglobal.com/api/v1/claims?person_id=8b6f2c2e-9a7e-4a6d-9b6d-1f92c3c5a441&page_size=10&index=1" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Best Practices:
- Check
has_nextbefore requesting the next page - Use consistent
page_sizeacross requests within the same session - The
indexparameter is 0-based (first page isindex=0)
Error Handling
The Claims API uses the Problem Details format (RFC 9457) for all error responses.
Error Response Format
{
"type": "https://api.example.com/problems/bad-request",
"title": "Invalid request parameters",
"status": 400,
"detail": "Exactly one of 'person_id' or 'business_entity_id' must be provided.",
"instance": "/v1/claims"
}
HTTP Status Codes
Status | Description | Common Causes |
200 OK | Success | Request completed successfully |
400 Bad Request | Client error | Missing required params, invalid format, both/neither of person_id/business_entity_id supplied |
401 Unauthorized | Auth failure | Missing or expired bearer token |
403 Forbidden | Permission denied | Valid token but insufficient access |
404 Not Found | Resource missing | Claim number, denial ID, or receipt ID does not exist |
500 Internal Server Error | Server error | Unexpected server-side issue |
503 Service Unavailable | Service down | Temporary outage or maintenance |
Example Error Responses
Missing or Conflicting Parameters (400):
{
"type": "https://api.example.com/problems/bad-request",
"title": "Bad Request",
"status": 400,
"detail": "Exactly one of 'person_id' or 'business_entity_id' must be provided.",
"instance": "/v1/claims"
}
Unauthorized (401):
{
"type": "https://api.example.com/problems/unauthorized",
"title": "Unauthorized",
"status": 401,
"detail": "The access token is invalid or has expired.",
"instance": "/v1/claims"
}
Claim Not Found (404):
{
"type": "https://api.example.com/problems/not-found",
"title": "Not Found",
"status": 404,
"detail": "Claim '11BPEB1210513P0000101' was not found.",
"instance": "/v1/claims/11BPEB1210513P0000101"
}
Error Handling Best Practices
- Retry transient failures with exponential backoff for
503and network errors. - Do not retry
4xxclient errors — fix the request before retrying. - Log the
instancefield from error responses to correlate with support tickets. - Validate required parameters client-side before making API calls to reduce
400errors.
Idempotency
The PATCH /v1/claims/{claim_number}/denials/{denial_id} endpoint requires an Idempotency-Key header.
How it Works
- Generate a unique UUID v4 for each distinct denial update operation.
- Idempotency-Key: d290f1ee-6c54-4b01-90e6-d701748f0851
- If the request times out or returns a network error, retry using the same key.
- The server will return the original response rather than processing the operation twice.
Best Practices
- Generate a new
Idempotency-Keyfor each logically distinct update. - Reuse the same key when retrying after a failure.
- Store the key alongside the operation if you need to audit retries.
- Keys should be UUID v4 format.
Safe (GET) endpoints — GET /v1/claims, GET /v1/claims/{claim_number}, and all other GET endpoints — are inherently idempotent. They do not require an Idempotency-Key.
Changelog
Version 1.0.0 (2026-04-21)
- Initial release of Claims API documentation
- Covers all 10 endpoints in
claims.v1.json - Documented pagination, idempotency, and error handling
- Included real-world use cases with curl examples
Endpoints
/v1/claims/{claim_number}?person_id=person_id
/v1/claims?person_id=person_id&business_entity_id=business_entity_id&page_size=30&index=0
/v1/claims/{claim_number}/receipts?person_id=8b6f2c2e-9a7e-4a6d-9b6d-1f92c3c5a441&page_siz...
/v1/claims/receipts/{receipt_id}?person_id=person_id
/v1/claims/payees?person_id=person_id&page_size=20&index=0
/v1/claims/expense-categories-and-types?person_id=person_id&account_type=account_type&empl...
/v1/claims/receipts/download-file-from-cloud/{external_id}?person_id=person_id
/v1/claims/{claim_number}/receipts?person_id=person_id
/v1/claims/receipts/upload-file-to-cloud?person_id=person_id
/v1/claims/receipts/upload?person_id=person_id
/v1/claims/{claim_number}/denials/{denial_guid}
/v1/reports/claim-details?employer_id=employer_id&claim_status=claim_status&service_date_f...
/v1/claims?person_id=person_id
/v1/claims/receipts-needed?person_id=person_id&type=type&page_size=page_size&index=index
/v1/claims/{claim_number}/cancel?person_id=person_id
/v1/claims/worksheets/{worksheet_id}?person_id=person_id
/v1/claims/{worksheet_id}/file-claim?person_id=person_id
/v1/claims/{claim_number}/denials