Attachments Status v1

Summary API Attachments FAQ CHANGE LOG     

Overview

The Attachment Status API enables customers to query for the status of attachment transactions (typically sending of medical information attachments) that they have submitted to their payer. The Attachment Status API takes the transaction details and returns status information in a format that's understandable to the customer.

For example, consider a provider sending an attachment to the Veteran's Administration. How do they know it was received? Did Change Healthcare receive it? Was it processed and delivered to the payer? Did the payer accept it? When the customer wants to know the status of any attachment transaction, they can use our Status API to find out the status of medical data they've sent to their payer.

NOTE: Change Healthcare's Attachment Submission and Attachment Status APIs don't support push notifications. You can obtain the status of any of your claims or related attachment submissions by using the Change Healthcare Claim Status API and the Attachment Status API (described here).

Through our attachment submission APIs, the Change Healthcare clearinghouse processes provider-submitted attachment transactions before forwarding the documents to the payer. Using the Attachments Status API queries, you may receive responses directly from Change Healthcare, or responses that originate from the payer.

See the FAQ page for more detailed information.

NOTE: The Change Healthcare Marketplace Attachment Submissions API is a prerequisite for using the Attachment Status API.

You can search for all attachments transactions for a given patient or provider over a period of time. The Attachment Status API takes measures to ensure privacy by tying all requests to the specific Submitter ID associated with the API consumer.

API Endpoints

The endpoints for the Attachment Status API collection are as follows.

  • The primary Attachment Status query API endpoint (it supports both GET and POST methods):

    https://apigw.changehealthcare.com/medicalnetwork/attachments/status/v1/

    The endpoint supports two types of searches: a highly targeted search using transaction traceId values, which are unique for every transaction; and broad searches using a set of metadata filters that specify search criteria. See the FAQ page for more information.

  • The Attachment Status collection provides a GET /healthcheck call to check that the service you're trying to use is up and running. The API engine replies with the API version number and an OK message:

    https://apigw.changehealthcare.com/medicalnetwork/attachments/status/v1/healthcheck

  • Each of our API collections also contains an endpoint instance for obtaining new authorization tokens:

    https://apigw.changehealthcare.com/apip/auth/v2/token

API Onboarding

Most of our APIs are private and require credentials to gain access. Begin by obtaining your client_id and client_secret for our sandbox test environment. (Contact your Change Healthcare representative if you do not have this information.)

Find out more about our security protocols and their implementation.

NOTE: You use a separate Change Healthcare-issued credential pair for your production API work.

You can test the APIs from within our interactive documentation (see the API page), use an application such as Postman, or use your own development platform.

  • Try our Postman collection! Run in Postman

The goal for onboarding is to ensure API customers can automate their API consumption process. For end use, API consumption shouldn't require 'seeing' the APIs; preferably, a number of tasks can be automated:

  • API bearer token automation, using OAuth2 token retrieval.
  • A data entry console to make claims requests and eligibility requests. It's a characteristic feature of medical facilities where public medical encounters take place.
  • Abstraction of the majority of complex data that's required for a successful request, so you can easily make Status requests and efficiently get replies. For example, Control Numbers exist in all of our APIs as a required value that's generated, assigned and sent by the provider or institution to identify each transaction. When the provider's office sends a request, they should never have to worry about defining and entering those values, and they should be handled programmatically.
  • Auditing and tracking for all transactions.
  • Actionable information to aid in solving problems and successfully completing medical network tasks.

For token automation, you can apply one of the following:

  • Get a unique token for each transaction.
  • Apply the same token across all transactions during the full token lifespan and automatically refresh the token just before it expires. Tokens for production APIs have a two-hour/7200 second lifespan.

NOTE: We suggest automating transactions to use the tokens generated over the token lifespan. Obtaining tokens for each individual transaction is less efficient and does not improve the security posture for any transaction.

Using the API

In our interactive documentation, select the API tab, and select the green POST API object. Scroll down to the Authorization field, enter the word Bearer, and paste your token into the Bearer Token field.

If you are using our Postman collection or a similar development console, ensure your client_id and client_secret for your production account are installed in your Authorization API request body. Preferably, you can set up your environment variables to refer to your credentials whenever you require a token. If you correctly set up your environment variables, you can install the collection in Postman (for example), and simply run its Token Authorization API to obtain a token whenever you need it, which will automatically be used by the other APIs in the collection.

For Sandbox and production API testing, you can also edit the request body. Don't use real-world values in Sandbox API usage. Doing so will produce errors.

For Sandbox usage, we also provide predefined values to simulate Personal Medical Information (PMI) in the Sandbox environment. For successful use of Sandbox APIs, you must use these "fake patient" values for your testing. Consult the Sandbox Test PMI Values document located in the Attachments tab.

For further details about Attachment Status API usage, see the FAQ page.

Links to Attachment Status FAQ Topics

You'll find the following topics on this page:

Accessing the Attachment Status APIs

How do I access the Production APIs?

What are the endpoints for getting authorization tokens?

What information needs to go in the API Request header?

Using the Sandbox environment

Do you have a sandbox that I can test before signing a contract?

How do I access the Sandbox environment?

Sandbox predefined fields and values

Using the Attachment Status APIs

How do I query for a specific Attachments transaction?

What does the metadata search do?

What do typical API responses look like?

Understanding API features

What do the statusCodes mean?

How to remediate attachment transaction issues

Accessing the Attachment Status APIs

How do I access the Production APIs?

  • This is the primary Attachment Status verification API endpoint:

    https://apigw.changehealthcare.com/medicalnetwork/attachments/status/v1/

  • The Attachment Status collection also provides a GET /healthcheck call to check that the service you're trying to use is up and running. The API engine replies with the API version number and an OK message:

    https://apigw.changehealthcare.com/medicalnetwork/attachments/status/v1/healthcheck

What are the endpoints for getting authorization tokens?

  • For secure use of our APIs, each of our API collections also contains an instance of this endpoint for getting Bearer authorization tokens. The Bearer token endpoint URL is as follows:

    https://apigw.changehealthcare.com/apip/auth/v2/token/

    Bearer tokens have a two-hour lifespan (7200 seconds) in production.

Find out more about our security protocols and their implementation here.

What information needs to go in the API Request header?

You must pass a Bearer authorization token in the header for an Attachment Status API request. You can get the token by making an API call to:

curl -X POST \
  'https://apis.changehealthcare.com/apip/auth/v2/token/' \
  -H 'Content-Type: application/json' \
  -d '{
  "client_id": "<Your-ClientId>",
  "client_secret": "<Your-ClientSecret>",
  "grant_type": "client_credentials"
}'

The authorization token is a requirement for making an Attachment Status API call, which will have the following headers:

Content-Type: application/json
Authorization: Bearer <Your-Access-Token>

In production, the lifespan of a token is two hours (7200 seconds). For Sandbox use, a token lifespan is one hour.

Using the Sandbox environment

Do you have a sandbox that I can test before signing a contract?

We do! You can use our Sandbox environment even before signing a contract. It requires a separate set of secure credentials which you can obtain from your Change Healthcare representative. After receiving your client_id and client_secret for our Sandbox environment, you can test the API in our interactive documentation, use an application such as Postman, or test APIs using your own development console.

Try our Postman Collection! Run in Postman

We have a list of test service ID values to use in Sandbox for testing a variety of different responses. See the section Sandbox predefined fields and values below.

How do I access the Sandbox environment?

  • The Sandbox endpoint URL for authorization tokens is as follows:

    https://sandbox.apigw.changehealthcare.com/apip/auth/v2/token/

    Authorization tokens have a lifespan of 3600 seconds (1 hour) in the Sandbox environment.

  • For testing, the Sandbox Attachment Status API endpoint is as follows:

    https://sandbox.apigw.changehealthcare.com/medicalnetwork/attachments/status/v1/

  • The Healthcheck Sandbox URL for this API set is as follows:

    https://sandbox.apigw.changehealthcare.com//medicalnetwork/attachment/status/v1/healthcheck

Sandbox predefined fields and values

You can edit fields in the HTTP request body to see how the API works with changes to the data. For Sandbox use, you are limited to a specific set of values.

We provide predefined values to simulate Personal Medical Information (PMI) in the Sandbox environment. If you haven't seen these before, consult the Sandbox Test PMI Values document located in the Attachments tab.

For Sandbox usage, all fields must have the correct predefined values to obtain a successful response. Inventing new PMI values or using real-world PMI values will result in errors such as the messages listed below.

The following JSON fields must use one of the following predefined values in Sandbox:

Field Values
memberId "0000000000", "0000000001", "0000000002", "1234567890", "0000000004", "0000000005", "0000000006","0000000007", "123456789"
firstName "johnone", "johntwo", "janeone", "janetwo"
lastName "doeone", "doetwo"
middleName "middleone", "middletwo"
gender "m", "u", "f"
dateOfBirth "18800102", "18800101", "18160421", "19800101", "19800102", "20000101", "20000102"
ssn "000000000", "555443333", "1111111111", "000000001", "891234567", "123456789"
groupNumber "0000000000", "1111111111","1234567891","0000000001", "0000000002", "0000000003", "0000000004", "0000000005"
address1 "123 address1", "000 address1"
address2 "apt 123", "apt 000", "123", "000"
city "city1", "city2"
state "wa", "tn"
postalCode "981010000", "372030000"
employerId "00000", "12345","00001","00002","000000000", "123456789","123456"
propertyCasualtyClaimNumber "00000", "12345","00001","00002"
patientControlNumber "00000", "12345","00001","00002"
priorAuthorizationNumber "00000", "12345","00001","00002"
referralNumber "00000", "12345","00001","00002"
repricedClaimNumber "00000", "12345","00001","00002"
investigationalDeviceExemptionNumber "00000", "12345","00001","00002"
claimNumber "00000", "12345","00001","00002"
name "johnone doeone", "johntwo doetwo", "janeone doeone", "janetwo doetwo", "submitter contact info"
phoneNumber "0000000000", "123456789", "0000000001", "0000000002"
faxNumber "0000000000", "123456789", "0000000001", "0000000002"
email "email@email.com", "email@email.net"
stateLicenseNumber "0000000", "0000001", "123456"
contractVersionIdentifier "111111", "222222", "123456"
patientControlNumber "00000", "12345","00001","00002"
priorAuthorizationNumber "00000", "12345","00001","00002"
referralNumber "00000", "12345","00001","00002"
claimControlNumber "00000", "12345","00001","00002"
cliaNumber "12D4567890", "00D0000001"
repricedClaimNumber "00000", "12345","00001","00002"
mammographyCertificationNumber "00000", "12345","00001","00002"
medicalRecordNumber "00000", "12345","00001","00002"
demoProjectIdentifier "00000", "12345","00001","00002"
carePlanOversightNumber "00000", "12345","00001","00002"
policyNumber "00000", "12345","00001","00002"
npi "1760854442", "1942788757"
organizationName "happy doctors group", "happy doctors grouppractice","extra healthy insurance", "regional ppo network"

NOTE: TradingPartnerServiceId 9496 is a test payer and is the only payer allowed for use in Sandbox.


If you don't use the predefined values, you will receive errors like the following:

{
    "errors": [
        {
            "field": "subscriber",
            "description": "Please use predefined canned users for non-prod environments: policyNumber was not predefined."
        },
        {
            "field": "claimInformation",
            "description": "Please use predefined canned users for non-prod environments: patientControlNumber was not predefined."
        },
    ]
}

Using the Attachment Status APIs

How do I query for a specific Attachments transaction?

The Attachment Status API uses GET and POST calls depending on the endpoint you use.

To query for the status of a specific transaction, you use the GET method with two components in the HTTP query path:

  • A reference to the transaction's traceId value in the request
  • A fieldset value 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

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.

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 must ensure that the `traceId` value is maintained for every attachment submission record. It should pass that value to Admissions Status whenever a query references that value.

The traceId is part of the combination value attachmentId that you receive after a successful transaction using the Attachment Submissions API:

{
    "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.

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 receive in response to your request. fieldset= uses either of two possible values to show the following:

  • Use fieldset=summary for a brief summary of the submission
  • The fieldset=detailed option shows a more detailed description of the submission
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 the metadata search do?

The Attachment Status API also supports the use of descriptive data, known as metadata, to check for attachment transactions. So you don't need the traceId to search for attachment transactions for a particular claim or a patient. If you don't have the traceId, you can use a range of dates, the patient's name, the provider's name, and so on, as a combination search.

POST 'https://api-dev.apip.awsnonprod.healthcareit.net/medicalnetwork/attachments/status/v1/transactionStatus/metadata'

You use a request body to specify the metadata values to search for transaction records. The request body contains a few mandatory values, along with several optional values to improve query accuracy.

When you have more than one match for a search, the API lists all matching transaction records in one response body.

All metadata queries must have the following data attributes in the request body:

Field Definition
submitterId The ID number of record for the submitter of the transaction
transactionReceivedStartDate The start date for which the transaction was sent
transactionReceivedEndDate The date on which the transaction was completed

Dates must be formatted in YYYY-MM-DD, as in 2021-03-31.

NOTE: The mandatory Start Date and End Date values define a range, so your request can query for the status of all attachment transactions for the submitter during that time period. You can further focus these queries using the patient's name and other optional metadata values. This query is possible only by metadata search.

The submitterId is required; it prevents API users from searching for medical information to which they don't have legal access, whether mistakenly or deliberately.

Add one or more of the following optional data attributes to filter a metadata search query:

Field Definition
memberId The patient's medical ID number
patientFirstName The Patient's first name
patientLastName The Patient's last name
providerId The Medical Provider ID
providerFirstName The first name of the medical provider
providerLastName The last name of the medical provider
controlNumber The generated control number for the medical encounter
claimEndDate End date of the medical claim
claimStartDate Opening date of the claim
payerId Identification number of the Payer to whom the claim is submitted

For more effective and convenient searches, start by adding one or two metadata values in the request body to make the search more accurate:

POST 'https://sandbox.apigw.changehealthcare.com/medicalnetwork/attachments/status/v1/metadata' \

    {
        "submitterId": "TESTSBMTR11111",
        "transactionReceivedEndDate": "2005-05-14",
    "transactionReceivedStartDate": "2005-05-11",
    "memberId": "0000000001"
    }

You'll never use the traceId value as a metadata search criteria.

Add more attributes in the request body to narrow the search if necessary:

POST 'https://sandbox.apigw.changehealthcare.com/medicalnetwork/attachments/status/v1/metadata' \

    {
        "submitterId": "TESTSBMTR11111",
        "transactionReceivedEndDate": "2005-05-14",
    "transactionReceivedStartDate": "2005-05-11",
    "memberId": "0000000001",
        "providerId": "1760854442",
        "payerId": "9496"
    }

What do typical API responses look like?

The following response shows a payer rejection of a previously sent EDI 275 submission when you send a query using a trackId value with a fieldset=summary argument:

[
  {
    "statusCode": "51",
    "statusMessage": "REJECTED_BY_PAYER",
    "statusTimeStamp": "2020-12-16 06:14",
    "documents": [{
      "documentName": "rightarm.jpg",
      "controlNumber": "123456789"
    }]
  }
]

A query using the fieldset=detailed argument gets a response similar to the following:

{
    "transactionDetails": {
    "submitterId": "TESTSBMTR11111",
    "payerId": "6405"
    "memberId": "0000000001",
    "patientFirstName": "doeone",
    "patientLastName": "johnone",
    "providerId": "1760854442",
    "providerFirstName": "testProvider",
    "providerLastName": "happy doctors group",
    "claimEndDate": "2005-05-14",
    "claimStartDate": "2005-05-14",
    "payerName": "Mutual Liberty"
    },
    "status":[{
        "statusCode": "51",
        "statusMessage": "REJECTED_BY_PAYER",
        "statusTimeStamp": "2020-12-16 06:14",
        "documents": [{
          "documentName": "rightarm.jpg",
          "controlNumber": "123456789"
        }]
    }]
}

What do the statusCodes mean?

Every response to an Attachment Status request contains the following information:

Field Definition
statusCode The ID number of record for the submitter of the transaction
statusMessage The message associated with the code
statusTimeStamp The date and time when the reported status was issued by the API responder

The statusCode values and messages in responses are as follows:

  • Code 01 Transaction Received: CHC has successfully received your EDI 275 attachment transaction. No further action is needed at this time.

  • Code 02 Accepted by CHC: The Change Healthcare (CHC) clearinghouse has received your attachment submission but nothing further has yet taken place.

  • Code 03 In Process: The attachment submission has been accepted by CHC and it is being processed before submitting to the payer. No further action is needed at this time.

  • Code 04 Delivered To Payer: Change Healthcare has finished validating and processing the attachment submission and forwarded it to the payer, but the payer has not yet accepted the submission. No further action is needed at this time.

  • Code 05 Accepted by Payer: The attachment submission is received and accepted by the payer as part of the associated claim. No further action is needed.

  • Code 06 Acknowledged by Payer: Acknowledgement from the payer (forwarded by the clearinghouse) that they've received the submission.

  • Code 07 Accepted: The final Accepted status of the attachment submission; it has been processed and accepted by both CHC and the Payer.

  • Code 08 Rejected: Final Rejected status of the submission; it has been rejected by the payer.

  • Code 51 Rejected by CHC: You may receive this when CHC's clearinghouse detects an issue with the attachment submission before it's forwarded to the payer. Because CHC won't fix incorrect or missing attributes, incorrect file formats or other possible data file issues, you will need to take care of these issues yourself and re-submit. Ensure that all of your submissions' attributes contain the correct information before resubmitting.

  • Code 52 Rejected by Payer: The payer has rejected the EDI 275 attachment submission. The most common reason is that the payer has found missing or incorrect X12 EDI data in the submission. Those errors likely originate in the JSON request body from the original submission; the CHC clearinghouse translates its content to X12 EDI before transmitting it to the payer. Check all attributes in your submission before re-submitting.

  • Code 53 Validation Error: Occurs when you don't define the correct fieldset= value in the HTTP query path. It must be summary or detail. This error does not apply to metadata searches.

  • Code 54 Too many records: Your metadata search criteria are too broad. You're limited to 100 match instances for any single metadata search. If more matches exist, you will need to narrow your search.

NOTE: You typically want transactions to be accepted by the payer without further delays. One advantage of using Change Healthcare's Attachment Submission and Attachment Status APIs is that our clearinghouses do some validation and verification of submissions before they're sent to the payer. It reduces the chance of attachments being rejected by the payer, incurring further delays due to mistakes or missing information. There's no substitute, however, for ensuring the attachment submission is fully correct and its files are in the correct format before sending.

The following response shows the successful conclusion of an attachments transaction, since it is accepted by the payer as a part of the medical claim.

[
  {
    "statusCode": "05",
    "statusMessage": "ACCEPTED_BY_PAYER",
    "statusTimeStamp": "2020-12-16 06:14",
    "documents": [{
      "documentName": "rightarm.jpg",
      "controlNumber": "123456789"
    }]
  }
]

How do I remediate attachment transaction issues?

Attachment Formatting. Sometimes, attachment formatting may be wrong (attempting to send an encapsulated Postscript file as an image attachment, or a Word document, for example). 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 can't process them, and you'll get a Rejected by CHC as a result. (You'll 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 can't fix issues in your attachment files.

NOTE: Change Healthcare supports the following formats for 275 attachments: JPG, BMP, GIF, TIF, TIFF, PDF, DOC, DOCX, TXT, RTF, JPEG, and PNG. Some payers support fewer file format types.

File Sizes. The CHC clearinghouse will flag files that are an excessive size. In these cases, you'll need to convert the attachment file to a smaller format, or 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:

[]

The result is an empty array. This is the RESTful API's way of telling you that no result matches the search criteria. this result describes a "patient not found" situation. The user can try adding other fields to the search, and check their search criteria for data entry errors.

Change Log

API Name API Version Date Introduced Available Until
Attachment Status API v1 December 22, 2020 TBD

Release Notes:

v1

  • Initial release of the Attachment Status API
  • 3/8/2021 Update: New Endpoint URLs for the Attachment Status API