Request and Response
Responses to our Medical Network APIs can be lengthy due to the many data points that a payer or trading partner provides in the query response. Professional claims can have up to fifty line items (Loop 2400) in the claimInformation object (Loop 2300 in the EDI spec), each of which, reflects payer decisions on payment.
Our APIs translate back-and-forth between JSON and X12 EDI when the information departs into and returns from the medical network. All fields and JSON objects conform to the EDI 837p transaction standard.
Validation endpoint
curl --request POST \
--url https://sandbox-apigw.optum.com/medicalnetwork/professionalclaims/v3/validation \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
"controlNumber": "000000001",
"tradingPartnerServiceId": "9496",
"submitter": {
"organizationName": "REGIONAL PPO NETWORK",
"contactInformation": {
"name": "SUBMITTER CONTACT INFO",
"phoneNumber": "123456789"
}
},
"receiver": {
"organizationName": "EXTRA HEALTHY INSURANCE"
},
"subscriber": {
"memberId": "0000000001",
"paymentResponsibilityLevelCode": "P",
"firstName": "johnone",
"lastName": "doeOne",
"gender": "M",
"dateOfBirth": "19800102",
"policyNumber": "00001",
"address": {
"address1": "123 address1",
"city": "city1",
"state": "wa",
"postalCode": "981010000"
}
},
"dependent": {
"memberId": "0000000002",
"paymentResponsibilityLevelCode": "P",
"firstName": "janeone",
"lastName": "doeOne",
"gender": "F",
"dateOfBirth": "19800102",
"policyNumber": "00002",
"relationshipToSubscriberCode": "01",
"address": {
"address1": "123 address1",
"city": "city1",
"state": "wa",
"postalCode": "981010000"
}
},
"providers": [{
"providerType": "BillingProvider",
"npi": "1760854442",
"employerId": "123456789",
"organizationName": "HAPPY DOCTORS GROUPPRACTICE",
"address": {
"address1": "000 address1",
"city": "city2",
"state": "tn",
"postalCode": "372030000"
},
"contactInformation": {
"name": "janetwo doetwo",
"phoneNumber": "0000000001"
}
},{
"providerType": "ReferringProvider",
"npi": "1942788757",
"firstName": "johntwo",
"lastName": "doetwo",
"employerId" : "123456"
},{
"providerType": "RenderingProvider",
"npi": "1942788757",
"firstName": "janetwo",
"lastName": "doetwo",
"middleName": "middletwo",
"ssn" : "000000000"
}],
"claimInformation": {
"claimFilingCode": "CI",
"patientControlNumber": "12345",
"claimChargeAmount": "28.75",
"placeOfServiceCode": "11",
"claimFrequencyCode": "1",
"signatureIndicator": "Y",
"planParticipationCode": "A",
"benefitsAssignmentCertificationIndicator": "Y",
"releaseInformationCode": "Y",
"claimSupplementalInformation": {
"repricedClaimNumber": "00001",
"claimNumber": "12345"
},
"healthCareCodeInformation": [{
"diagnosisTypeCode": "BK",
"diagnosisCode": "496"
},{
"diagnosisTypeCode": "BF",
"diagnosisCode": "25000"
}],
"serviceFacilityLocation": {
"organizationName": "HAPPY DOCTORS GROUP",
"address": {
"address1": "000 address1",
"city": "city2",
"state": "tn",
"postalCode": "372030000"
}
},
"serviceLines":[ {
"serviceDate": "20050514",
"professionalService": {
"procedureIdentifier": "HC",
"lineItemChargeAmount": "25",
"procedureCode": "E0570",
"measurementUnit": "UN",
"serviceUnitCount": "1",
"compositeDiagnosisCodePointers": {
"diagnosisCodePointers": ["1","2"]
}
}
},
{
"serviceDate": "20050514",
"professionalService": {
"procedureIdentifier": "HC",
"lineItemChargeAmount": "3.75",
"procedureCode": "A7003",
"measurementUnit": "UN",
"serviceUnitCount": "1",
"compositeDiagnosisCodePointers": {
"diagnosisCodePointers": ["1" ]
}
}
}
]
}
}
{
"status": "SUCCESS",
"controlNumber": "000000001",
"tradingPartnerServiceId": "9496",
"claimReference": {
"correlationId": "200715R999898~18620063139417176",
"submitterId": "999898",
"customerClaimNumber": "000000001",
"patientControlNumber": "12345",
"timeOfResponse": "2020-07-15T12:44:17.994-05:00",
"claimType": "PRO",
"formatVersion": "5010"
},
"meta": {
"submitterId": "999898",
"senderId": "IN_APIP_MN_CHC_TestApp2",
"billerId": "009998",
"traceId": "2b680c68-cb81-a781-f68e-8dc92a66639c",
"applicationMode": "sandbox"
},
"editStatus": "SUCCESS",
"payer": {
"payerName": "EXTRA HEALTHY INSURANCE",
"payerID": "9496"
}
}
curl --request POST \
--url https://sandbox-apigw.optum.com/medicalnetwork/professionalclaims/v3/raw-x12-validation \
--header 'accept: application/json' \
--header 'content-type: application/json'
{"x12": "ISA*00* *01*CYCTRANS *ZZ*009998999898 *ZZ*CLAIMSCH *200714*1925*|*00501*000000001*0*T*:~GS*HC*418581RTEXGEAR*1465*20200714*1925*000000001*X*005010X222~ST*837*000000001*005010X222~BHT*0019*00*000000001*20200714*1925*CH~NM1*41*2*REGIONAL PPO NETWORK*****46*009998999898~PER*IC*SUBMITTER CONTACT INFO*TE*123456789~NM1*40*2*EXTRA HEALTHY INSURANCE*****46*CLAIMSCH~HL*1**20*1~NM1*85*2*HAPPY DOCTORS GROUPPRACTICE*****XX*1760854442~N3*000 address1~N4*city2*tn*372030000~REF*EI*123456789~PER*IC*janetwo doetwo*TE*0000000001~HL*2*1*22*1~SBR*P********CI~NM1*IL*1*doeOne*johnone****MI*0000000001~DMG*D8*19800102*M~NM1*PR*2*EXTRA HEALTHY INSURANCE*****PI*9496~HL*3*2*23*0~PAT*01~NM1*QC*1*doeOne*janeone~N3*123 address1~N4*city1*wa*981010000~DMG*D8*19800102*F~CLM*12345*28.75***11:B:1*Y*A*Y*Y~REF*9A*00001~REF*D9*12345~HI*BK:496*BF:25000~NM1*DN*1*doetwo*johntwo****XX*1942788757~NM1*82*1*doetwo*janetwo*middletwo***XX*1942788757~NM1*77*2*HAPPY DOCTORS GROUP~N3*000 address1~N4*city2*tn*372030000~LX*1~SV1*HC:E0570*25*UN*1***1:2~DTP*472*D8*20050514~LX*2~SV1*HC:A7003*3.75*UN*1***1~DTP*472*D8*20050514~SE*38*000000001~GE*1*000000001~IEA*1*000000001~"}
{
"status": "SUCCESS",
"controlNumber": "000000001",
"tradingPartnerServiceId": "9496",
"claimReference": {
"correlationId": "200715R999898~18620063139417176",
"submitterId": "999898",
"customerClaimNumber": "000000001",
"timeOfResponse": "2020-07-15T12:44:17.994-05:00",
"claimType": "PRO",
"formatVersion": "5010"
},
"meta": {
"submitterId": "999898",
"senderId": "IN_APIP_MN_CHC_TestApp2",
"billerId": "009998",
"traceId": "607cd6b2-c60e-7501-2154-10701791f9ce",
"applicationMode": "sandbox"
},
"editStatus": "SUCCESS",
"payer": {
"payerName": "EXTRA HEALTHY INSURANCE",
"payerID": "9496"
}
}
Submission endpoint
{
"controlNumber": "000000001",
"tradingPartnerServiceId": "9496",
"submitter": {
"organizationName": "REGIONAL PPO NETWORK",
"contactInformation": {
"name": "SUBMITTER CONTACT INFO",
"phoneNumber": "123456789"
}
},
"receiver": {
"organizationName": "EXTRA HEALTHY INSURANCE"
},
"subscriber": {
"memberId": "0000000001",
"paymentResponsibilityLevelCode": "P",
"firstName": "johnone",
"lastName": "doeOne",
"gender": "M",
"dateOfBirth": "19800102",
"policyNumber": "00001",
"address": {
"address1": "123 address1",
"city": "city1",
"state": "wa",
"postalCode": "981010000"
}
},
"dependent": {
"memberId": "0000000002",
"paymentResponsibilityLevelCode": "P",
"firstName": "janeone",
"lastName": "doeOne",
"gender": "F",
"dateOfBirth": "19800102",
"policyNumber": "00002",
"relationshipToSubscriberCode": "01",
"address": {
"address1": "123 address1",
"city": "city1",
"state": "wa",
"postalCode": "981010000"
}
},
"providers": [{
"providerType": "BillingProvider",
"npi": "1760854442",
"employerId": "123456789",
"organizationName": "HAPPY DOCTORS GROUPPRACTICE",
"address": {
"address1": "000 address1",
"city": "city2",
"state": "tn",
"postalCode": "372030000"
},
"contactInformation": {
"name": "janetwo doetwo",
"phoneNumber": "0000000001"
}
},{
"providerType": "ReferringProvider",
"npi": "1942788757",
"firstName": "johntwo",
"lastName": "doetwo",
"employerId" : "123456"
},{
"providerType": "RenderingProvider",
"npi": "1942788757",
"firstName": "janetwo",
"lastName": "doetwo",
"middleName": "middletwo",
"ssn" : "000000000"
}],
"claimInformation": {
"claimFilingCode": "CI",
"patientControlNumber": "12345",
"claimChargeAmount": "28.75",
"placeOfServiceCode": "11",
"claimFrequencyCode": "1",
"signatureIndicator": "Y",
"planParticipationCode": "A",
"benefitsAssignmentCertificationIndicator": "Y",
"releaseInformationCode": "Y",
"claimSupplementalInformation": {
"repricedClaimNumber": "00001",
"claimNumber": "12345"
},
"healthCareCodeInformation": [{
"diagnosisTypeCode": "BK",
"diagnosisCode": "496"
},{
"diagnosisTypeCode": "BF",
"diagnosisCode": "25000"
}],
"serviceFacilityLocation": {
"organizationName": "HAPPY DOCTORS GROUP",
"address": {
"address1": "000 address1",
"city": "city2",
"state": "tn",
"postalCode": "372030000"
}
},
"serviceLines":[ {
"serviceDate": "20050514",
"professionalService": {
"procedureIdentifier": "HC",
"lineItemChargeAmount": "25",
"procedureCode": "E0570",
"measurementUnit": "UN",
"serviceUnitCount": "1",
"compositeDiagnosisCodePointers": {
"diagnosisCodePointers": ["1","2"]
}
}
},
{
"serviceDate": "20050514",
"professionalService": {
"procedureIdentifier": "HC",
"lineItemChargeAmount": "3.75",
"procedureCode": "A7003",
"measurementUnit": "UN",
"serviceUnitCount": "1",
"compositeDiagnosisCodePointers": {
"diagnosisCodePointers": ["1" ]
}
}
}
]
}
}
{
"status": "SUCCESS",
"controlNumber": "000000001",
"tradingPartnerServiceId": "9496",
"claimReference": {
"correlationId": "200715R999898~18620063139417176",
"submitterId": "999898",
"customerClaimNumber": "000000001",
"patientControlNumber": "12345",
"timeOfResponse": "2020-07-15T12:44:17.994-05:00",
"claimType": "PRO",
"formatVersion": "5010",
"rhclaimNumber": "00001TEST"
},
"meta": {
"submitterId": "999898",
"senderId": "IN_APIP_MN_CHC_TestApp2",
"billerId": "009998",
"traceId": "ab02da20-4d2f-1beb-0526-8bd29c81523c",
"applicationMode": "sandbox"
},
"editStatus": "SUCCESS",
"payer": {
"payerName": "EXTRA HEALTHY INSURANCE",
"payerID": "9496"
}
}
As shown below, the sample claim contains the JSON objects:
| JSON Object | Description |
|---|---|
submitter | Provider submitting the claim. |
receiver | Payer. |
tradingPartnerServiceId | Payer ID; you can use the payer’s ConnectCenter real-time Payer ID as the tradingPartnerServiceId. The Legacy PayerList originates this value. |
subscriber | Medical insurance policy holder. |
dependent | Dependent of the insurance policyholder receiving the care. |
providers | List of one or more providers involved in the medical care. ✍️ Setting Providers is deprecated, please set all Providers individually by its type. |
claimInformation | Complete breakdown of the medical encounter and its associated charges. |
serviceLines and serviceDate | serviceLines is an array of one or more medical services, procedures, or products for the encounter each of which, is specified as a serviceDate record in the array. |
After the API validates the claim, it is ready to submit to the payer unless you want to make further changes and run the checks.
The claimReference field is an object containing the list of identifiers that you can use to track an Institutional Claims. If questions arise about a claim, you can provide the information listed in the claimReference object to Optum support for troubleshooting purposes. It appears in all Submission responses for claims. The list of identifiers may differ depending on the context for the response:
```json
{
"status": "SUCCESS",
"controlNumber": "000000001",
"tradingPartnerServiceId": "9496",
"claimReference": {
"correlationId": "201113R999898~2634061369394033",
"submitterId": "009998999898",
"customerClaimNumber": "000000001",
"patientControlNumber": "12345",
"timeOfResponse": "2020-11-13T09:30:33.29-06:00",
"claimType": "PRO",
"formatVersion": "5010",
"rhclaimNumber": "2031851503057"
}
}
```
The first response you get back from the clearinghouse does not indicate whether the claim is being paid; it indicates that the clearinghouse has accepted the claim and is getting ready to forward it to the payer.
✍️ In the sandbox request, using value: test00005 (lower case and not uppercase), for
fieldName: patientControlNumber returns a EDITS canned response.
{"x12": "ISA*00* *01*CYCTRANS *ZZ*009998999898 *ZZ*CLAIMSCH *200714*1925*|*00501*000000001*0*T*:~GS*HC*418581RTEXGEAR*1465*20200714*1925*000000001*X*005010X222~ST*837*000000001*005010X222~BHT*0019*00*000000001*20200714*1925*CH~NM1*41*2*REGIONAL PPO NETWORK*****46*009998999898~PER*IC*SUBMITTER CONTACT INFO*TE*123456789~NM1*40*2*EXTRA HEALTHY INSURANCE*****46*CLAIMSCH~HL*1**20*1~NM1*85*2*HAPPY DOCTORS GROUPPRACTICE*****XX*1760854442~N3*000 address1~N4*city2*tn*372030000~REF*EI*123456789~PER*IC*janetwo doetwo*TE*0000000001~HL*2*1*22*1~SBR*P********CI~NM1*IL*1*doeOne*johnone****MI*0000000001~DMG*D8*19800102*M~NM1*PR*2*EXTRA HEALTHY INSURANCE*****PI*9496~HL*3*2*23*0~PAT*01~NM1*QC*1*doeOne*janeone~N3*123 address1~N4*city1*wa*981010000~DMG*D8*19800102*F~CLM*12345*28.75***11:B:1*Y*A*Y*Y~REF*9A*00001~REF*D9*12345~HI*BK:496*BF:25000~NM1*DN*1*doetwo*johntwo****XX*1942788757~NM1*82*1*doetwo*janetwo*middletwo***XX*1942788757~NM1*77*2*HAPPY DOCTORS GROUP~N3*000 address1~N4*city2*tn*372030000~LX*1~SV1*HC:E0570*25*UN*1***1:2~DTP*472*D8*20050514~LX*2~SV1*HC:A7003*3.75*UN*1***1~DTP*472*D8*20050514~SE*38*000000001~GE*1*000000001~IEA*1*000000001~"}
A successful validation of a professional claim gives a response similar to the following:
{
"status": "SUCCESS",
"controlNumber": "000000001",
"tradingPartnerServiceId": "9496",
"claimReference": {
"correlationId": "200715R999898~18620063139417176",
"submitterId": "999898",
"customerClaimNumber": "000000001",
"patientControlNumber": "12345",
"timeOfResponse": "2020-07-15T12:44:17.994-05:00",
"claimType": "PRO",
"formatVersion": "5010",
"rhclaimNumber": "12345"
},
"meta": {
"submitterId": "999898",
"senderId": "IN_APIP_MN_CHC_TestApp2",
"billerId": "009998",
"traceId": "e59c20d1-8ebb-0fa9-84ba-1160e16405ad",
"applicationMode": "sandbox"
},
"editStatus": "SUCCESS",
"payer": {
"payerName": "EXTRA HEALTHY INSURANCE",
"payerID": "9496"
}
}
Submit rejected claims
A correct claim is only submitted when the payer has actually adjudicated the submission and processed the claim for payment.
claimFrequencyCode '1' is used for all original submissions even if a claim has been rejected
claimFrequencyCode '7' is used specifically if a payer denies a claim and corrections need to be made
If a claim submission response is received with status EDIT, use claimFrequencyCode '7', that is, if a claim is denied at the payer and a '0' dollar or incomplete payment is received. Almost all other situations would require a claimFrequencyCode '1'.
Corrected claims appeals and denials
If a claim is denied or partially paid by a payer, a corrected claim should be sent for additional review. Submitting a corrected claim would require the claim frequency code '7', and the payer claim controlNumber must be included on the claim in the claimControlNumber field in the claimSupplementalInformation.
The claimControlNumber is the number assigned by the payer to identify a claim. Once submitted, the payer will review the claim and make any changes based on their internal review. The claimControlNumber is found on the payer 277 report.
The same process would need to be followed for voided claims, but using a frequency code '8'. Here is a sample corrected claim. To include additional documents, use the Attachment Submission API. See also Attachments Submission V1 Getting Started.
{
"controlNumber": "000000001",
"tradingPartnerServiceId": "9496",
"submitter": {
"organizationName": "REGIONAL PPO NETWORK",
"contactInformation": {
"name": "SUBMITTER CONTACT INFO",
"phoneNumber": "123456789"
}
},
"receiver": {
"organizationName": "EXTRA HEALTHY INSURANCE"
},
"subscriber": {
"memberId": "0000000001",
"paymentResponsibilityLevelCode": "P",
"firstName": "johnone",
"lastName": "doeOne",
"gender": "M",
"dateOfBirth": "19800102",
"policyNumber": "00001",
"address": {
"address1": "123 address1",
"city": "city1",
"state": "wa",
"postalCode": "981010000"
}
},
"providers": [{
"providerType": "BillingProvider",
"npi": "1760854442",
"employerId": "123456789",
"organizationName": "HAPPY DOCTORS GROUPPRACTICE",
"address": {
"address1": "000 address1",
"city": "city2",
"state": "tn",
"postalCode": "372030000"
},
"contactInformation": {
"name": "janetwo doetwo",
"phoneNumber": "0000000001"
}
},
{
"providerType": "ReferringProvider",
"npi": "1942788757",
"firstName": "johntwo",
"lastName": "doetwo",
"employerId" : "123456"
},{
"providerType": "RenderingProvider",
"npi": "1942788757",
"firstName": "janetwo",
"lastName": "doetwo",
"middleName": "middletwo",
"ssn" : "000000000"
}],
"claimInformation": {
"claimFilingCode": "CI",
"patientControlNumber": "12345",
"claimChargeAmount": "28.75",
"placeOfServiceCode": "11",
"claimFrequencyCode": "7",
"signatureIndicator": "Y",
"planParticipationCode": "A",
"benefitsAssignmentCertificationIndicator": "Y",
"releaseInformationCode": "Y",
"claimSupplementalInformation": {
"claimControlNumber": "12345"
},
"healthCareCodeInformation": [{
"diagnosisTypeCode": "BK",
"diagnosisCode": "496"
},{
"diagnosisTypeCode": "BF",
"diagnosisCode": "25000"
}],
"serviceFacilityLocation": {
"organizationName": "HAPPY DOCTORS GROUP",
"address": {
"address1": "000 address1",
"city": "city2",
"state": "tn",
"postalCode": "372030000"
}
},
"serviceLines":[ {
"serviceDate": "20050514",
"professionalService": {
"procedureIdentifier": "HC",
"lineItemChargeAmount": "25",
"procedureCode": "E0570",
"measurementUnit": "UN",
"serviceUnitCount": "1",
"compositeDiagnosisCodePointers": {
"diagnosisCodePointers": ["1","2"]
}
}
},
{
"serviceDate": "20050514",
"professionalService": {
"procedureIdentifier": "HC",
"lineItemChargeAmount": "3.75",
"procedureCode": "A7003",
"measurementUnit": "UN",
"serviceUnitCount": "1",
"compositeDiagnosisCodePointers": {
"diagnosisCodePointers": ["1" ]
}
}
}
]
}
}
Handle multiple authorization numbers per claim
If the Institutional Claims required multiple authorization numbers, multiple claims need to be submitted. Submission through the Professional API allows for prior authorization information to be submitted at both the claim and line level Institutional Claims APIs allows for prior authorization information to be submitted at the claim level only. Here is an Open API Specs sample.
ServiceLineReferenceInformation:
type: object
properties:
repricedLineItemReferenceNumber:
type: string
description: 'Loop: 2400, Segment: REF, Element: REF02 Notes: When REF01=9B'
adjustedRepricedLineItemReferenceNumber:
type: string
description: 'Loop: 2400, Segment: REF, Element: REF02 Note: When REF01=9D'
priorAuthorization:
maxItems: 5
minItems: 0
type: array
description: Loop 2400 REF
items:
Updated 10 days ago