> ## Documentation Index
> Fetch the complete documentation index at: https://developer.moneyone.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Schedule Bulk FI Requests (File Upload)

> Schedule multiple FI requests by uploading a CSV or JSON file.

## 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:

<ParamField header="client_id" type="string" required>
  Your unique client identifier provided by FinPro during onboarding.
</ParamField>

<ParamField header="client_secret" type="string" required>
  Your confidential client secret key provided by FinPro.
</ParamField>

<ParamField header="appIdentifier" type="string" required>
  The unique identifier for your application.
</ParamField>

<ParamField header="organisationId" type="string" required>
  Your organization's unique identifier assigned by FinPro.
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be set to `multipart/form-data`.
</ParamField>

## Request Parameters

The request uses multipart form data with the following fields:

<ParamField body="file" type="file" required>
  The CSV or JSON file containing consent IDs and optional per-row configuration. Maximum size: 10 MB.
</ParamField>

<ParamField body="reference_id" type="string">
  Optional batch identifier (5-60 characters, alphanumeric with hyphens and underscores). If omitted, the server generates one.
</ParamField>

<ParamField body="tracking_id" type="string">
  Optional alias for `reference_id`. If both are provided, `reference_id` is used.
</ParamField>

<ParamField body="global_config" type="string">
  Optional JSON or JSON string with global defaults: `fiDataRangeFrom`, `fiDataRangeTo`, `configId`.
</ParamField>

<ParamField body="globalConfig" type="string">
  Optional alias for `global_config`.
</ParamField>

<ParamField body="fiDataRangeFrom" type="string">
  Global default start date for financial data (ISO 8601 format). Applied to rows that don't specify their own value.
</ParamField>

<ParamField body="fiDataRangeTo" type="string">
  Global default end date for financial data (ISO 8601 format). Applied to rows that don't specify their own value.
</ParamField>

<ParamField body="configId" type="string">
  Global default analytics configuration ID. Applied to rows that don't specify their own value.
</ParamField>

## File Formats

### CSV Format

The CSV file must have a header row with the following columns:

| Column            | Required | Description                           |
| ----------------- | -------- | ------------------------------------- |
| `consentId`       | Yes      | The consent identifier (UUID format)  |
| `fiDataRangeFrom` | No       | Start date override (ISO 8601 format) |
| `fiDataRangeTo`   | No       | End date override (ISO 8601 format)   |
| `configId`        | No       | Analytics config override             |

**CSV Example:**

```csv theme={null}
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:

```json theme={null}
[
  { "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

<ResponseField name="ver" type="string">
  The API version that processed the request.
</ResponseField>

<ResponseField name="timestamp" type="string">
  The timestamp when the response was generated (ISO 8601 format).
</ResponseField>

<ResponseField name="txnid" type="string">
  A unique transaction ID for this API call.
</ResponseField>

<ResponseField name="status" type="string">
  The status of the API call. Returns `"success"` when the file is accepted.
</ResponseField>

<ResponseField name="message" type="string">
  A human-readable message describing the result.
</ResponseField>

<ResponseField name="data" type="object">
  Contains batch details and tracking information.

  <Expandable title="data properties">
    <ResponseField name="reference_id" type="string">
      The reference ID you provided for this batch.
    </ResponseField>

    <ResponseField name="batch_id" type="string">
      An internal batch identifier generated by the system.
    </ResponseField>

    <ResponseField name="storage_type" type="string">
      Storage location for the uploaded file (`database` or `s3`).
    </ResponseField>

    <ResponseField name="status" type="string">
      The current batch status. Initially `"FILE_UPLOADED"`.
    </ResponseField>
  </Expandable>
</ResponseField>

### Success Response Example

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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 Code             | Description                                                |
| ---------------------- | ---------------------------------------------------------- |
| `UnsupportedFileType`  | The file format is not CSV or JSON.                        |
| `FileTooLarge`         | The file exceeds the 10 MB limit.                          |
| `DuplicateReferenceId` | A batch with this `reference_id` already exists.           |
| `InvalidFileContent`   | The file content could not be parsed (malformed CSV/JSON). |