Skip to main content

File Upload

Overview​

The File Upload API allows you to upload documents and supporting files required for verification purposes. Uploaded files can be referenced when creating recipients or merchants.

Resource Access​

  • HTTP Method: POST
  • Endpoint: /banking/iban/api/file/v2/upload
  • Authentication: Bearer token required
  • Content Type: multipart/form-data

Request Headers​

HeaderValueRequiredDescription
AuthorizationBearer {access_token}YesBearer token for authentication
Content-Typemultipart/form-dataYesForm data content type

Request Body​

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

FieldTypeRequiredDescription
filefileYesThe file to upload

Supported File Types​

  • PDF documents (.pdf)
  • Image files (.jpg, .jpeg, .png)
  • Document files (.doc, .docx)

File Size Limits​

  • Maximum file size: 10 MB
  • Recommended file size: Under 5 MB for optimal processing

Response​

Success Response (200 OK)​

{
"file_id": "8f7d6e5c-4b3a-2f1d-9e8c-7b6a5d4c3f2e",
"filename": "verification_document.pdf",
"file_size": 245760,
"content_type": "application/pdf",
"upload_date": "2026-01-13T10:00:00.000Z",
"status": "uploaded"
}

Response Fields​

FieldTypeDescription
file_idstring (UUID)Unique identifier for the uploaded file
filenamestringOriginal filename
file_sizeintegerFile size in bytes
content_typestringMIME type of the file
upload_datestring (date-time)Upload timestamp
statusstringUpload status

File Status Values​

  • uploaded: File successfully uploaded
  • processing: File is being processed
  • verified: File has been verified
  • rejected: File rejected due to quality or content issues

Error Responses​

  • 400 Bad Request: Invalid file type or missing file
  • 401 Unauthorized: Invalid or missing authentication token
  • 413 Payload Too Large: File size exceeds maximum limit
  • 415 Unsupported Media Type: File type not supported
  • 500 Internal Server Error: Server error occurred

Code Examples​

cURL​

curl -X POST \
'https://gateway.ahrvo.network/banking/iban/api/file/v2/upload' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-F 'file=@/path/to/document.pdf'

Python​

import requests

url = "https://gateway.ahrvo.network/banking/iban/api/file/v2/upload"
headers = {
"Authorization": "Bearer YOUR_ACCESS_TOKEN"
}
files = {
'file': open('/path/to/document.pdf', 'rb')
}

response = requests.post(url, headers=headers, files=files)
print(response.json())

JavaScript (Node.js)​

const axios = require('axios');
const FormData = require('form-data');
const fs = require('fs');

const url = 'https://gateway.ahrvo.network/banking/iban/api/file/v2/upload';
const headers = {
'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
};

const formData = new FormData();
formData.append('file', fs.createReadStream('/path/to/document.pdf'));

axios.post(url, formData, {
headers: {
...headers,
...formData.getHeaders()
}
})
.then(response => {
console.log(response.data);
})
.catch(error => {
console.error(error.response.data);
});

Python with Async​

import aiohttp
import asyncio

async def upload_file():
url = "https://gateway.ahrvo.network/banking/iban/api/file/v2/upload"
headers = {
"Authorization": "Bearer YOUR_ACCESS_TOKEN"
}

with open('/path/to/document.pdf', 'rb') as f:
data = aiohttp.FormData()
data.add_field('file', f, filename='document.pdf')

async with aiohttp.ClientSession() as session:
async with session.post(url, headers=headers, data=data) as response:
result = await response.json()
print(result)

asyncio.run(upload_file())

Usage Notes​

  • Store the returned file_id for use when creating recipients or merchants
  • Ensure files are clear and legible for verification purposes
  • Supported file types may vary by region and verification requirements
  • Files are automatically scanned for malware and quality
  • Uploaded files are stored securely and encrypted
  • Files may be automatically deleted after a retention period
  • Check file status before using in recipient/merchant creation

Document Types​

Common document types that may be required:

  • Identity Documents: Passport, national ID, driver's license
  • Proof of Address: Utility bills, bank statements
  • Business Documents: Business registration, tax certificates
  • Banking Documents: Bank statements, voided checks

Best Practices​

  1. Image Quality: Ensure documents are clear and all text is readable
  2. File Format: Use PDF for multi-page documents
  3. Compression: Compress large files while maintaining readability
  4. Naming: Use descriptive filenames for easier tracking
  5. Security: Never include sensitive data in filenames
  6. Verification: Verify file upload success before proceeding

Interactive API Explorer​