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

# Bulk Status

> Query the processing status of a bulk batch with per-record details, filtering, and pagination.

## Overview

The Bulk Status API allows you to check the processing status of a bulk batch, including detailed information about each individual consent record. This API supports filtering by status and retry eligibility, pagination for large batches, and optional balance details via `include_balances`.

### Notes

* Use the `reference_id` you provided when scheduling the batch to query status.
* For large batches, use pagination to retrieve results in manageable chunks.
* `include_balances=true` enriches records with `account_details`.
* Failed records include retry eligibility information to help you decide next steps.

## 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 `application/json`.
</ParamField>

## Request Body

<ParamField body="reference_id" type="string" required>
  The unique reference ID you provided when scheduling the batch.
</ParamField>

<ParamField body="filters" type="object">
  Optional filters to narrow down the results.

  <Expandable title="filter properties">
    <ParamField body="status" type="array">
      Filter by row status. Array of status values (e.g., `["READY", "IN_PROGRESS"]`).
    </ParamField>

    <ParamField body="retry_eligible" type="string">
      Filter by retry eligibility. Values: `"Yes"`, `"No"`, `"YesWithModifications"`.
    </ParamField>

    <ParamField body="search" type="string">
      Partial match on `consent_id`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="page" type="integer" default="1">
  Page number for pagination.
</ParamField>

<ParamField body="limit" type="integer" default="100">
  Number of records per page. Maximum: 1000.
</ParamField>

<ParamField body="include_balances" type="boolean" default="false">
  Whether to include account balance details in each record.
</ParamField>

### Request Example

```json theme={null}
{
  "reference_id": "batch-20251110-001",
  "filters": {
    "status": ["FAILED", "IN_PROGRESS"]
  },
  "page": 1,
  "limit": 100,
  "include_balances": false
}
```

## 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"` for successful queries.
</ResponseField>

<ResponseField name="data" type="object">
  Contains batch status information.

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

    <ResponseField name="batch_id" type="string">
      The internal batch identifier.
    </ResponseField>

    <ResponseField name="batch_status" type="string">
      The overall batch status. See [Batch Status Values](#batch-status-values) below.
    </ResponseField>

    <ResponseField name="summary" type="object">
      Aggregated counts by status.

      <Expandable title="summary properties">
        <ResponseField name="total" type="integer">
          Total number of records in the batch.
        </ResponseField>

        <ResponseField name="ready" type="integer">
          Records ready to be processed.
        </ResponseField>

        <ResponseField name="in_progress" type="integer">
          Records currently being processed.
        </ResponseField>

        <ResponseField name="completed" type="integer">
          Records successfully processed.
        </ResponseField>

        <ResponseField name="failed" type="integer">
          Records that failed processing.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="metadata" type="object">
      Processing metadata and timestamps.

      <Expandable title="metadata properties">
        <ResponseField name="file_name" type="string">
          Uploaded file name (if scheduled via file upload).
        </ResponseField>

        <ResponseField name="submitted_at" type="string">
          When the batch was submitted.
        </ResponseField>

        <ResponseField name="last_updated_at" type="string">
          Last status update time.
        </ResponseField>

        <ResponseField name="progress_percentage" type="integer">
          Percentage completion for the batch.
        </ResponseField>

        <ResponseField name="global_config" type="object">
          Global defaults used for the batch.

          <Expandable title="global_config properties">
            <ResponseField name="fiDataRangeFrom" type="string">
              Global default start date (ISO 8601).
            </ResponseField>

            <ResponseField name="fiDataRangeTo" type="string">
              Global default end date (ISO 8601).
            </ResponseField>

            <ResponseField name="configId" type="string">
              Global default analytics configuration ID.
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="pagination" type="object">
      Pagination information.

      <Expandable title="pagination properties">
        <ResponseField name="page" type="integer">
          Current page number.
        </ResponseField>

        <ResponseField name="limit" type="integer">
          Records per page.
        </ResponseField>

        <ResponseField name="total" type="integer">
          Total records matching filters.
        </ResponseField>

        <ResponseField name="total_pages" type="integer">
          Total number of pages.
        </ResponseField>

        <ResponseField name="has_next" type="boolean">
          Whether more pages exist.
        </ResponseField>

        <ResponseField name="has_prev" type="boolean">
          Whether previous pages exist.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="records" type="array">
      Per-record details. See [Record Object](#record-object) below.
    </ResponseField>
  </Expandable>
</ResponseField>

### Record Object

Each record in the `records` array contains:

| Field             | Type    | Description                                                 |
| ----------------- | ------- | ----------------------------------------------------------- |
| `id`              | integer | Unique identifier for this record                           |
| `consent_id`      | string  | The consent ID                                              |
| `status`          | string  | Record status (see [Row Status Values](#row-status-values)) |
| `retry_eligible`  | string  | Retry eligibility (`Yes`, `No`, `YesWithModifications`)     |
| `session_id`      | string  | FI request session ID (if request was made)                 |
| `error`           | object  | Error details (if failed)                                   |
| `account_details` | array   | Present only if `include_balances=true`                     |

### Success Response Example

```json theme={null}
{
  "ver": "<version>",
  "status": "success",
  "message": "Bulk status retrieved successfully",
  "data": {
    "reference_id": "<string>",
    "batch_id": "<uuid>",
    "batch_status": "READY|IN_PROGRESS|COMPLETED|FAILED",
    "summary": {
      "total": 100,
      "ready": 10,
      "in_progress": 30,
      "completed": 55,
      "failed": 5
    },
    "metadata": {
      "file_name": "<string|null>",
      "submitted_at": "<ISO-8601>",
      "last_updated_at": "<ISO-8601>",
      "progress_percentage": 60,
      "global_config": {
        "fiDataRangeFrom": "<ISO-8601>",
        "fiDataRangeTo": "<ISO-8601>",
        "configId": "<string>"
      }
    },
    "pagination": {
      "page": 1,
      "limit": 100,
      "total": 100,
      "total_pages": 1,
      "has_next": false,
      "has_prev": false
    },
    "records": [
      {
        "id": 1,
        "consent_id": "<uuid-v4>",
        "status": "READY|IN_PROGRESS|COMPLETED|FAILED",
        "retry_eligible": "Yes|No|YesWithModifications|null",
        "session_id": "<string|null>",
        "error": { "code": "<string>", "message": "<string>" },
        "account_details": [ /* present only if include_balances=true */ ]
      }
    ]
  }
}
```

## Status Values

### Batch Status Values

| Status        | Description                             |
| ------------- | --------------------------------------- |
| `READY`       | Batch accepted and ready for processing |
| `IN_PROGRESS` | Records are being processed             |
| `COMPLETED`   | All records processed successfully      |
| `FAILED`      | Batch-level failure                     |

### Row Status Values

| Status        | Description                            |
| ------------- | -------------------------------------- |
| `READY`       | Record validated, ready for processing |
| `IN_PROGRESS` | FI request sent, awaiting response     |
| `COMPLETED`   | Data fetched successfully              |
| `FAILED`      | Processing failed                      |

### Retry Eligibility Values

| Value                  | Description                      | Action                                     |
| ---------------------- | -------------------------------- | ------------------------------------------ |
| `Yes`                  | Can retry as-is                  | Retry without changes                      |
| `No`                   | Cannot retry (permanent failure) | Review error and fix source issue          |
| `YesWithModifications` | Can retry with changes           | Apply suggested modifications before retry |

## Error Responses

### Batch Not Found

When the `reference_id` does not exist:

```json theme={null}
{
  "ver": "1.0",
  "timestamp": "2024-11-10T12:00:00Z",
  "txnid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "errorCode": "BatchNotFound",
  "errorMsg": "No batch found with reference_id 'batch-xyz'"
}
```

**HTTP Status Code**: `404 Not Found`