Attachments Submission FAQs
The Attachments Submission API supports the X12 EDI 275 Patient Information transaction. It translates this standard to JSON, so it is more accessible to developers for integration into users’ applications.
The attachments submission take two forms: Solicited and Unsolicited.
- For an Unsolicited attachment, consider workman's compensation claims. Attachments illustrating the conditions giving rise to the claim are required in all worker's compensation claims, hence they are called unsolicited claims.
- Solicited claims usually are sent by payers to providers requesting documentation for a claim.
NOTE
Please see the API FAQs section for tips and solutions to some of the most common questions asked by customers, developer community, and internal staff about the use of the Change Healthcare APIs.
What does a typical Attachments API request look like?
The API uses a POST request. You provide the input as JSON in the body of the request. The following shows the contents of an Unsolicited attachments submission request body.
Example
Note that enough claim information (claimInformation object) must be included in the request to ensure the attachments submission goes to the right place:
```json
"controlNumber": "123459999",
"tradingPartnerServiceId": "9496",
"submitter": {
"organizationName": "happy doctors grouppractice",
"etin": "1942788757"
},
"provider": {
"organizationName": "happy doctors group",
"npi": "1760854442",
"address": {
"address1": "123 address1",
"city": "city1",
"state": "wa",
"postalCode": "981010000"
},
"phoneNumber": "123456789",
"faxNumber": "123456789"
},
"subscriber": {
"memberId": "0000000001",
"firstName": "johnone",
"lastName": "doeone"
},
"claimInformation": {
"patientControlNumber": "12345",
"payerControlNumber": "00001",
"beginClaimServiceDate": "20050514",
"endClaimServiceDate": "20050515",
"serviceLines": [{
"providerAttachmentControlNumber": "123456789",
"serviceLineDateInformation" : {
"submissionDate" : "20050514"
},
"attachmentDetails": {
"name": "rightarm.jpg"
}
}]
}
}' \
-F [email protected]~/images/attachments_rightarm.jpg
```
A submission for a Solicited Attachments transaction (attachments requested by the payer) contains more payer information.
Attachments submission request example
```json
{
"controlNumber": "123459999",
"tradingPartnerServiceId": "9496",
"tradingPartnerName":"Happy Payers of Washington State",
"payerAddress": {
"address1": "123 address1",
"city": "city1",
"state": "wa",
"postalCode": "981010000"
},
"submitter": {
"organizationName": "happy doctors grouppractice",
"etin": "1942788757"
},
"provider": {
"organizationName": "happy doctors group",
"npi": "1760854442",
"address": {
"address1": "123 address1",
"city": "city1",
"state": "wa",
"postalCode": "981010000"
},
"phoneNumber": "123456789",
"faxNumber": "123456789"
},
"subscriber": {
"memberId": "0000000001",
"firstName": "johnone",
"lastName": "doeone"
},
"claimInformation": {
"patientControlNumber": "12345",
"payerControlNumber": "00001",
"beginClaimServiceDate": "20050514",
"endClaimServiceDate": "20050614",
"serviceLines": [{
"payerClaimControlNumber": "123456789",
"serviceLineDateInformation" : {
"submissionDate" : "20050514"
},
"attachmentDetails": {
"name": "rightarm.jpg"
}
}]
}
}
```
What does a typical Attachments response from the payer look like?
After the Change Healthcare clearinghouse sends the attachments and receives the payer acknowledgement, you will receive a response body showing the status of the attachments submission. Results may vary based on payer acceptance or non-acceptance of individual attachment files.
Example
```json
Date format: "yyyy-MM-dd'T'HH:mm'Z'"
Sample response:
{
"transactionDetails": {
"submitterId": "TESTSBMTR11111",
"memberId": "0000000001",
"patientFirstName": "doeone",
"patientLastName": "johnone",
"payerId": "TESTEP10",
"providerId": "1760854442",
"providerFirstName": null,
"providerLastName": "happy doctors group",
"claimStartDate": "2021-08-14",
"claimEndDate": "2021-08-15",
"payerName": "VA HEALTH SYSTEM",
"transactionSubmittedDate":"2021-08-16T05:21Z",
"rejectionInformation": null
},
"status": [
{
"statusCode": "10",
"statusMessage": "PARTIALLY_ACCEPTED",
"statusTimeStamp": "2021-08-20T13:25Z",
"documents": [
{
"documentName": "rightarm1.jpg",
"controlNumber": "123456789",
"statusCode": "52",
"statusMessage": "REJECTED_BY_PAYER",
"statusTimeStamp": "2021-08-20T13:25Z",
"rejectionInformation": "File type not supported"
},
{
"documentName": "rightarm.jpg",
"controlNumber": "123456789",
"statusCode": "06",
"statusMessage": "ACCEPTED_BY_PAYER",
"statusTimeStamp": "2021-08-20T13:25Z"
}
]
}
]
}
```
Time stamp values show both the date and time in a specific format. Each individual attachment file in the submission gets a separate object as part of the overall response. This is how you will find out the state of a partial acceptance of attachments from the payer.
For submissions with more than one attachment, you will receive a Partial Acceptance notification as part of the response should one or more submitted files not be accepted.
Above, you see that accepted attachments will simply receive an acceptance time stamp. Rejected attachments will receive a rejectionInformation field briefly describing the reason.
For a longer set of response examples, see the topic Other Kinds of Responses in submissions.
What are the differences between Solicited and Unsolicited Attachments?
The serviceLines JSON object contains the values that define the key difference in Solicited and Unsolicited attachment transactions. For any transaction, in JSON, the key values are:
Unsolicited Attachments
The key JSON elements in Unsolicited attachment transactions are:
-
providerAttachmentControlNumber -
payerAddressand its elements
You send Unsolicited attachments as part of the process of submitting 275 claim transactions, which contain attachments as standard documentation for the claim. The Worker's Compensation claim is a good example; with this claim, it is expected that attachments may be forwarded as a part of the claim submission.
Example
You use the providerAttachmentControlNumber as the control number value in the serviceLines JSON object.
```json
{
"serviceLines": [{
"providerAttachmentControlNumber": "123456789"
}
```
Unsolicited transactions will contain the required payerAddress object, which has the payer's address information. It consists of the following:
```json
"tradingPartnerName":"Happy Payers of Washington State",
"payerAddress": {
"address1": "123 address1",
"city": "city1",
"state": "wa",
"postalCode": "981010000"
},
```
Use this address information in the request body when you need to mail the physical attachments to the payer. This may be necessary when the payer does not support either electronic attachment transactions or fax.
Solicited Attachments
The key JSON elements in Solicited attachment transactions are:
-
payerClaimControlNumber -
tradingPartnerName -
payerAddressand its elements
You typically send Solicited attachments in response to a 277R transaction from a payer that requests additional documentation for a submitted claim.
Example
When you edit the request body, ensure that you have the payerClaimControlNumber as a unique value for each attachment, as the subordinate field to the serviceLines JSON object.
```json
"serviceLines": [{
"payerClaimControlNumber": "123456789",
}
```
Solicited attachment transactions also contain the required payerAddress object, which has the payer's address information. It consists of the following:
```json
"tradingPartnerName":"Happy Payers of Washington State",
"payerAddress": {
"address1": "123 address1",
"city": "city1",
"state": "wa",
"postalCode": "981010000"
},
```
The tradingPartnerName is also required in the JSON request body.
How do I query for a specific Attachments transaction?
The Attachments Status API uses GET and POST requests depending on the endpoint used.
To query for the status of a specific transaction, you use the GET request with two components in the HTTP query path:
- A reference to the transaction's
traceIdvalue in the request - A
fieldsetvalue that defines how much information to show about the transaction
The query does not use a request body.
Using the traceId value in your query path
The traceId specifies the attachment transaction in your query path. It supports the most accurate queries. It requires use of the traceId values that the Change Healthcare system applies to each attachment transaction.
The traceId is a unique 128-bit UUID value (as an example, 3ba21288-3f65-11eb-a512-6ab12069ade5) that Change Healthcare returns to the submitter as an acknowledgement when they receive every new attachments transaction.
NOTE
The customer's back office developers should maintain the
traceIdvalue for every attachments submission record. Whenever a Status query references that value, it should be passed to Admissions Status.
Example
The traceId is a part of the combination value attachmentId that you receive after a successful transaction using the /submission/v1/uploads endpoint:
```json
{
"status": "success",
"attachmentId": "3ba21288-3f65-11eb-a512-6ab12069ade5_12115_999898"
}
```
You specify the first 32 octets from the attachmentId as the traceId in your HTTP query path.
```javascript
GET 'https://apigw.changehealthcare.com/medicalnetwork/attachments/status/v1/3600060b-2325-1180-155f-14671d2b35a8?
```
Using the fieldset argument in your query
You use the fieldset= value in combination with the traceId to form your query. It defines how much information you want to receive in response to your request. fieldset= uses either of two values to show the following:
- Use
fieldset=summaryfor a brief summary of the submission; - The
fieldset=detailedoption shows a more detailed description of the submission.
Example
```javascript
GET 'https://apigw.changehealthcare.com/medicalnetwork/attachments/status/v1/3600060b-2325-1180-155f-14671d2b35a8?fieldset=summary' \
```
```GET 'https://apigw.changehealthcare.com/medicalnetwork/attachments/status/v1/3600060b-2325-1180-155f-14671d2b35a8?fieldset=detailed' \
```
What does a successful Attachments transaction response look like?
Example
For a successful Solicited or Unsolicited transaction, you will receive the following:
```json
{
"status": "success",
"attachmentId": "c8f5fdc7-d71c-5cf8-f68c-2e87eff625bf_12B19_999898"
}
```
Your workflow for API consumers should retain this notification for every transaction they send. It contains a unique value called the traceId, which is a 128-bit UUID value that's generated and sent by the clearinghouse whenever it receives a new attachment transaction.
The traceId is a reference value should a user need to check the status of an Attachments Submission endpoint (/submission/v1/uploads).
The acknowledgement appends the tradingPartnerServiceId (12B19 in this example, which is the Payer ID. This is required to request benefit information from an insurance carrier. This will vary based on the payer you want to connect to. Here is a list of test tradingPartnerServiceId), along with the submitterId (999898 in this example).
How can I check the status of a submission?
Because our APIs do not support push notifications from the clearinghouse or the payer, API users will need to check on the status of attachment transactions that they have sent on behalf of the provider. To do so, use the /attachments/status/v1/{traceId} endpoint, which is closely tied to the/attachments/submission/v1/uploads endpoint, and offers a flexible RESTful query mechanism.
A provider has two different teams; one enters the claim and the other verifies and submits it. Before submitting, can they enter the claim, save it, and have it released when ready?
Our APIs do not have a cache/drafting feature. Customers can develop and automate this feature. Customers should hold the claims on their end and programmatically set up a console to separate working on claims from submitting them.
Fax Numbers and the Attachments Submission API
Any tradingPartnerServiceId can be used to send a fax to the payer by setting payerFaxNumber on the request.
```javascript
"payerFaxNumber": "fax number of the payer",
```
Any tradingPartnerServiceId can be used to send a physical mail packet to the payer by setting the payerAddress on the request.
```javascript
"payerAddress" : { "address1": "123 address1", "city": "city1", "state" : "wa", "postalCode": "981010000"},
```
What are the JSON-to-EDI mappings for the Attachments Submission request?
Example
The following JSON code block shows the direct relationship between JSON fields in an attachment request and the X12 EDI loop associated with each field in the 275 request:
```json
{
"controlNumber": "controlNumber",
"tradingPartnerId": "tradingPartnerId",
"tradingPartnerServiceId": "LOOP 1000A; NM109",
"tradingPartnerName": "LOOP 1000A NM103",
"payerFaxNumber": "fax number of the payer",
"payerAddress": {
"address1": "",
"address2": "",
"city": "",
"state": "",
"postalCode": ""
},
"submitter":
{
"organizationName": "LOOP 1000B NM103",
"firstName": "LOOP 1000B NM104",
"lastName": "LOOP 1000B NM103",
"etin": "LOOP 1000B NM109; "
},
"provider":
{
"organizationName": "LOOP 1000C NM103",
"lastName": "LOOP 1000C NM103",
"firstName": "LOOP 1000C NM104",
"middleName": "LOOP 1000C NM105",
"suffix": "LOOP 1000C NM107",
"npi": "LOOP 1000C NM109",
"taxonomyCode": "LOOP 1000C PRV03",
"providerCommercialNumber": "Loops to 1000C; Maps to REF02; REF01=G2",
"locationNumber": "Loops to 1000C; Maps to REF02; REF01=LU",
"stateLicenseNumber": "Loops to 1000C; Maps to REF02; REF01=0B",
"providerUpinNumber": "Loops to 1000C; Maps to REF02; REF01=1G",
"address":
{
"address1": "LOOP 1100C",
"address2": "LOOP 1100C; maps N302",
"city": "LOOP 1100C; N401",
"state": "LOOP 1100C; N402",
"postalCode": "LOOP 1100C; N403"
},
"phoneNumber": "Used in fax cover sheet",
"faxNumber": "Used in fax cover sheet"
},
"subscriber":
{
"memberId": "LOOP 1000D NM segment; NM108=MI",
"firstName" : "LOOP 1000D NM segment; NM104",
"lastName" : "LOOP 1000D NM segment; NM103"
},
"claimInformation":
{
"patientControlNumber": "LOOP 1000D REF=EJ segment",
"billingTypeIdentifier": "LOOP 1000D REF=BLT",
"medicalRecordIdentifier": "LOOP 1000D REF=EA",
"claimNumber": "LOOP 1000D REF=D9",
"beginClaimServiceDate": "LOOP 1000D DTP segment; DTP01=472; DTP02=RD8",
"endClaimServiceDate": "LOOP 1000D DTP segment; DTP01=472; DTP02=RD8",
"claimServiceDate": "LOOP 1000D DTP segment; DTP01=472; DTP02=D8",
"serviceLines":[ //Note: for each serviceLine, we will add LX segment and keep incrementing LX01
{
"payerClaimControlNumber": "LOOP 2000A; TRNO1=2; Payer Claim Control Number is the value from the TRN segment loop 2200D of the 277 when in response to a solicited request",
"providerAttachmentControlNumber" : "LOOP 2000A TRN01=1; For the unsolicited 275, the Attachment Control Number is the value from PWK06 loop 2300 of the 837. This is the main matching criteria and must be unique on a per attachment basis.",
"claimStatus": [
{
"claimStatusCategoryCode": "LOOP 2000A; STC01-1",
"additionalInformationRequestCode": "LOOP 2000A; STC01-2"
}],
"providerControlNumber": "LOOP 2000A; REF01=6R",
"lineItemControlNumber": "LOOP 2000A; REF01=FJ",
"procedureOrRevenueDetails":
{
"procedureOrRevenueCode": "LOOP 2000A; REF01; valid values: CPT, F8, FO, PRT,RB, VP, YJ, ZZ",
"procedureOrRevenueValue": "value of the code provided in REF01; this would be REF02",
"revenueCode": "LOOP 2000A; REF04-02"
},
"procedureCodeModifier":
{
"serviceChangeNumber": "LOOP 2000A; REF01=SK; REF02",
"objectCode" : "LOOP 2000A; REF04-1=XX4; REF04-2",
"systemNumber": "LOOP 2000A; REF04-3=06; REF04-4",
"specialPaymentReferenceNumber": "LOOP 2000A; REF04-5=4N; REF04-6"
},
"serviceLineDateInformation":
{
"serviceDate": "LOOP 2100A; DTP01=472; DTP03=value; DTP02=D8",
"beginServiceDate": "LOOP 2100A; DTP01=472; DTP03=value ; DTP02=RD8",
"endServiceDate": "LOOP 2100A; DTP01=472; DTP03=value ; DTP02=RD8",
"submissionDate": "LOOP 2100B; DTP01=472; DTP03=value; DTP02=D8"
},
"attachmentDetails":
{
"name": "Should match a file name sent with Form-Data files, Used to complete LOOP 2110B; BIN02 and LOOP 2110B; BIN01"
}
}
]
}
}
```
How do I attach multiple files in one transaction?
Unsolicited and Solicited transactions use different approaches for attaching multiple files. Both transaction types support this feature.
You use the serviceLines object to contain two or more sub-objects in the JSON request body, each representing an attachment file. Each attached document requires its own record as part of the transaction (you cannot just list the filenames under attachmentDetails).
Example
For Unsolicited Attachments transactions, each attachment must have a unique providerAttachmentControlNumber value.
```json
"serviceLines": [{
"providerAttachmentControlNumber": "123456789",
"serviceLineDateInformation" : {
"submissionDate" : "20050514"
},
"attachmentDetails": {
"name": "rightarm.jpg"
}
}
{
"providerAttachmentControlNumber": "123456788",
"serviceLineDateInformation" : {
"submissionDate" : "20050514"
},
"attachmentDetails": {
"name": "rightscapula.jpg"
}
}]
```
For Solicited Attachments transactions, you use the payerClaimControlNumber in the JSON request body and use the same payerClaimControlNumber value in each document record:
```json
"serviceLines": [{
"payerClaimControlNumber": "123412341",
"serviceLineDateInformation" : {
"submissionDate" : "20050514"
},
"attachmentDetails": {
"name": "rightarm.jpg"
}
}
{
"payerClaimControlNumber": "123412341",
"serviceLineDateInformation" : {
"submissionDate" : "20050514"
},
"attachmentDetails": {
"name": "rightscapula.jpg"
}]
}
```
How do I use the API to send a Fax to the payer?
The payerFaxNumber field is the payer fax number that you can use to send a digital fax to the payer. If payerFaxNumber is present and the trading partner is not set up for 275 transactions, a fax will be sent due to your request.
How do I handle payer submissions when they don't support 275 transactions and don't accept faxes?
When the trading partner is not set up for 275 transactions, and the payerFaxNumber is not present, it means that they do not support faxing documents at all. Mailing the attachment document is the only option. Print the document in the highest quality possible, and mail it to the payer if payerAddress information is present.
What file format types does the Attachments Submission API support?
Change Healthcare's Attachments Submission API supports the following formats for 275 attachments: JPG, TIF, TIFF, PDF, JPEG, and PNG.
Change Healthcare’s attachment solution includes workers’ compensation attachments and medical attachments. Any receiver who does not support electronic attachments will receive the documentation through fax or mail.
What do the statusCode Attributes mean?
Our Attachments Status APIs support a series of standard responses, called statusCodes to show various results from submitted attachment transactions. See also statusCode and statusMessage fields. You can use the Attachments Status sandbox environment to exercise attachment API calls and view these results in a safe environment. Doing so helps you get a clear view of how the attachments system works, so you fully understand how to submit documents associated with any medical claim.
NOTE
See Handling Errors in Attachments Submission Transactions for more information about error remediation.
Using our sandbox examples provides the advantage of knowing in advance what can go wrong. Our goal is to enable the sender to solve any issue; and, even better, to avoid issues in the first place.
How do I remediate attachment transaction issues?
Attachment Formatting
Sometimes, attachment formatting may be wrong (for example, attempting to send an encapsulated Postscript file as an image attachment, or a Word document). Images and documents may be encoded improperly and have extra metadata attached to them (that information can often be removed by opening the document's Properties dialog). In these cases, the clearinghouse cannot process them, and you will get a Rejected by CHC as a result. (You will only receive this by using this API — the clearinghouse does not support push notifications.) You will need to correct the issues yourself, because the clearinghouse cannot fix issues in your attachment files.
NOTE
File Sizes
The Change Healthcare clearinghouse flags files of an excessive size. In these cases, you should convert the attachment file to a smaller format or, if possible, reduce the page count of the attachment to contain only the relevant information.
Search Does Not Turn Up a Record
Even when you correctly construct your search, you might receive the following result:
```json
[]
```
The result is an empty array. This is RESTful API's way of telling you that no result matches the search criteria. It could, for example, describe a "patient not found" situation. Try adding other fields to the search, and check their search criteria for data entry errors.
Rejections when a file is known good
If you receive rejections of attachments when the format is good and the file size is acceptable, remove any metadata associated with the file. You can usually edit and remove this information in the file's Properties window.
Properties Window
Fax and Mail Issues
The majority of Attachment failed to Mail or Attachment failed to Fax responses to sent attachments are the result of incorrect formats for files or an attachment that is too large to conveniently mail or fax. Some claims require a substantial amount of information that cannot be reduced for transmission; in these cases, break up the largest attachment files into several smaller ones. Ensure that every document or image is in the correct formats to be accepted by our clearinghouse and that are acceptable to the payer.
Finally, check the request body for missing required JSON attributes. Use our Attachments Submission contents topic to check the details.
See StatusCode responses for more information.
Does the Claim Submission or Claim Status APIs return Customer Account number from the insurance record?
It will have the memberID for the patient, not necessarily the account number from the billing system.
I am new to Change Healthcare and health-tech in general. My provider is in network with Aetna and would like to submit claims using Change Healthcare APIs. When I try to enroll a payer in Connect Center, I find many different payer names with the word Aetna in it.
Which payer should I select? I want to use Change Healthcare APIs for Eligibility, Claims, Claim Status, and ERA. For example, most payers require enrollment to get ERAs through Connect Center. In this case, if our provider is in-network with Aetna, which of the above Aetnas I enroll with?
The best way to know which payer to submit claims to, is to look at the back of the insurance card. That ID should correlate to the Payer ID field.
If you do not have any other identifiable information for Aetna such as, if it is a part of a Better Health plan or an address, use the AETNA/60054 payer IDs.
Where can we get the adjudication message after submitting a claim?
The response you receive at the time of submission would let you know the claim has passed clearinghouse level processing, and will be sent to the payer during our next processing window. The payer-specific response information can be obtained through the Claims Responses and Reports V2 API. The Claims Responses and Reports v2 API provides a direct connection to your mailbox where payers will send their final claims responses and reports. Use this API to access your mailbox for all the files containing complete information about claim payments, claim status updates, and other communications regarding revenue cycles and adjudication from the payer. Refer to this documentation about the recommend files to be used.
Related Topics
Updated about 1 month ago