How does the metadata search work?

Using Metadata Search

The Attachment Status API also supports the use of descriptive information, known as metadata, to check for attachment transactions. You don't need the traceId to search for attachment transactions for a particular claim or a patient. (This search tool is used for any cases where you do not have the Trace ID.) Using metadata search, you can use a range of dates, the patient's name, the provider's name, and so on, as a combination search. Add these search criteria into the request body.


You use an HTTP 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.

Required Metadata Search Values

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

submitterIdThe ID number of record for the submitter of the transaction
transactionReceivedStartDateThe start date for which the transaction was sent
transactionReceivedEndDateThe 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.

Filtering Metadata Searches

To filter a metadata search query, add one or more of the following optional data attributes:

memberIdThe patient's medical ID number
patientFirstNameThe Patient's first name
patientLastNameThe Patient's last name
providerIdThe Medical Provider ID
providerFirstNameThe first name of the medical provider
providerLastNameThe last name of the medical provider
controlNumberThe generated control number for the medical encounter
claimEndDateEnd date of the medical claim
claimStartDateOpening date of the claim
payerIdIdentification number of the Payer to whom the claim is submitted

To make the search more accurate, add one or two metadata values in the request body:

POST '' \

        "submitterId": "TESTSBMTR11111",
        "transactionReceivedEndDate": "2005-05-14",
        "transactionReceivedStartDate": "2005-05-11",
        "memberId": "0000000001"
NOTE: 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 '' \

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

Metadata Search Responses

Details and Status for a Single Attachment Description
       "traceId": "<actual trace id of the transaction from DB>",
       "transactionDetails": {
           "submitterId": "TESTSBMTR11111",
           "memberId": "0000000001",
           "patientFirstName": "doeone",
           "patientLastName": "johnone",
           "payerId": "TESTEP01",
           "providerId": "111222333",
           "providerFirstName": null,
           "providerLastName": "happy doctors group",
           "claimStartDate": "2005-05-14",
           "claimEndDate": "2005-05-14",
           "payerName": "TEST HEALTH SYSTEM",
           "rejectionInformation": null
       "status": [
               "statusCode": "01",
               "statusMessage": "TRANSACTION_RECEIVED",
               "statusTimeStamp": "2021-08-19T18:27Z",
               "documents": [
                       "documentName": "rightarm.jpg",
                       "controlNumber": "123456789"

Most of the information that appears in a metadata search record is transactionDetails content that originates from the transaction. If the transaction was successful, you can expect to see a NULL value for the rejectionInformation field in the response.

The statusCode and statusMessage fields are a code pair that simply describes the current non-failure state of the attachment transaction. The message TRANSACTION_RECEIVED (statusCode 01) shows that the attachment's been received by the Change Healthcare clearinghouse. Other messages include:

    (statusCode 04)
    (statusCode 05)
    (statusCode 06)
    (statusCode 10)
    (statusCode 11)
    (statusCode 12)

Check the topic Standard Attachment Transaction statusCode Responses for more information about status messages.

Status for Multiple Attachments in a Transaction Description
"status": [
        "statusCode": "10",
        "statusMessage": "PARTIALLY_ACCEPTED",
        "statusTimeStamp": "2021-08-24T19:21Z",
        "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"

If you send multiple documents for a single transaction, the status object for that submission can yield a PARTIALLY_ACCEPTED status. It separately shows each file's status, as the payer processes each attachment file. Each file rejection will be noted with a rejectionInformation field. Check the topic What do the status codes mean? for information about all the status messages.

Did this page help you?