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​