Skip to main content
POST
/
fi
/
requests
/
schedule
/
upload
/
v3
Schedule Bulk FI Requests (File Upload)
curl --request POST \
  --url https://api.example.com/fi/requests/schedule/upload/v3 \
  --header 'Content-Type: <content-type>' \
  --header 'appIdentifier: <appidentifier>' \
  --header 'client_id: <client_id>' \
  --header 'client_secret: <client_secret>' \
  --header 'organisationId: <organisationid>' \
  --data '
{
  "reference_id": "<string>",
  "tracking_id": "<string>",
  "global_config": "<string>",
  "globalConfig": "<string>",
  "fiDataRangeFrom": "<string>",
  "fiDataRangeTo": "<string>",
  "configId": "<string>"
}
'
{
  "ver": "<string>",
  "timestamp": "<string>",
  "txnid": "<string>",
  "status": "<string>",
  "message": "<string>",
  "data": {
    "reference_id": "<string>",
    "batch_id": "<string>",
    "storage_type": "<string>",
    "status": "<string>"
  }
}

​
Overview

The File Upload API allows you to schedule bulk FI requests by uploading a file containing consent IDs and optional configuration.

​
Notes

  • Supported file formats are CSV and JSON only.
  • Maximum file size is 10 MB.
  • Files must be UTF-8 encoded (without BOM for CSV).

​
Authentication

This API requires authentication using the following headers:
​
client_id
string
required
Your unique client identifier provided by FinPro during onboarding.
​
client_secret
string
required
Your confidential client secret key provided by FinPro.
​
appIdentifier
string
required
The unique identifier for your application.
​
organisationId
string
required
Your organization’s unique identifier assigned by FinPro.
​
Content-Type
string
required
Must be set to multipart/form-data.

​
Request Parameters

The request uses multipart form data with the following fields:
​
file
file
required
The CSV or JSON file containing consent IDs and optional per-row configuration. Maximum size: 10 MB.
​
reference_id
string
Optional batch identifier (5-60 characters, alphanumeric with hyphens and underscores). If omitted, the server generates one.
​
tracking_id
string
Optional alias for reference_id. If both are provided, reference_id is used.
​
global_config
string
Optional JSON or JSON string with global defaults: fiDataRangeFrom, fiDataRangeTo, configId.
​
globalConfig
string
Optional alias for global_config.
​
fiDataRangeFrom
string
Global default start date for financial data (ISO 8601 format). Applied to rows that don’t specify their own value.
​
fiDataRangeTo
string
Global default end date for financial data (ISO 8601 format). Applied to rows that don’t specify their own value.
​
configId
string
Global default analytics configuration ID. Applied to rows that don’t specify their own value.

​
File Formats

​
CSV Format

The CSV file must have a header row with the following columns:
ColumnRequiredDescription
consentIdYesThe consent identifier (UUID format)
fiDataRangeFromNoStart date override (ISO 8601 format)
fiDataRangeToNoEnd date override (ISO 8601 format)
configIdNoAnalytics config override
CSV Example: 
consentId,fiDataRangeFrom,fiDataRangeTo,configId
54450ac0-8bcb-4b9c-ad74-29b4fabe18f7,2024-01-01T00:00:00Z,2024-06-30T23:59:59Z,config-1
7b2d9e3a-1f4c-4a8b-9c6d-2e5f8a9b0c1d,,,config-2
9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d,2024-07-01T00:00:00Z,2024-12-31T23:59:59Z,
CSV Rules:
  • Header row is required
  • UTF-8 encoding (no BOM)
  • Comma delimiter
  • Empty cells use the global defaults provided in form data
  • Wrap values in quotes if they contain commas

​
JSON Format

The JSON file can be either an array or an object with a consents_list array: 
[
  { "consent_id": "54450ac0-8bcb-4b9c-ad74-29b4fabe18f7", "fiDataRangeFrom": "2024-01-01T00:00:00Z", "fiDataRangeTo": "2024-06-30T23:59:59Z", "configId": "config-1" },
  { "consentId": "7b2d9e3a-1f4c-4a8b-9c6d-2e5f8a9b0c1d", "configId": "config-2" }
]
Both consent_id and consentId are accepted in JSON rows.

​
Response Parameters

​
ver
string
The API version that processed the request.
​
timestamp
string
The timestamp when the response was generated (ISO 8601 format).
​
txnid
string
A unique transaction ID for this API call.
​
status
string
The status of the API call. Returns "success" when the file is accepted.
​
message
string
A human-readable message describing the result.
​
data
object
Contains batch details and tracking information.

​
Success Response Example

{
  "ver": "1.0",
  "timestamp": "2024-11-10T12:00:00Z",
  "txnid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "success",
  "message": "File uploaded successfully",
  "data": {
    "reference_id": "batch-20251110-002",
    "batch_id": "7c3e8a92-4b5d-6f7e-8a9b-0c1d2e3f4a5b",
    "storage_type": "database",
    "status": "FILE_UPLOADED"
  }
}

​
Error Responses

​
Unsupported File Type

When the uploaded file is not CSV or JSON: 
{
  "ver": "1.0",
  "timestamp": "2024-11-10T12:00:00Z",
  "txnid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "errorCode": "UnsupportedFileType",
  "errorMsg": "Only JSON or CSV files are accepted",
  "errorDetails": {
    "providedType": "application/pdf",
    "acceptedTypes": ["application/json", "text/csv"]
  }
}
HTTP Status Code: 400 Bad Request

​
File Too Large

When the file exceeds the maximum size: 
{
  "ver": "1.0",
  "timestamp": "2024-11-10T12:00:00Z",
  "txnid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "errorCode": "FileTooLarge",
  "errorMsg": "File size exceeds maximum allowed",
  "errorDetails": {
    "providedSize": 52428800,
    "maxSize": 10485760,
    "maxSizeMB": 10
  }
}
HTTP Status Code: 413 Payload Too Large

​
Duplicate Reference ID

When the reference_id already exists: 
{
  "ver": "1.0",
  "timestamp": "2024-11-10T12:00:00Z",
  "txnid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "errorCode": "DuplicateReferenceId",
  "errorMsg": "reference_id 'batch-20251110-002' already exists"
}
HTTP Status Code: 409 Conflict

​
Common Error Codes

Error CodeDescription
UnsupportedFileTypeThe file format is not CSV or JSON.
FileTooLargeThe file exceeds the 10 MB limit.
DuplicateReferenceIdA batch with this reference_id already exists.
InvalidFileContentThe file content could not be parsed (malformed CSV/JSON).