Claim Attachments API

Updated on Wed, 04/02/2025 - 08:07

Jump To Section

Claim Attachments 1.0.0

Claim Attachments 1.0.0

Claim Attachments is an external API that allows clearinghouses to submit medical claim attachments. It supports two primary workflows:

Unsolicited Claim Attachment – This workflow allows providers to submit medical documentation to support the adjudication of the claim at the time of the claim submission. Availity then delivers the attachment to the health plan for further processing.
Solicited Claim Attachment – After the health plan receives a claim and begins the adjudication process, it may determine that additional information is needed to complete the adjudication. The health plan can, therefore, create the 277RFAI (Request For Additional Information) transaction. These requests are delivered to the provider's inbox. The clearinghouse can respond to these requests through the API. Availity matches the solicited responses to the provider's inbox work queue requests and sends the attachments to the health plan. Upon receiving these solicited responses, Availity moves the solicited request to the provider's Sent work queue and waits for the health plan to respond.

Endpoints

#	Path	Function
1	POST /medical-attachments/ma/external/rest/response	Use this endpoint to submit an attachment to a claim.
2	GET /medical-attachments/ma/external/rest/status/{requestId}	Use the request ID from your POST/response request to check the status of your attachment.

Parameters

1. POST /response:


POST/response request body
Object	Type	Definition
submitter	Object (Required)	Object providing identifying and contact information the organization or person who submitted the attachment. Refer to the Submitter table for fields and definitions.
subscriber	Object (Required)	Object providing identifying and contact information about the health plan subscriber. Refer to the Subscriber table for fields and definitions.
patient	Object (Required)	Object providing identifying and contact information about the patient. Refer to the Patient table for fields and definitions.
provider	Object (Required)	Object providing identifying and contact information about the provider. Refer to the Provider table for fields and definitions.
payer	Object (Required)	Object providing identifying and contact information about the payer. Refer to the Payer table for fields and definitions.
encounter	(Required)	Object providing information about the provision of services to the patient. Refer to the Encounter table for fields and definitions.
payloads	Array	Array containing objects with information about the attachment(s). Refer to the Payloads table for fields and definitions.
product	Object (Required)	Object containing information about the healthcare product. Refer to the Product table for fields and definitions.

2. GET /status/{requestId}

GET /status/{requestId} parameters

Object	Type	Definition
requestId	Integer	The request ID received after your initial POST/response request that you can use to check the status of your attachment.

Sample requests and responses

1. POST/response

Request:

curl --location --request POST 'https://qua.api.availity.com/availity/medical-attachments/ma/external/rest/response' \	
--header 'accept: application/json' \	
--header 'content-type: application/json' \	
--header 'authorization: Bearer <access token>' \	
--data-raw '{	
    "payer": {	
        "id": "68069"	
    },	
    "submitter": {	
        "id": "477823",	
        "state": "TX"	
    },	
    "product": {	
        "type": "CLAIM",	
        "category": "MEDICAL"	
    },	
    "patient": {	
        "lastName": "Ochoa",	
        "firstName": "Blanca",	
        "dateOfBirth": "2004-11-03",	
        "memberNumber": "524845471",	
        "accountNumber": "NXGMDX-1236885"	
    },	
    "subscriber": {	
        "lastName": "Ochoa",	
        "firstName": "Blanca",	
        "dateOfBirth": "2004-11-03",	
        "memberNumber": "524845471",	
        "accountNumber": "NXGMDX-1236885"	
    },	
    "provider": {	
	
        "lastName": "Nxgen MDX"	
    },	
    "encounter": {	
        "serviceTo": "2021-06-24",	
        "serviceFrom": "2021-06-24",	
        "requestNumber": "RN85363437337111"	
    },	
    "payloads": [	
        {	
            "contents": [	
                {	
                    "reasonCodes": [	
                        {	
                            "value": "76438-1",	
                            "codeType": "LOINC"	
                        }	
                    ],	
                    "filename": "test.pdf",	
                    "contentType": {	
                        "type": "application",	
                        "subtype": "pdf"	
                    },	
                    "data": "JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBvYmoKPDwvTGVuZ3RoIDMgMCBSL0Zg+IF0KPj4Kc3RhcnR4cmVmCjEyNzg3CiUlRU9GCg=="	
                }	
            ]	
        }	
    ]	
}	

Text Copied!

Successful response:

{
  "id":3325491
}

Text Copied!

You can use this ID to make a GET/status/{requestId} request to check the status of your attachment.

If your request is unsuccessful, you may receive a response like this:

{
    "parameterViolations": [
        {
            "constraintType": "PARAMETER",
            "path": "sendResponseExt.arg0.patient.lastName",
            "message": "Patient Last Name is required.",
            "value": ""
        }
    ]
}

Text Copied!

2. GET/status/{requestId}

Request:

curl --location --request GET 'https://qua.api.availity.com/availity/medical-attachments/ma/external/rest/status/3325473' \
--header 'accept: application/json' \
--header 'authorization: Bearer <access token>'
Text Copied!

Response:

{
    "status": "SUBMITTED"
}
Text Copied!

Field definitions

Claim Attachments field definitions: Submitter object


Field	Type	Definition
id	String (Required)	The submitter's ID number.
state	String (Required)	The submitter's state.

Claim Attachments field definitions: Subscriber object


Field	Type	Definition
firstName	String (Required)	The health plan subscriber's first name.
middleName	String	The health plan subscriber's middle name.
lastName	String (Required)	The health plan subscriber's last name.
accountNumber	String (Required)	The health plan subscriber's account number.
memberNumber	String (Required)	The health plan subscriber's member number.
relationshipToPatientCode	String	Code for the subscriber's relationship to the patient. Values with definitions in parentheses: 18 (Self) 01 (Spouse) 19 (Child) G8 (Other relationship)
dateOfBirth	String	The subscriber's birth date.
gender	String	The subscriber's gender.
address	Array	Array detailing the subscriber's street address, city, state, and ZIP code.

Claim Attachments field definitions: Patient object


Field	Type	Definition
firstName	String (Required)	The patient's first name.
middleName	String	The patient's middle name.
lastName	String (Required)	The patient's last name.
accountNumber	String (Required)	The patient's health plan account number.
memberNumber	String (Required)	The patient's health plan member number.
dateOfBirth	String	The patient's birth date.
gender	String	The patient's gender.
address	Array	Array detailing the patient's street address, city, state, and ZIP code.

Claim Attachments field definitions: Provider object


Field	Type	Definition
lastName	String (Required)	The provider's last name.
firstName	String	The provider's first name.
middleName	String	The provider's middle name.
npi	String	The provider's National Provider Identifier.
taxId	String	The provider's tax ID number.
address	String	The first line of the provider's address.
address2	String	The second line of the provider's address.
city	String	The provider's city.
state	String	The two-state abbreviation for the provider's state.
zip	String	The provider's ZIP code.

Claim Attachments field definitions: Payer object


Field	Type	Definition
id	String (Required)	The payer's Availity-specific payer ID. Maximum character length: 35.

Claim Attachments field definitions: Encounter object


Field	Type	Definition
claimNumber	String (Required)	The number for the claim. Required when submitting a response to a solicited attachment.
serviceFrom	String (Required)	The service starting date.
requestNumber	String (Required)	For unsolicited attachments, use a unique Attachment Control Number per attachment submitted. For solicited attachments, use the payer Attachment Control Number for every attachment submitted.
serviceTo	String	The service ending date.
submitDate	String	The date the claim was submitted.
serviceChargeAmount	String	The amount charged for the service.
authNumber	String	The authorization number for the service.
providerControlNumber	String	Service line item identifier (REF*6R in the X12 275 transaction).

Claim Attachments field definitions: Payloads object


Field	Type	Definition
reasonCodes	Array	Refer to the reasonCodes table for fields and definitions.
requestNumber	String	Equivalent to the encounter.requestNumber and only necessary if each attachment has a different requestNumber.
contents	Array	Array containing objects with information about the attachment. Refer to the payloads.contents table for fields and definitions.

Claim Attachments field definitions: payloads.reasonCodes object


Field	Type	Definition
codeType	String (Required)	Only allowed value is LOINC.
value	String (Required)	Must be unique to the attachment being submitted. Cannot be custom. Refer to LOINC.org for allowed values.

Claim Attachments field definitions: payloads.contents object


Field	Type	Definition
contentType	Object (Required)	Object containing information about the attachment content type. Refer to the payloads.contents.contentType table for fields and definitions.
filename	String (Required)	The name of the attachment file. Character length: Minimum = 1, maximum = 255.
data	String	The base64-encoded attachment.

Claim Attachments field definitions: payloads.contents.contentType object


Field	Type	Definition
type	String	The type of document/attachment (example: application).
subType	String	The subtype of document/attachment (example: PDF).

Claim Attachments field definitions: Product object


Field	Type	Definition
category	String (Required)	The category of the product. The only accepted value is MEDICAL.
type	String (Required)	The type of product. The only accepted value is CLAIM.