Skip to main content

Fetch a File

Suggest Edits


Overview​

Retrieve the metadata details of a specific File resource by its unique identifier. This endpoint returns information about the file including its status, type, size, and linked resources, but not the actual file content.


Resource Access​

Production (api.ahrvo.network)

GET https://api.ahrvo.network/payments/na/files/\{file_id}

Staging (gateway.ahrvo.network)

GET http://gateway.ahrvo.network/payments/na/files/\{file_id}

Arguments​

AttributeMandatory / OptionalDescription
file_idMandatoryThe unique ID of the file to retrieve

Example Request​

curl -X GET https://gateway.ahrvo.network/payments/na/files/FIxxxxxxxxxxxxxxxxxx \
-H "Content-Type: application/json" \
-H "Authorization: Basic <base64_encoded_credentials>"

Example Response​

File Awaiting Upload:

{
"id": "FIxxxxxxxxxxxxxxxxxx",
"status": "REQUIRES_UPLOAD",
"created_at": "2025-12-10T17:00:00Z",
"updated_at": "2025-12-10T17:00:00Z",
"linked_type": "MERCHANT",
"linked_to": "MRxxxxxxxxxxxxxxxxxx",
"extension": null,
"display_name": "Bank Statement (December 2025)",
"type": "BANK_STATEMENT",
"size_in_bytes": null,
"file_name": null,
"tags": {
"month": "2025-12",
"purpose": "merchant_onboarding"
},
"_links": {
"self": {
"href": "https://api.ahrvo.network/payments/na/files/FIxxxxxxxxxxxxxxxxxx"
},
"upload": {
"href": "https://api.ahrvo.network/payments/na/files/FIxxxxxxxxxxxxxxxxxx/upload"
},
"merchant": {
"href": "https://api.ahrvo.network/payments/na/merchants/MRxxxxxxxxxxxxxxxxxx"
}
}
}

Successfully Uploaded File:

{
"id": "FIxxxxxxxxxxxxxxxxxx",
"status": "UPLOADED",
"created_at": "2025-12-10T17:00:00Z",
"updated_at": "2025-12-10T17:05:00Z",
"linked_type": "MERCHANT",
"linked_to": "MRxxxxxxxxxxxxxxxxxx",
"extension": "pdf",
"display_name": "Bank Statement (December 2025)",
"type": "BANK_STATEMENT",
"size_in_bytes": 245678,
"file_name": "bank_statement_dec_2025.pdf",
"tags": {
"month": "2025-12",
"purpose": "merchant_onboarding",
"reviewed": "true"
},
"_links": {
"self": {
"href": "https://api.ahrvo.network/payments/na/files/FIxxxxxxxxxxxxxxxxxx"
},
"merchant": {
"href": "https://api.ahrvo.network/payments/na/merchants/MRxxxxxxxxxxxxxxxxxx"
}
}
}

Understanding File Metadata​

Key Fields​

  • status: Current state of the file (REQUIRES_UPLOAD, PENDING, UPLOADED)
  • linked_type: Type of resource the file is attached to (MERCHANT, APPLICATION)
  • linked_to: ID of the linked resource
  • type: Category of file (BANK_STATEMENT, PCI_DOCUMENT, TAX_DOCUMENT)
  • extension: File extension (only available after upload)
  • size_in_bytes: File size (only available after upload)
  • file_name: Original filename (only available after upload)

Status Progression​

  1. REQUIRES_UPLOAD: Initial state after creation
  2. PENDING: File uploaded and being processed
  3. UPLOADED: File ready and available

API Documentation​