> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://build.andel.org/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://build.andel.org/_mcp/server. # ESI Compatibility Andel can carry the concepts required by Express Scripts' (ESI) CDH 1500-byte accumulator protocol, for partners that exchange accumulator data in that format. This page documents the supported event types, accumulator types, the field mapping between the Data Exchange API and the ESI fixed-width record, and a sample file partners can validate against their own parsers. Monetary fields are **proposed and provenance-pending**. They ship optional and are not yet a firm contract. Do not build settlement logic on the dollar amounts until Andel confirms their provenance. ## Supported event types A purchase's `event_type` maps to an ESI Event Code: | `event_type` | ESI Event Code | Meaning | | ------------------ | -------------- | ---------------------------------------------------- | | `claim` | `00` | A normal fill. | | `reversal` | `11` | Restores accumulators for a returned or voided fill. | | `adjustment` | `10` | A flat or paired accumulator correction. | | `hra_initial_load` | `01` | Initial annual HRA load. | | `hra_rollover` | `04` | Prior-year HRA rollover. | | `hra_incentive` | `16` | Mid-year HRA incentive top-up. | In the ESI CDH protocol, all six event types are the **same** record, distinguished by the Event Code and by which accumulators move. This API mirrors that: every event type is a `/purchases` record discriminated by `event_type`. HRA loads, rollovers, and incentives are records whose populated accumulator is the HRA slot (`type_of_benefit_account: hra`); they carry `origin_code` and `plan_year`, use `date_of_service` as the effective date, and omit the pharmacy-fill fields (`ndc`, `prescriber_spi`, `quantity`). ## Supported accumulator types Each element of a purchase's `accumulators` array carries a `type_of_benefit_account` that maps to an ESI Type-of-Benefit-Account code: | `type_of_benefit_account` | ESI code | Description | | ------------------------- | -------- | ----------------------------------------- | | `hra` | `02` | Health Reimbursement Arrangement balance. | | `deductible` | `04` | Plan deductible. | | `oop` | `05` | Out-of-pocket. | | `cap` | `06` | Benefit cap. | | `lifetime_cap` | `07` | Lifetime cap. | | `drug_cap` | `08` | Drug-specific cap. | | `benefit_deductible` | `14` | Benefit-specific deductible. | | `benefit_oop` | `15` | Benefit-specific out-of-pocket. | | `base_deductible` | `24` | Base deductible. | | `base_oop` | `25` | Base out-of-pocket. | | `tmoop` | `35` | True maximum out-of-pocket. | The `cr_db_indicator` on each accumulator maps to the ESI CR-DB Indicator: `debit` (`+`) consumes the accumulator, `credit` (`-`) restores it, `replace` (`R`) overwrites the running total, and `bypass` (`B`) ignores the accumulator for that transaction. ## Field mapping The Andel-source column is the API field; the ESI-source column describes the partner protocol position (1-indexed byte offset and length in the CDH record). ### Purchase | API field | ESI field (position, length) | | ------------------------ | -------------------------------------------------------------------- | | `purchase_id` | Signature (319-344, 26), persisted to a `purchase_id` mapping | | `member_id` | Partner Subscriber Id (756-775, 20) | | `plan_id` | Group Id (489-503, 15) or Partner Group ID (776-790, 15) | | `purchased_at` | Transaction Date + Time (261-276, 16) | | `date_of_service` | Date Of Service (277-284, 8, `CCYYMMDD`) | | `ndc` | Product / Service Id (1422-1440, 19), qualifier `03` | | `quantity` | Dispensed Quantity (1444-1453, 10, 3-decimal) | | `days_supply` | Days Supply (1441-1443, 3) | | `prescriber_spi` | Provider ID (287-301, 15), Provider Type `09` | | `provider_type` | Provider Type (285-286, 2) | | `network_ind` | Network Ind (347, 1) | | `event_type` | Event Code (350-351, 2) | | `original_purchase_id` | Claim Xref Id (449-466, 18) | | `status` | Response Code (243-244) / Reason Code (245-246) on the Data Response | | `member_purchase_amount` | Current Amount, out-of-pocket slot (`05`), 2-decimal | | `oop_amount` | Current Amount, out-of-pocket slot (`05`), 2-decimal | | `plan_contribution` | Derived (total less member responsibility) | | `deductible_applied` | Current Amount, deductible slot (`04`), 2-decimal | | `subscriber_id` | Subscriber Id (469-488, 20) | | `first_name` | First Name (504-528, 25) | | `last_name` | Last Name (529-563, 35) | | `date_of_birth` | Date Of Birth (568-575, 8, `CCYYMMDD`) | | `gender` | Gender (576, 1) | | `relationship` | Relationship (567, 1) | | `origin_code` | Origin Code (430, 1), HRA balance events | | `plan_year` | Derived / partner config, HRA balance events | ### Accumulator | API field | ESI field | | ------------------------- | -------------------------------------- | | `type_of_benefit_account` | Type of Benefit Account N (2) | | `participation_type` | Participation Type N (1) | | `amount` | Current Amount N (10, 2-decimal) | | `cr_db_indicator` | CR-DB Indicator N (1) | | `accumulated_amount` | Accumulated Amount N (10, 2-decimal) | | `remaining_amount` | Remaining Amount N (10, 2-decimal) | | `met_this_transaction` | Derived (Remaining Amount equals zero) | ### HRA balance events HRA loads, rollovers, and incentives are `/purchases` records with `event_type` set to `hra_initial_load`, `hra_rollover`, or `hra_incentive`. They reuse the purchase fields above: the dollar amount is the `accumulators` entry with `type_of_benefit_account: hra`, `date_of_service` is the effective date, and `origin_code` + `plan_year` carry the load metadata. ### ESI protocol identity The `esi` object on a purchase carries the wire-protocol identifiers, populated only when a purchase is exchanged via the ESI CDH format: | API field | ESI field (position, length) | | ----------------------- | ------------------------------ | | `esi.sender_id` | Sender Id (205-228, 24) | | `esi.receiver_id` | Receiver Id (229-238, 10) | | `esi.signature` | Signature (319-344, 26) | | `esi.claim_id` | Claim Id (431-448, 18) | | `esi.claim_xref_id` | Claim Xref Id (449-466, 18) | | `esi.transmission_type` | Transmission Type (201-202, 2) | | `esi.request_code` | Request Code (203-204, 2) | | `esi.response_code` | Response Code (243-244, 2) | | `esi.reason_code` | Reason Code (245-246, 2) | ## Fields not populated * **Monetary fields** (`member_purchase_amount`, `oop_amount`, `plan_contribution`, `deductible_applied`, accumulator amounts, HRA amounts) are proposed and provenance-pending; they may be omitted until provenance is confirmed. * **Demographics and ESI protocol identity** are populated only when a purchase is exchanged via the ESI CDH format; they are otherwise omitted. * The deprecated ESI Situational Segment and ESI-internal or reserved fields are not used. ## Transport options | Transport | Notes | | -------------- | -------------------------------------------------------------------------- | | Batch SFTP | Default. File drop on a schedule; lowest infrastructure requirement. | | IBM MQ | Real-time, transactional; both sides exchange responses for every request. | | XML over HTTPS | Real-time request/response with the same semantics as MQ. | ## Sample file A synthetic batch in the ESI CDH layout: a batch header, three detail records (a claim, a reversal, and an HRA load), and a batch trailer. All values are synthetic and the file uses test status (`T`). Fields are shown space-delimited for readability; the wire format is fixed-width. ```text ANDEL_TO_ESI_20260520.txt 00 ANDEL HEALTH CDH T M 20260520 090500 00000001 DQ 01 ANDEL-TPO-0001 MHS 0000 00 ... DOS=20260513 PT=09 SIG=20260513182401512A1B2C3D EVT=00 SUB=SUB-4471902 GRP=PLN-0001 FN=MARIA LN=LOPEZ DOB=19840702 G=2 REL=1 ACC=[04 1 0000003250 + | 05 1 0000001000 + | 02 1 0000003250 +] NDC=00093005301 DS=030 QTY=0000030000 DQ 02 ANDEL-TPO-0001 MHS 0000 00 ... DOS=20260513 PT=09 SIG=20260520090214733B2C3D4E EVT=11 XREF=CLM-0009912837 SUB=SUB-4471902 GRP=PLN-0001 FN=MARIA LN=LOPEZ DOB=19840702 G=2 REL=1 ACC=[04 1 0000003250 - | 05 1 0000001000 - | 02 1 0000003250 -] NDC=00093005301 DS=030 QTY=0000030000 DQ 01 ANDEL-TPO-0001 MHS 0000 00 ... DOS=20260101 SIG=20260101000000001C3D4E5F EVT=01 ORIG=E SUB=SUB-4471902 GRP=PLN-0001 FN=MARIA LN=LOPEZ DOB=19840702 G=2 REL=1 ACC=[02 1 0000050000 R] 99 000000005 ```