PDF Flow

The PDF Flow is for clients whose journey starts from a bank-statement PDF. You upload the statement with a single API call, and Signal IQ takes care of parsing, checks, ingestion, insights generation and output delivery.

Upload

You upload a bank-statement PDF with a single API call. On success you receive an uploadId immediately.

See API Reference - PDF APIs for the full request, response, and error contract.

What happens inside

Once the upload is accepted, Signal IQ moves through these stages. You are kept informed at each important step via webhook (see Notifications below).

1. Parse - the statement is parsed. If parsing fails, the flow ends and you receive PDF_PARSE_FAILED.
2. Fraud check - a separate fraud gate runs. If it blocks, nothing enters Setu Insights and you receive PDF_FRAUD_DETECTED.
3. Statement validation - a separate statement-validation gate runs. If it blocks, nothing enters Setu Insights and you receive STATEMENT_VALIDATION_FAILED.
4. PDF parse success - if both gates pass, parsing succeeded (PDF_PARSE_SUCCESS).
5. Data block creation - the parsed data is prepared for analysis inside Setu Insights (FI_DATA_BLOCK_CREATION_SUCCESS).
6. Insights generation started - the insights job is accepted (INSIGHTS_CREATION_STARTED). A reportId is issued at this stage.
7. Insights generation success / failure - the report is produced (INSIGHTS_CREATION_SUCCESSFUL), or the failure is reported (INSIGHTS_CREATION_FAILED).
8. Report availability - on success, use the reportId from the webhook to fetch your configured outputs.

Fraud and statement validation are two separate gates. Details for each are in Fraud gate and Statement-validation gate below.

Notifications you receive

Every notification is delivered as an HTTP POST to your configured webhook URL, and is wrapped in the same envelope. The correlation field in this flow is uploadId.

{
  "type": "AUTO_DI_STATUS",
  "data": {
    "status": "<STAGE_STATUS>",
    "uploadId": "fb12d1a2-1e5c-4c63-aa54-d5f1d2ec19af"
  }
}

Full catalogue

Treat INSIGHTS_CREATION_SUCCESSFUL as terminal success, and statuses 1, 2, 3 and 8 as terminal failures.

Notification error codes

Structured errorCode / errorMessage appear on terminal failure webhooks such as PDF_PARSE_FAILED. Fraud and statement-validation blocks do not use BSP codes.

On PDF_PARSE_FAILED

Examples of every schema

{
  "type": "AUTO_DI_STATUS",
  "data": {
    "status": "PDF_PARSE_FAILED",
    "uploadId": "fb12d1a2-1e5c-4c63-aa54-d5f1d2ec19af",
    "errorCode": "BSP-105",
    "errorMessage": "Unable to detect bank statement format. Please verify the bank name and resubmit."
  }
}

{
  "type": "AUTO_DI_STATUS",
  "data": {
    "status": "PDF_FRAUD_DETECTED",
    "uploadId": "fb12d1a2-1e5c-4c63-aa54-d5f1d2ec19af",
    "fraudSignals": {
      "overall": "IRREGULARITY_DETECTED",
      "checks": [],
      "vendorScore": null
    }
  }
}

{
  "type": "AUTO_DI_STATUS",
  "data": {
    "status": "STATEMENT_VALIDATION_FAILED",
    "uploadId": "fb12d1a2-1e5c-4c63-aa54-d5f1d2ec19af",
    "statementValidation": {
      "status": "FAIL",
      "issues": []
    }
  }
}

{
  "type": "AUTO_DI_STATUS",
  "data": {
    "status": "PDF_PARSE_SUCCESS",
    "uploadId": "fb12d1a2-1e5c-4c63-aa54-d5f1d2ec19af"
  }
}

{
  "type": "AUTO_DI_STATUS",
  "data": {
    "status": "FI_DATA_BLOCK_CREATION_SUCCESS",
    "uploadId": "fb12d1a2-1e5c-4c63-aa54-d5f1d2ec19af",
    "dataIds": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"]
  }
}

{
  "type": "AUTO_DI_STATUS",
  "data": {
    "status": "INSIGHTS_CREATION_STARTED",
    "uploadId": "fb12d1a2-1e5c-4c63-aa54-d5f1d2ec19af",
    "reportId": "7f3e4d5c-1111-2222-3333-444455556666"
  }
}

{
  "type": "AUTO_DI_STATUS",
  "data": {
    "status": "INSIGHTS_CREATION_SUCCESSFUL",
    "uploadId": "fb12d1a2-1e5c-4c63-aa54-d5f1d2ec19af",
    "reportId": "7f3e4d5c-1111-2222-3333-444455556666"
  }
}

{
  "type": "AUTO_DI_STATUS",
  "data": {
    "status": "INSIGHTS_CREATION_FAILED",
    "uploadId": "fb12d1a2-1e5c-4c63-aa54-d5f1d2ec19af",
    "errorCode": "BSP-501",
    "errorMessage": "Insights computation failed. Please contact support with the uploadId."
  }
}

Step-by-step notifications are configurable per client. They can be switched off entirely, or limited to specific stages. This is set up during onboarding.

Webhook delivery

When Signal IQ posts a notification to your webhook, handlers must be idempotent and key off uploadId.

Fraud gate

Blocks when fraudSignals.overall is FRAUD or IRREGULARITY_DETECTED. Notification: PDF_FRAUD_DETECTED. Nothing is ingested into Setu Insights.

The raw fraudSignals object is forwarded so you can apply your own risk policy.

• Signal IQ treats FRAUD and IRREGULARITY_DETECTED the same for this flow: both stop processing before insights.
• The webhook still includes the full fraudSignals object (overall, checks, vendorScore) so you can handle the two values differently in your own systems if needed.
• If overall is neither value above, the fraud gate does not block.
• checks is an array of individual check results when present. vendorScore may be a number or null - use it only as supporting context.

Statement-validation gate

Blocks when statementValidation is present and statementValidation.status is not PASS. Notification: STATEMENT_VALIDATION_FAILED. Nothing is ingested into Setu Insights.

The raw statementValidation object is forwarded so you can apply your own risk policy.

A missing statementValidation field is not treated as a failure. The statement-validation gate only blocks when the object is present and its status is not PASS.

Getting your outputs

On INSIGHTS_CREATION_SUCCESSFUL, use the reportId from the webhook to fetch your configured outputs. See the API reference for how to fetch results.

See how Signal IQ works when you already have your own financial data.