Standard Attachment Transaction StatusCode Responses
Our Attachment APIs support a series of standard responses, called statusCode, to show various results from submitted attachment transactions. 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 Attachment Submissions Transactions for more information about error remediation.
Our sandbox examples provide the alerts you about what can go wrong. Our goal is to enable the sender to solve any issues; and, even better, to avoid issues in the first place.
How do you use our sandbox?
A list of test payers in the sandbox are each bound to specific statusCode message types. Use these payer IDs to test specific message types in the sandbox; they are not valid for use with the live API.
When you use the sandbox to run example for Attachments transactions, you can attach any sample documents you want for testing.
Rejections of Attachment Transactions by Payers
Many EDI 276 transaction responses reporting a failed attachment reception will also show a rejectionInformation attribute. This field carries information that is added by the payer to explain why the attachment was rejected. This data does not originate with Optum and is entirely optional for the payer. In other words, the payer may reject a transaction for any reasons and not offer any explanation at all. It is best for submitters of any attachment transaction to err on the side of caution, ensure that all documents conform to file format standards, and avoid sending overly large graphic files.
How to Use the Test Payers in the Sandbox API
You can use your API client to test all of our API response types in the sandbox. You do this using a separate Test Payer ID, which is unique for each response type. All IDs for API responses types follow a specific naming pattern:
TEST<EP/PP><StatusCode>
- EP stands for Electronic Payer (a payer that supports electronic attachment submissions)
- The two-digit Status Code (01, 02, ...) This is the status code identifying the response type for which the payer is configured
As in: TESTEP02
How to use the test payer accounts for each Attachments API response type
- Submit an attachment using the Attachments Submission API. Use a test payer ID for each response type.
- After successful submission, the API returns the
traceIdin the response header. - Send an API request for an Attachment Status API summary/detail endpoint using this
traceIdor to the/metadataendpoint using transaction dates along with any filtering criteria you want to use. - The Attachment Status API returns a pre-defined Sandbox status response that is configured for that
payerId. - The metadata search returns a list of matching transactions with their
traceIdand corresponding statuses. AlltraceIdscorresponding to a testpayerIdfrom the following lists will return a test status messages. If anytraceIdvalues appear that do not belong to the payer list, the result returns the actual status from the database.
All notifications apply to payers accepting both Solicited and Unsolicited attachments unless noted otherwise.
StatusCode Responses
StatusCode and StatusMessage Fields
The statusCode and statusMessage fields are a code pair that simply describe the current non-failure state of the attachment transaction. The message TRANSACTION_RECEIVED (statusCode 01) shows that the attachment's been received by the clearinghouse. The following sections show the other messages included and relevant examples.
TESTEP01 Test PayerId
If you use the sandbox with this test payerId, you will receive this message stating that the clearinghouse has successfully received your submitted attachments transaction.
```json
[
{
"statusCode": "01",
"statusMessage": "TRANSACTION_RECEIVED",
"statusTimeStamp": "2021-08-19T18:27Z",
"documents": [
{
"documentName": "rightarm.jpg",
"controlNumber": "123456789"
}
]
}
]
```
Transaction Accepted by Clearinghouse
TESTEP02 Test PayerId
If you use the sandbox with this test payerId, you will receive this message stating that the clearinghouse has accepted your submitted attachments transaction.
```json
[
{
"statusCode": "02",
"statusMessage": "ACCEPTED_BY_CHC",
"statusTimeStamp": "2021-05-13 10:33",
"documents": [
{
"documentName": "rightarm.jpg",
"controlNumber": "51827660-012714"
}
]
}
]
```
Successful Reception of Attachment by Payer
TESTEP04 Test PayerId
If you use the sandbox with this test payerId, you will receive this notification when the clearinghouse delivers the attachment(s) to the payer. At this point, the clearinghouse has forwarded the attachment to the payer.
```json
[
{
"statusCode": "04",
"statusMessage": "DELIVERED_TO_PAYER",
"statusTimeStamp": "2021-08-19T18:43Z",
"documents": [
{
"documentName": "rightarm.jpg",
"controlNumber": "123456789"
}
]
}
]
```
Acknowledgement of Attachment Reception by Payer
TESTEP05 Test PayerId
The payer sends acknowledgement of your attachment transmission through the clearinghouse. It indicates they received your transaction and will evaluate it for accuracy and usability. This does not indicate payer acceptance of the transaction.
```json
[
{
"statusCode": "05",
"statusMessage": "ACKNOWLEDGED_BY_PAYER",
"statusTimeStamp": "2021-08-20T13:22Z",
"documents": [
{
"documentName": "rightarm.jpg",
"controlNumber": "123456789"
},
{
"documentName": "rightarm1.jpg",
"controlNumber": "123456789"
}
]
}
]
```
Acceptance of Attachment by Payer
TESTEP06 Test PayerId
If you use the sandbox with this test payerId, you will receive this notification indicating a fully successful attachment transaction.
```json
[
{
"statusCode": "06",
"statusMessage": "ACCEPTED_BY_PAYER",
"statusTimeStamp": "2021-08-20T13:36Z",
"documents": [
{
"documentName": "rightarm.jpg",
"controlNumber": "123456789"
},
{
"documentName": "rightarm1.jpg",
"controlNumber": "123456789"
}
]
}
]
```
Partial Acceptance of Multiple Attachments
NOTE
The TESTEP10 Test Payer ID is designed for the "Partially Accepted" use case. Use at least two attachments in the same sandbox API request to receive an accurate response for this use case.
This response occurs when the payer accepts one or more files while rejecting others in a transaction with multiple files. The rejectionInformation field may or may not be part of the response in real-life transactions, and its data contents are up to the payer to provide. You can convert the file to the correct format and re-send it in a separate transaction. Ensure that all documents conform to file format standards and also avoid sending files that exceed more than a few megabytes each. For example, modern cell phones can produce photos that are in excess of 6 to 8 megabytes in size; take measures to reduce their size before sending. Some diagnostics files, when sent in PDF format, may also exceed payer file size limits and need to be broken up into several smaller files.
TESTEP10 Test PayerId
```json
[
{
"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",
},
{
"documentName": "rightarm.jpg",
"controlNumber": "123456789",
"statusCode": "06",
"statusMessage": "ACCEPTED_BY_PAYER",
"statusTimeStamp": "2021-08-20T13:25Z"
}
]
}
]
```
Rejection of attachment transaction by clearinghouse
TESTEP51 Test PayerId
In this test case, the clearinghouse is rejecting the transaction due to errors. The clearinghouse will reject attachments with the wrong format and will not convert any file in an incorrect format; the sender must fix the problem and re-send. See format types supported for more information. If information is missing from the request body, Optum may detect that and reject it for that reason.
```json
"status": [
{
"statusCode": "51",
"statusMessage": "REJECTED_BY_CHC",
"statusTimeStamp": "2021-08-19T18:34Z",
"documents": [
{
"documentName": "rightarm.doc",
"controlNumber": "123456789"
}
]
}
]
}
```
The clearinghouse may contribute information for the rejectionInformation field. You may or may not receive helpful information here, so it is important to address any possible issues before sending the transaction to the clearinghouse through the API:
```json
"rejectionInformation": "File type not supported"
```
Rejection of Attachment by Payer
TESTEP52 Test PayerId
In this test case, the payer rejects the attachment. Notification reaches the clearinghouse who forwards the results back to the submitter. Payers may reject an attachment due to excessive file sizes. CHAMPUS is a good example. File size is the most frequent issue in this use case.
```json
"status": [
{
"statusCode": "52",
"statusMessage": "REJECTED_BY_PAYER",
"statusTimeStamp": "2021-08-20T13:17Z",
"documents": [
{
"documentName": "rightarm.jpg",
"controlNumber": "123456789"
},
{
"documentName": "rightarm1.jpg",
"controlNumber": "123456789"
}
]
}
]
```
The payer can optionally contribute information for the rejectionInformation field. You may or may not receive helpful information here, so it is important to address any possible issues before starting the transaction. Of course, the rejections do not apply when you are exercising these calls in the sandbox but they definitely apply when you are exercising the API in the real world:
```json
"rejectionInformation": "Attachment type not supported"
```
Rejection of Attachment Due to Request Validation Error
TESTEP53 Test PayerId
The status message is dynamic depending on the type of validation failure.
```json
{
"statusCode": "53",
"statusMessage": "Missing required fields transactionReceivedStartDate,transactionReceivedEndDate."
}
```
Payer Accepted with Errors
TESTPP19 Test PayerId
"status": [
{
"statusCode": "19",
"statusMessage": "ACCEPTED_BY_PAYER_WITH_ERRORS",
"statusTimeStamp": "2021-08-19T19:27Z",
"documents": [
{
"documentName": "rightarm.jpg",
"controlNumber": "123456789"
}
]
}
]
Too Many Records TESTPP54 Test PayerId text Too Many Records Example 19
"status": [
{
"statusCode": "54",
"statusMessage": "There are more than 100 records found. Please refine your search criteria"
}
]
Unable to Process Request TESTPP56 Test PayerId text Unable to Process System Error Example 20
json
"status": [
{
"statusCode": "56",
"statusMessage": "Unable to process the request at this time, please try again later"
}
]
Understanding Transaction Details
Detailed responses to submissions and to status queries will show the traceId of each, with a transactionDetails object:
[
{
"traceId": "<actual trace id of the transaction from DB>",
"transactionDetails": {
"submitterId": "TESTSBMTR11111",
"memberId": "0000000001",
"patientFirstName": "doeone",
"patientLastName": "johnone",
"payerId": "TESTEP05",
"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": "05",
"statusMessage": "ACKNOWLEDGED_BY_PAYER",
"statusTimeStamp": "2021-08-20T13:22Z",
"documents": [
{
"documentName": "rightarm1.jpg",
"controlNumber": "123456789"
},
{
"documentName": "rightarm.jpg",
"controlNumber": "123456789"
}
]
}
]
}
]
Details include the core information for the transaction submitter. It includes information about the medical provider, the patient, the payer ID and their entity name, and claim dating information. It is followed by the summary status report for the submission. In this case, it is a successful submission. Because the summary content differs in every response type, each subsection below contains only the summary data, because the transactionDetails object will be the same across the board.
NOTE
Select Attachments features are not yet supported by the sandbox standard responses. For more information, see Unsupported use cases.
Unsupported use cases
Metadata Search Error messages
The Attachment Status API /attachments/status/v1/metadata supports a powerful metadata search feature. It supports use of common-sense search criteria to find transaction records based on a patient's or provider's name, or by many other possible data points. You can filter using multiple search criteria. A typical metadata search error message consists of: There are more than 100 records found. Please refine your search criteria. It indicates that your search is too broad. Use other search criteria to filter your replies for better accuracy.
NOTE
The Metadata Search use case is not supported by the
statusCodefunctionality, so you will not see this error demonstration in the sandbox. Future updates may support this feature.
Unable to Process Errors message
For occasional problems in API operation, such as temporary connection problems, you will receive an Unable to process the request at this time, please try again later message. It is a generic error message for Attachments submissions that simply did not go through. Check the handling errors in Attachment Submissions transactions topic for more information.
NOTE
The Unable to Process use case is not supported by the
statusCodefunctionality, so you will not see this error demonstration in the sandbox. Future updates may support this feature.
Updated 1 day ago