Metadata Search Feature

Using Metadata search

The Attachment Status API also supports the use of descriptive information, known as metadata, to check for attachment transactions. You do not need the traceId (the attachment submitted ID returned to submitters or payers when they submit the claim attachment. A traceId can also be retrieved by calling the following metadata endpoint.) 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 the metadata search, you can use a range of dates, patient's name, provider's name, and so on, as a combination search. Add these search criteria into the request body.

```json
POST https://sandbox-apigw.optum.com/medicalnetwork/attachments/status/v1/transactionStatus/metadata
```

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:

FieldDefinition
submitterIdID of record for the submitter of the transaction.
transactionReceivedStartDateStart date for which the transaction was sent.
transactionReceivedEndDateDate on which the transaction was completed.
📝 Dates must be in YYYY-MM-DD format, 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 field is required; it prevents the API users from searching for medical information to which they do not 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:

FieldDefinition
memberIdPatient's medical ID.
patientFirstNamePatient's first name.
patientLastNamePatient's last name.
providerIdMedical Provider ID.
providerFirstNameFirst name of the medical provider.
providerLastNameLast name of the medical provider.
controlNumberGenerated 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.

Metadata search request

To make the search more accurate, add one or two metadata values in the request body. See example in Metadata Search Request & Response.

📘

NOTE

Do not use the traceId value as a metadata search criteria.

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

Metadata search responses

Details and Status for a single Attachment. See example in Metadata Search Request & Response.

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.

StatuCode 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. Other messages include:

StatusMessageStatusCode
TRANSACTION_RECEIVEDstatusCode 01
ACCEPTED _BY_CHCstatusCode 02
DELIVERED_TO_PAYERstatusCode 04
ACKNOWLEDGED_BY_PAYERstatusCode 05
ACCEPTED_BY_PAYERstatusCode 06
PARTIALLY_ACCEPTEDstatusCode 10
REJECTED_BY_CHCstatusCode 11
REJECTED_BY_PAYERstatusCode 12

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

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. See What do the status codes mean? for information about all the status messages.

Related Topic