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
}
'import requests
url = "https://api.example.com/bulk/status"
payload = {
"reference_id": "<string>",
"filters": {
"status": [{}],
"retry_eligible": "<string>",
"search": "<string>"
},
"page": 123,
"limit": 123,
"include_balances": True
}
headers = {
"client_id": "<client_id>",
"client_secret": "<client_secret>",
"appIdentifier": "<appidentifier>",
"organisationId": "<organisationid>",
"Content-Type": "<content-type>"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
client_id: '<client_id>',
client_secret: '<client_secret>',
appIdentifier: '<appidentifier>',
organisationId: '<organisationid>',
'Content-Type': '<content-type>'
},
body: JSON.stringify({
reference_id: '<string>',
filters: {status: [{}], retry_eligible: '<string>', search: '<string>'},
page: 123,
limit: 123,
include_balances: true
})
};
fetch('https://api.example.com/bulk/status', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/bulk/status",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'reference_id' => '<string>',
'filters' => [
'status' => [
[
]
],
'retry_eligible' => '<string>',
'search' => '<string>'
],
'page' => 123,
'limit' => 123,
'include_balances' => true
]),
CURLOPT_HTTPHEADER => [
"Content-Type: <content-type>",
"appIdentifier: <appidentifier>",
"client_id: <client_id>",
"client_secret: <client_secret>",
"organisationId: <organisationid>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/bulk/status"
payload := strings.NewReader("{\n \"reference_id\": \"<string>\",\n \"filters\": {\n \"status\": [\n {}\n ],\n \"retry_eligible\": \"<string>\",\n \"search\": \"<string>\"\n },\n \"page\": 123,\n \"limit\": 123,\n \"include_balances\": true\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("client_id", "<client_id>")
req.Header.Add("client_secret", "<client_secret>")
req.Header.Add("appIdentifier", "<appidentifier>")
req.Header.Add("organisationId", "<organisationid>")
req.Header.Add("Content-Type", "<content-type>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/bulk/status")
.header("client_id", "<client_id>")
.header("client_secret", "<client_secret>")
.header("appIdentifier", "<appidentifier>")
.header("organisationId", "<organisationid>")
.header("Content-Type", "<content-type>")
.body("{\n \"reference_id\": \"<string>\",\n \"filters\": {\n \"status\": [\n {}\n ],\n \"retry_eligible\": \"<string>\",\n \"search\": \"<string>\"\n },\n \"page\": 123,\n \"limit\": 123,\n \"include_balances\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/bulk/status")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["client_id"] = '<client_id>'
request["client_secret"] = '<client_secret>'
request["appIdentifier"] = '<appidentifier>'
request["organisationId"] = '<organisationid>'
request["Content-Type"] = '<content-type>'
request.body = "{\n \"reference_id\": \"<string>\",\n \"filters\": {\n \"status\": [\n {}\n ],\n \"retry_eligible\": \"<string>\",\n \"search\": \"<string>\"\n },\n \"page\": 123,\n \"limit\": 123,\n \"include_balances\": true\n}"
response = http.request(request)
puts response.read_body{
"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": [
{}
]
}
}Bulk Operations
Bulk Status
Query the processing status of a bulk batch with per-record details, filtering, and pagination.
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
}
'import requests
url = "https://api.example.com/bulk/status"
payload = {
"reference_id": "<string>",
"filters": {
"status": [{}],
"retry_eligible": "<string>",
"search": "<string>"
},
"page": 123,
"limit": 123,
"include_balances": True
}
headers = {
"client_id": "<client_id>",
"client_secret": "<client_secret>",
"appIdentifier": "<appidentifier>",
"organisationId": "<organisationid>",
"Content-Type": "<content-type>"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
client_id: '<client_id>',
client_secret: '<client_secret>',
appIdentifier: '<appidentifier>',
organisationId: '<organisationid>',
'Content-Type': '<content-type>'
},
body: JSON.stringify({
reference_id: '<string>',
filters: {status: [{}], retry_eligible: '<string>', search: '<string>'},
page: 123,
limit: 123,
include_balances: true
})
};
fetch('https://api.example.com/bulk/status', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/bulk/status",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'reference_id' => '<string>',
'filters' => [
'status' => [
[
]
],
'retry_eligible' => '<string>',
'search' => '<string>'
],
'page' => 123,
'limit' => 123,
'include_balances' => true
]),
CURLOPT_HTTPHEADER => [
"Content-Type: <content-type>",
"appIdentifier: <appidentifier>",
"client_id: <client_id>",
"client_secret: <client_secret>",
"organisationId: <organisationid>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/bulk/status"
payload := strings.NewReader("{\n \"reference_id\": \"<string>\",\n \"filters\": {\n \"status\": [\n {}\n ],\n \"retry_eligible\": \"<string>\",\n \"search\": \"<string>\"\n },\n \"page\": 123,\n \"limit\": 123,\n \"include_balances\": true\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("client_id", "<client_id>")
req.Header.Add("client_secret", "<client_secret>")
req.Header.Add("appIdentifier", "<appidentifier>")
req.Header.Add("organisationId", "<organisationid>")
req.Header.Add("Content-Type", "<content-type>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/bulk/status")
.header("client_id", "<client_id>")
.header("client_secret", "<client_secret>")
.header("appIdentifier", "<appidentifier>")
.header("organisationId", "<organisationid>")
.header("Content-Type", "<content-type>")
.body("{\n \"reference_id\": \"<string>\",\n \"filters\": {\n \"status\": [\n {}\n ],\n \"retry_eligible\": \"<string>\",\n \"search\": \"<string>\"\n },\n \"page\": 123,\n \"limit\": 123,\n \"include_balances\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/bulk/status")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["client_id"] = '<client_id>'
request["client_secret"] = '<client_secret>'
request["appIdentifier"] = '<appidentifier>'
request["organisationId"] = '<organisationid>'
request["Content-Type"] = '<content-type>'
request.body = "{\n \"reference_id\": \"<string>\",\n \"filters\": {\n \"status\": [\n {}\n ],\n \"retry_eligible\": \"<string>\",\n \"search\": \"<string>\"\n },\n \"page\": 123,\n \"limit\": 123,\n \"include_balances\": true\n}"
response = http.request(request)
puts response.read_body{
"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 viainclude_balances.
Notes
- Use the
reference_idyou provided when scheduling the batch to query status. - For large batches, use pagination to retrieve results in manageable chunks.
include_balances=trueenriches records withaccount_details.- Failed records include retry eligibility information to help you decide next steps.
Authentication
This API requires authentication using the following headers:string
required
Your unique client identifier provided by FinPro during onboarding.
string
required
Your confidential client secret key provided by FinPro.
string
required
The unique identifier for your application.
string
required
Your organization’s unique identifier assigned by FinPro.
string
required
Must be set to
application/json.Request Body
string
required
The unique reference ID you provided when scheduling the batch.
object
integer
default:"1"
Page number for pagination.
integer
default:"100"
Number of records per page. Maximum: 1000.
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
string
The API version that processed the request.
string
The timestamp when the response was generated (ISO 8601 format).
string
A unique transaction ID for this API call.
string
The status of the API call. Returns
"success" for successful queries.object
Contains batch status information.
Show data properties
Show data properties
string
The reference ID for this batch.
string
The internal batch identifier.
string
The overall batch status. See Batch Status Values below.
object
object
Processing metadata and timestamps.
Show metadata properties
Show metadata properties
string
Uploaded file name (if scheduled via file upload).
string
When the batch was submitted.
string
Last status update time.
integer
Percentage completion for the batch.
object
array
Per-record details. See Record Object below.
Record Object
Each record in therecords 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) |
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
{
"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 thereference_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'"
}
404 Not FoundWas this page helpful?
