File Management

HarpFi provides a file management system that allows you to upload and store files for various purposes, such as payment documentation and business entity verification. Files uploaded through the API are securely stored and can be referenced in other API operations as needed.

File Configuration

The following table outlines the allowed file configurations for different purposes:

Purpose	Description	Supported MIME Types	Max File Size
payment_evidence	Supporting documentation for payments, such as invoices, receipts	png, jpeg, pdf, docx	5MB
business_entity_documents	Files related to business entity verification, such as registration documents, certificates, or identification	png, jpeg, pdf, docx	5MB

Upload File

The Upload File endpoint allows you to upload files to HarpFi for use in various operations. When uploading a file, you must specify the purpose for which the file will be used.

Request

POSThttps://files.harpfi.com/v1/files/upload

The request should be sent as multipart/form-data with the following fields:

Field	Type	Required	Description
`file`	file	Yes	The file to upload
`purpose`	string	Yes	The purpose for which the file is being uploaded. Must be one of: `payment_evidence` or `business_entity_documents`

Example Request

Bash

curl -X POST \
  'https://files.harpfi.com/v1/files/upload' \
  -H 'Authorization: ApiKey YOUR_API_KEY_HERE' \
  -F 'file=@/path/to/your/file.pdf' \
  -F 'purpose=payment_evidence'

Response

JSON

{
    "success": true,
    "message": "File uploaded successfully",
    "data": {
        "id": "FILE_abc123xyz.pdf",
        "purpose": "payment_evidence",
        "mimeType": "application/pdf",
        "uploadedAt": "2024-11-21T10:15:00Z"
    }
}

Response Fields

The response returns a file object containing:

Field	Type	Description
`id`	string	The unique identifier for the uploaded file
`purpose`	string	The purpose for which the file was uploaded (`payment_evidence` or `business_entity_documents`)
`mimeType`	string	The MIME type of the uploaded file
`uploadedAt`	string	The timestamp when the file was uploaded (ISO 8601 format)

Get File Details

The Get File Details endpoint allows you to retrieve metadata for an uploaded file by its file ID. Use the file ID returned when the file was uploaded.

Request

GEThttps://files.harpfi.com/v1/files/:fileId/details

Path Parameters

Parameter	Type	Description
`fileId`	string	The unique identifier of the file

Response

JSON

{
    "success": true,
    "message": "File details retrieved successfully",
    "data": {
        "id": "1771616981673hx0Tq8HWQd9ekKzg2hCF.pdf",
        "purpose": "payment_evidence",
        "name": "UTILITY Bill.pdf",
        "mimeType": "application/pdf",
        "contentLink": {
            "url": "https://files.harpfi.com/v1/files/1771616981673hx0Tq8HWQd9ekKzg2hCF.pdf/content",
            "expiryDate": null
        },
        "expiryDate": null,
        "uploadedAt": "2026-02-20T19:49:41.000Z"
    }
}

Response Fields

Field	Type	Description
`id`	string	The unique identifier for the file
`purpose`	string	The purpose for which the file was uploaded (`payment_evidence` or `business_entity_documents`)
`name`	string	The original file name
`mimeType`	string	The MIME type of the file
`contentLink`	object	Link to download the file content
`contentLink.url`	string	URL to retrieve the file content
`contentLink.expiryDate`	string \| null	When the content link expires (null if it does not expire)
`expiryDate`	string \| null	When the file record expires (null if it does not expire)
`uploadedAt`	string	The timestamp when the file was uploaded (ISO 8601 format)

Note: Use the same authentication (API key) as for other file endpoints. If the file does not exist or you do not have access, the API returns an error response.