Skip to main content
POST
/
bulk
/
status
Bulk Status
curl --request POST \
  --url https://api.example.com/bulk/status \
  --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>",
  "filters": {
    "status": [
      {}
    ],
    "retry_eligible": "<string>",
    "search": "<string>"
  },
  "page": 123,
  "limit": 123,
  "include_balances": true
}
'
{
  "ver": "<string>",
  "timestamp": "<string>",
  "txnid": "<string>",
  "status": "<string>",
  "data": {
    "reference_id": "<string>",
    "batch_id": "<string>",
    "batch_status": "<string>",
    "summary": {
      "total": 123,
      "ready": 123,
      "in_progress": 123,
      "completed": 123,
      "failed": 123
    },
    "metadata": {
      "file_name": "<string>",
      "submitted_at": "<string>",
      "last_updated_at": "<string>",
      "progress_percentage": 123,
      "global_config": {
        "fiDataRangeFrom": "<string>",
        "fiDataRangeTo": "<string>",
        "configId": "<string>"
      }
    },
    "pagination": {
      "page": 123,
      "limit": 123,
      "total": 123,
      "total_pages": 123,
      "has_next": true,
      "has_prev": true
    },
    "records": [
      {}
    ]
  }
}

​
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:
​
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 application/json.

​
Request Body

​
reference_id
string
required
The unique reference ID you provided when scheduling the batch.
​
filters
object
Optional filters to narrow down the results.
​
page
integer
default:"1"
Page number for pagination.
​
limit
integer
default:"100"
Number of records per page. Maximum: 1000.
​
include_balances
boolean
default:"false"
Whether to include account balance details in each record.

​
Request Example

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

​
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" for successful queries.
​
data
object
Contains batch status information.

​
Record Object

Each record in the records array contains:
FieldTypeDescription
idintegerUnique identifier for this record
consent_idstringThe consent ID
statusstringRecord status (see Row Status Values)
retry_eligiblestringRetry eligibility (Yes, No, YesWithModifications)
session_idstringFI request session ID (if request was made)
errorobjectError details (if failed)
account_detailsarrayPresent only if include_balances=true

​
Success Response Example

{
  "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

StatusDescription
READYBatch accepted and ready for processing
IN_PROGRESSRecords are being processed
COMPLETEDAll records processed successfully
FAILEDBatch-level failure

​
Row Status Values

StatusDescription
READYRecord validated, ready for processing
IN_PROGRESSFI request sent, awaiting response
COMPLETEDData fetched successfully
FAILEDProcessing failed

​
Retry Eligibility Values

ValueDescriptionAction
YesCan retry as-isRetry without changes
NoCannot retry (permanent failure)Review error and fix source issue
YesWithModificationsCan retry with changesApply suggested modifications before retry

​
Error Responses

​
Batch Not Found

When the reference_id does not exist: 
{
  "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