On this page
Move from business JSON to X12 with one predictable API.
Generate 837P claims, batched 270 eligibility inquiries, 276 status requests, and professional-service 278 authorization requests—then turn supported clearinghouse responses back into structured JSON.
https://api.interoplayer.devYour first 837P translation
The sandbox is the fastest path to a working integration. Use synthetic data until your security and production access reviews are complete.
- 1
Create a workspace and sandbox key
Open API keys, create a sandbox key, and save it immediately. The complete secret is shown only once.
- 2
Set server-side environment variables
Never put an Interoplayer key in browser code or a mobile application.
export INTEROPLAYER_API_URL="https://api.interoplayer.dev"
export INTEROPLAYER_API_KEY="il_test_your_key_here"- 3
Download the synthetic claim
Start with the validated fixture, then map fields from your own canonical data model.
Download claim-837p.json - 4
Send the request
Generate one idempotency key per logical claim and reuse that same key if the request must be retried.
IDEMPOTENCY_KEY="$(uuidgen)"
curl --request POST \
--url "${INTEROPLAYER_API_URL}/v1/translations/x12/837p?version=005010X222A1&output=transaction" \
--header "Authorization: Bearer ${INTEROPLAYER_API_KEY}" \
--header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
--header "Content-Type: application/json" \
--header "Accept: text/plain" \
--data @claim-837p.jsonA successful request returns 200 OK and an X12 body. Once your trading-partner profile is configured, switch to output=interchange to receive the complete ISA–IEA file. Keep the X-Interoplayer-Request-Id response header with your internal operation metadata for support and tracing.
Authentication and environments
Every product API request uses an environment-scoped bearer key. The key determines both the workspace and whether the request runs in sandbox or live mode.
Authorization: Bearer il_test_your_key_here| Environment | Prefix | Use | X12 indicator |
|---|---|---|---|
| Sandbox | il_test_ | Synthetic development and certification tests | ISA15=T |
| Live | il_live_ | Approved production workflows | ISA15=P |
Treat API keys like passwords
Store keys in a secrets manager, scope each key to one environment, and revoke it from the dashboard if it may have been exposed. Do not send keys in URLs, commit them to source control, or include them in application logs.
Create an 837P translation
Translate one claim with the original 1.0 body or send 1–100 claims with the expanded 2.0 body. The complete X12 result is returned synchronously in the same response.
/v1/translations/x12/837pHTTPSQuery parameters
| Name | Required | Values | Description |
|---|---|---|---|
version | Yes | 005010X222A1 | The X12 837P implementation-guide version. |
output | Recommended | interchange or transaction | Use interchange for ISA through IEA. For backward compatibility, omission currently means transaction. |
tradingPartner | No | Profile code | Selects an active receiver profile. Valid only with output=interchange; omit it to use the environment default. |
Request headers
| Header | Required | Value |
|---|---|---|
Authorization | Yes | Bearer il_test_… or Bearer il_live_… |
Content-Type | Yes | application/json |
Idempotency-Key | Live: yes | Opaque, non-PHI value between 16 and 255 characters |
Accept | No | application/edi-x12 for an interchange or text/plain for a transaction set |
Single-claim and expanded batch profiles
Schema 1.0 remains backward-compatible for basic single claims. Schema 2.0 accepts 1–100 claims plus advanced professional-claim structures. Unknown properties are rejected so integration mistakes fail early.
transactionRequiredControl number, submitter transaction ID, creation date/time, and purpose code.
submitter + receiverRequiredOrganizations and identifiers used in the 837 transaction set.
billingProviderPer claimOrganization or person, NPI, taxonomy, tax ID, address, optional contact, and optional pay-to provider.
subscriber + patient + payerPer claimThe policyholder is the subscriber. Add patient for a dependent and supply the relationship code.
claim1–100Claim identifiers, diagnoses, provider roles, coverage/adjudication, specialty data, and service lines.
serviceLines1–50Procedure, amount, units, date, diagnosis pointers, modifiers, authorizations, NDC, DME, and provider overrides.
Dates use YYYY-MM-DD. Money and quantities are decimal strings, not floats.
NPIs must pass their checksum. Diagnoses omit decimal punctuation.
The claim total must equal the sum of all service-line charges.
Frequency 7 or 8 requires a payer claim control number; frequency 1 must omit it.
Expanded synthetic request
This compact example shows a dependent claim, secondary coverage, provider roles, an attachment reference, and NDC data. Add up to 100 entries in claims.
{
"schemaVersion": "2.0",
"transaction": {
"controlNumber": "0002",
"submitterTransactionIdentifier": "SYNTHETIC-BATCH-0001",
"creationDate": "2026-09-15",
"creationTime": "14:30:15",
"purposeCode": "00"
},
"submitter": {
"organizationName": "Example Billing Platform",
"identifier": "EXAMPLEBILLING",
"contact": {
"name": "EDI Operations",
"phone": "14165550100",
"email": "edi@example.test"
}
},
"receiver": {
"organizationName": "Example Health Plan",
"identifier": "842610001"
},
"claims": [
{
"billingProvider": {
"entityType": "organization",
"organizationName": "Example Health Clinic",
"npi": "1234567893",
"taxonomyCode": "207Q00000X",
"taxId": "123456789",
"address": {
"address1": "100 Main Street",
"address2": "Suite 200",
"city": "Miami",
"state": "FL",
"postalCode": "33111"
}
},
"subscriber": {
"firstName": "Jane",
"middleName": "Q",
"lastName": "Doe",
"memberId": "SYNTHETIC123",
"groupNumber": "SYNTHETIC42",
"dateOfBirth": "1980-04-23",
"gender": "F",
"relationshipCode": "18",
"address": {
"address1": "45 Lake Shore Road",
"city": "Miami",
"state": "FL",
"postalCode": "33133"
}
},
"patient": {
"firstName": "John",
"lastName": "Doe",
"dateOfBirth": "2015-06-12",
"gender": "M",
"relationshipCode": "19",
"address": {
"address1": "45 Lake Shore Road",
"city": "Miami",
"state": "FL",
"postalCode": "33133"
}
},
"payer": {
"organizationName": "Example Health Plan",
"identifier": "842610001"
},
"claim": {
"patientControlNumber": "SYNTHETIC-DEPENDENT-0001",
"totalChargeAmount": "125.50",
"placeOfServiceCode": "11",
"frequencyCode": "1",
"claimFilingIndicatorCode": "CI",
"diagnoses": [
"M5450"
],
"priorAuthorizationNumber": "SYNTHETIC-AUTH-0001",
"attachments": [
{
"reportTypeCode": "OZ",
"transmissionCode": "BM",
"controlNumber": "SYNTHETIC-ATTACHMENT-0001"
}
],
"providers": {
"referring": {
"firstName": "Robert",
"lastName": "Smith",
"npi": "1245319599"
},
"serviceFacility": {
"organizationName": "Example Health Facility",
"npi": "1234567893",
"address": {
"address1": "100 Main Street",
"address2": "Suite 200",
"city": "Miami",
"state": "FL",
"postalCode": "33111"
}
}
},
"coordinationOfBenefits": [
{
"sequenceCode": "S",
"claimFilingIndicatorCode": "CI",
"paidAmount": "75.00",
"payerClaimControlNumber": "SYNTHETIC-OTHER-0001",
"subscriber": {
"firstName": "Jane",
"lastName": "Doe",
"memberId": "SYNTHETIC-SECONDARY",
"relationshipCode": "18"
},
"payer": {
"organizationName": "Example Secondary Plan",
"identifier": "SECONDARY1"
}
}
],
"serviceLines": [
{
"procedureCode": "99213",
"modifiers": [
"25"
],
"chargeAmount": "125.50",
"unitCount": "1",
"serviceDate": "2026-09-14",
"diagnosisPointers": [
1
],
"lineControlNumber": "SYNTHETIC-LINE-0001",
"drug": {
"nationalDrugCode": "00026063512",
"quantity": "10",
"unitCode": "ML"
}
}
]
}
}
]
}The expanded mapping is explicitly uncertified. It supports the documented dependent, COB/adjudication, provider, authorization, attachment, NDC, ambulance, anesthesia, chiropractic, DME, and accident structures, but receiver acceptance still requires the receiver's current companion guide and certification tests.
Use the output your transport owns
Interoplayer translates and validates the document; your application remains responsible for delivering it through its clearinghouse connection.
output=interchange
Returns ISA, GS, ST–SE, GE, and IEA using a configured trading-partner profile and server-owned control numbers.
Content-Type: application/edi-x12output=transaction
Returns only ST through SE for a gateway that deliberately owns the outer control envelopes.
Content-Type: text/plainComplete interchanges require an active trading-partner profile containing the sender and receiver identifiers approved by your clearinghouse. Configure it yourself in the Clearinghouse setup wizard by using a guided preset, importing the routing fields from an existing X12 file locally in your browser, or entering the assigned values. Configuration enables envelope generation; it is not clearinghouse certification or proof of acceptance.
ISA*00* *00* *ZZ*EXAMPLESENDER *ZZ*EXAMPLERECEIVER*...~
GS*HC*EXAMPLESENDER*EXAMPLERECEIVER*...*005010X222A1~
ST*837*0001*005010X222A1~
BHT*0019*00*SYNTHETIC0001*20260907*143015*CH~
...
CLM*SYNTHETIC0001*175.5***11:B:1*Y*A*Y*I~
...
SE*31*0001~
GE*1*1~
IEA*1*000000001~Useful response headers
X-Interoplayer-Request-IdCorrelation ID for tracing and support.X-Interoplayer-Mapping-RevisionThe immutable mapping revision used.X-Interoplayer-Operation-CountOne successful HTTP request is one operation.X-Interoplayer-Document-CountNumber of claims represented in the response.X-Interoplayer-Trading-PartnerThe resolved profile for complete interchanges.Idempotency-ReplayedTrue when an earlier logical request was replayed.RateLimit-RemainingRequests remaining in the fixed-minute window.X-Interoplayer-Quota-RemainingRemaining monthly units when the plan has a hard allowance.Translate up to 100 eligibility inquiries at once
Send one business-oriented JSON batch and receive one complete X12 270 interchange. Every inquiry shares the same payer and requesting provider, while each subscriber or dependent patient keeps an independent reference ID.
/v1/eligibility/270/batchesHTTPS| Input | Required | Description |
|---|---|---|
version query parameter | Yes | Must be 005010X279A1. |
tradingPartner query parameter | No | Selects an active receiver profile; omission uses the environment default. |
Idempotency-Key header | Live: yes | Reuse one stable, non-PHI key when retrying the same complete batch. |
inquiries | Yes | Between 1 and 100 subscriber or dependent eligibility inquiries. |
Complete synthetic batch
Use a unique referenceId for every inquiry so you can correlate each patient with the clearinghouse's eventual 271 response. Add dependent when the patient is someone other than the policyholder in subscriber.
{
"schemaVersion": "1.0",
"batchReference": "ELIGIBILITY-BATCH-001",
"informationSource": {
"organizationName": "Example Health Plan",
"payerId": "842610001"
},
"informationReceiver": {
"organizationName": "Example Health Clinic",
"npi": "1234567893",
"taxonomyCode": "207Q00000X"
},
"inquiries": [
{
"referenceId": "ELIGIBILITY-001",
"subscriber": {
"firstName": "Jane",
"lastName": "Doe",
"memberId": "SYNTHETIC123",
"groupNumber": "SYNTHETIC42",
"dateOfBirth": "1980-04-23",
"gender": "F"
},
"serviceDate": "2026-09-07",
"serviceTypeCodes": [
"30"
]
},
{
"referenceId": "ELIGIBILITY-002",
"subscriber": {
"firstName": "Robert",
"lastName": "Smith",
"memberId": "SYNTHETIC456",
"dateOfBirth": "1975-11-08",
"gender": "M"
},
"dependent": {
"firstName": "Mary",
"lastName": "Smith",
"dateOfBirth": "2015-10-14",
"gender": "F"
},
"serviceDate": "2026-09-07",
"serviceTypeCodes": [
"1",
"30"
]
}
]
}IDEMPOTENCY_KEY="$(uuidgen)"
curl --request POST \
--url "${INTEROPLAYER_API_URL}/v1/eligibility/270/batches?version=005010X279A1" \
--header "Authorization: Bearer ${INTEROPLAYER_API_KEY}" \
--header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
--header "Content-Type: application/json" \
--header "Accept: application/edi-x12" \
--data @eligibility-270-batch.jsonISA*00* *00* *ZZ*EXAMPLESENDER *ZZ*EXAMPLERECEIVER*...~
GS*HS*EXAMPLESENDER*EXAMPLERECEIVER*...*005010X279A1~
ST*270*000000001*005010X279A1~
BHT*0022*13*ELIGIBILITY-BATCH-001*20260907*143015~
HL*1**20*1~
NM1*PR*2*EXAMPLE HEALTH PLAN*****PI*842610001~
HL*2*1*21*1~
NM1*1P*2*EXAMPLE HEALTH CLINIC*****XX*1234567893~
...
HL*4*2*22*1~
NM1*IL*1*SMITH*ROBERT****MI*SYNTHETIC456~
HL*5*4*23*0~
TRN*1*ELIGIBILITY-002*EXAMPLESENDER~
NM1*03*1*SMITH*MARY~
DMG*D8*20151014*F~
DTP*291*D8*20260907~
EQ*1^30~
...
GE*1*1~
IEA*1*000000001~Usage is measured per operation: one API request containing up to 100 documents. A batch containing 30 inquiries consumes one operation and returns X-Interoplayer-Operation-Count: 1 and X-Interoplayer-Document-Count: 30. It also uses one request from the per-minute request limit. If no operation remains in a hard quota, the whole batch is rejected; no partial batch is generated. Replaying a completed batch with the same idempotency key does not consume another operation.
When dependent is present, Interoplayer creates a subscriber hierarchy followed by the dependent patient hierarchy. Do not send a relationship code in the 270 request. If the payer returns one in the 271, the parser exposes it as relationshipCode along with patientType, subscriber, and dependent.
Clearinghouses can impose stricter batching and loop rules than the base X12 guide. Certify this output against the receiver's companion guide and sandbox before using it in production. A partner profile may later lower the batch size or split a batch into multiple transaction sets without changing your JSON contract.
Keep the claim moving after eligibility
Use versioned JSON contracts for batched claim-status and multi-service professional prior-authorization requests. Both endpoints return a complete interchange and use the same trading-partner, idempotency, quota, and concurrency controls as the 270 and 837P paths.
/v1/claims/status/276?version=005010X212/v1/authorizations/278?version=005010X217Strict synthetic requests
Dates use YYYY-MM-DD, monetary values and units are strings, NPIs must pass their checksum, and unknown properties are rejected.
{
"schemaVersion": "2.0",
"requestReference": "STATUS-BATCH-001",
"payer": {
"organizationName": "Example Health Plan",
"identifier": "842610001"
},
"requester": {
"organizationName": "Example Billing Platform",
"identifier": "EXAMPLEBILLING"
},
"serviceProvider": {
"organizationName": "Example Health Clinic",
"npi": "1234567893"
},
"inquiries": [
{
"referenceId": "STATUS-TRACE-001",
"subscriber": {
"firstName": "Robert",
"lastName": "Smith",
"memberId": "SYNTHETIC456",
"dateOfBirth": "1975-11-08",
"gender": "M"
},
"patient": {
"firstName": "Mary",
"lastName": "Smith",
"dateOfBirth": "2015-10-14",
"gender": "F",
"relationshipCode": "19"
},
"claim": {
"patientControlNumber": "SYNTHETIC0001",
"serviceDate": "2026-09-01",
"serviceDateEnd": "2026-09-05",
"service": {
"procedureCode": "99213",
"chargeAmount": "85.00",
"lineControlNumber": "LINE-1"
}
}
}
]
}IDEMPOTENCY_KEY="$(uuidgen)"
curl --request POST \
--url "${INTEROPLAYER_API_URL}/v1/claims/status/276?version=005010X212" \
--header "Authorization: Bearer ${INTEROPLAYER_API_KEY}" \
--header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
--header "Content-Type: application/json" \
--header "Accept: application/edi-x12" \
--data @claim-status-276.jsonVersion 2 adds dependent patients, date ranges, service-level 276 criteria, and multi-service 278 reviews with providers, facilities, referrals, attachments, notes, and ambulance details. Every 276 batch shares one payer, requester, and service provider. Version 1 remains available for compatibility. Certify both request types against the receiver's current companion guide and sandbox.
Turn clearinghouse X12 back into JSON
When your application receives an acknowledgment, eligibility result, authorization decision, claim status, or remittance, send it to the parser and receive normalized JSON in the same response. Interoplayer does not retain either payload.
/v1/x12/responses/parseHTTPSA 999 acceptance means the transaction passed implementation and syntax checks. It does not mean the payer accepted or adjudicated the claim. Use 277CA for claim-level acknowledgment, 277 for later claim status, and 835 for payment and adjustments.
The normalized mappings retain 271 benefit limits, dates, references, messages, and related entities; 277CA service-line statuses and correlation IDs; and 835 claim/service adjustments, references, remarks, providers, and balance results.
A successful parse request is one operation regardless of how many supported transaction sets the interchange contains. Live requests require an idempotency key; retry the same X12 with the same key to avoid duplicate usage.
Parse a response interchange
Send one standalone TA1 or a complete interchange containing one or more supported transaction sets. Multiple sets return a MULTIPLE wrapper with a transactions array.
curl --request POST \
--url "${INTEROPLAYER_API_URL}/v1/x12/responses/parse" \
--header "Authorization: Bearer ${INTEROPLAYER_API_KEY}" \
--header "Idempotency-Key: parse-response-$(uuidgen)" \
--header "Content-Type: application/edi-x12" \
--data-binary @accepted-999.x12{
"schemaVersion": "1.0",
"standard": "x12",
"transactionType": "999",
"disposition": "accepted",
"envelope": {
"interchangeControlNumber": "000000001",
"senderId": "CLEARINGHOUSE",
"receiverId": "INTEROPLAYER",
"interchangeDate": "260907",
"interchangeTime": "1430",
"usageIndicator": "T",
"groupControlNumber": "77",
"implementationVersion": "005010X231A1"
},
"functionalGroup": {
"identifierCode": "HC",
"controlNumber": "77",
"implementationVersion": "005010X222A1"
},
"transactionSets": [
{
"transactionSetIdentifier": "837",
"controlNumber": "000000123",
"implementationVersion": "005010X222A1",
"acknowledgmentCode": "A",
"disposition": "accepted",
"errors": []
}
],
"summary": {
"acknowledgmentCode": "A",
"includedCount": 1,
"receivedCount": 1,
"acceptedCount": 1
}
}Idempotency and safe retries
Network failures make it impossible to know whether a request completed. Idempotency lets your application retry the same logical operation without generating a second interchange or usage event.
Generate the key before the first attempt. Persist it with your operation, reuse it with the identical request on every retry, and never include patient or claim data in the value.
| Response | Action |
|---|---|
| Connection reset or timeout | Retry with the same idempotency key and identical request. |
409 request in progress | Wait for Retry-After, then retry with the same key. |
429 or 503 | Honor Retry-After when present; use exponential backoff with jitter. |
400, 401, 413, or 422 | Fix the request or credentials before retrying. |
409 idempotency conflict | The key was used with different input. Investigate; do not retry blindly. |
The initial idempotency window is 24 hours. A completed replay preserves complete interchange control numbers and is billed once, but HTTP attempts still count toward the per-minute request limit.
Machine-readable problem details
Non-2xx responses use application/problem+json and include a request ID. Schema errors can also include field-level paths.
{
"type": "https://interoplayer.dev/problems/invalid-request",
"title": "Invalid request",
"status": 400,
"detail": "The request does not match the endpoint contract.",
"instance": "/v1/translations/x12/837p",
"requestId": "2363d23e-5fb9-4b01-8808-cb3ad62987b6",
"errors": [
{
"path": "/subscriber/memberId",
"message": "is required"
}
]
}| Status | Meaning | Retry? |
|---|---|---|
400 | Malformed input, schema failure, or invalid headers | After fixing |
401 | Missing, malformed, unknown, or revoked API key | After fixing |
403 | The environment is not entitled to the operation | No |
404 | Stored response missing, expired, or belongs to another environment | No |
409 | Idempotency conflict or an identical request is still running | Conditional |
413 | Payload exceeds the plan's synchronous limit | After reducing |
422 | Invalid/unsupported X12 or unavailable partner profile | After fixing |
429 | Request, quota, sandbox, or concurrency limit reached | Yes |
503 | Temporary dependency or capacity failure | Yes |
Plan limits and response headers
Limits are enforced from the environment's active entitlement. Read response headers instead of hard-coding assumptions into your application.
| Plan | Requests/minute | Concurrency | Payload | Monthly allowance |
|---|---|---|---|---|
| Sandbox | 60 per key | 2 | 256 KiB | 1,000 · hard stop |
| Launch | 120 per key | 4 | 1 MiB | 1,500 operations · paid overage |
| Scale | 600 per key | 16 | 1 MiB | 15,000 operations · paid overage |
1 operation = 1 API request containing up to 100 documents. Sandbox traffic also shares a platform-wide safety ceiling. If capacity is full, retry after the duration in Retry-After. Eligibility batches support up to 100 inquiries synchronously; larger asynchronous file APIs are not part of v1.
One synchronous, no-payload-retention model
Translation and response parsing return their results in the same HTTP request. Interoplayer does not offer response polling or customer webhooks and does not retain either payload.
In-memory processing
Request and response bodies are processed in memory and are not persisted. Operational logs exclude bodies and credentials. Compact request fingerprints and non-payload metadata support idempotency, usage, and tracing.
Operational metadata only
The database records bounded identifiers, request fingerprints, byte counts, outcomes, timing, and billing units—not JSON documents, generated X12, clearinghouse X12, or normalized response JSON.
Interoplayer does not need your clearinghouse API key. Your systems keep ownership of clearinghouse transport, and only send the data needed for the translation or acknowledgment operation you invoke.
Before sending a live transaction
Passing schema validation is necessary, but receiver certification remains a separate step. Complete this checklist with the clearinghouse or payer that will receive the file.
- 01
Map your canonical claim or eligibility data and exercise positive and negative synthetic cases in sandbox.
- 02
Provide the sender and receiver identifiers assigned or explicitly approved by the clearinghouse.
- 03
Apply the receiver's current companion-guide rules to a versioned trading-partner profile.
- 04
Submit representative interchanges to the receiver's certification environment and capture TA1, 999, 277CA, business-response, and remittance evidence.
- 05
Complete your security, access, retention, and incident-response review before using protected health data.
- 06
Create a live key, store it server-side, and keep the same HTTP contract while switching environments.
Start with a sandbox key and the validated fixture.
Your HTTP integration can be running today; trading-partner certification can proceed against the same contract.