Initiate Upload

Uploading PDFs via the API is a three-call sequence: init the workflow, submit the PDF files, then confirm with a CONTINUE action. All three use the same auth headers.

Step 1 — Init

POST /orchestration/init

Start a new workflow. Returns a transactionId that ties together every subsequent call.

Request body

{
  "reference_id": "<your-loan-or-case-id>",
  "instance_id": "<gateway_instance_id>"
}

string

required

Your own identifier for this case (e.g. loan ID, application ID). Used for idempotency — calling init again with the same reference_id returns the existing workflow.

string

required

Gateway instance ID configured for the PDF API upload flow. Provided by your integration contact.

Sample request

curl --request POST \
  --url 'https://<base_url>/orchestration/init' \
  --header 'Content-Type: application/json' \
  --header 'client_id: <your_client_id>' \
  --header 'client_secret: <your_client_secret>' \
  --header 'organisationId: <your_organisation_id>' \
  --header 'appIdentifier: <your_app_identifier>' \
  --data '{
    "reference_id": "<your-loan-id>",
    "instance_id": "<gateway_instance_id>"
  }'

Response

{
  "status": "success",
  "data": {
    "status": "SUCCESS",
    "transaction_id": "<transactionId>",
    "session_token": "<session_token>"
  }
}

Store the transaction_id — it is the single identifier used for status polling and data retrieval. The session_token is not required for subsequent API calls in this flow.

Step 2 — Submit PDF Files

POST /orchestration/submit

Submit all bank statement PDFs in a single call. Each file is a separate entry in input_data. The system runs OCR preview per file automatically and groups files by detected account number — no bank name or account number needs to be specified.

You can submit PDFs from multiple banks and accounts in one call. Files covering the same account across different months are merged automatically.

Request body

{
  "transactionId": "<transactionId>",
  "input_data": [
    {
      "name": "bank_statement_file",
      "value": "data:application/pdf;base64,<base64_string>",
      "type": "file",
      "meta": {
        "file_name": "statement1.pdf",
        "file_type": "application/pdf",
        "password": ""
      }
    },
    {
      "name": "bank_statement_file",
      "value": "data:application/pdf;base64,<base64_string>",
      "type": "file",
      "meta": {
        "file_name": "statement2.pdf",
        "file_type": "application/pdf",
        "password": "HARS0407"
      }
    }
  ]
}

string

required

The transaction_id received from Step 1.

array

required

Array of PDF file objects. Each entry represents one file.

string

required

Must be bank_statement_file.

string

required

Full base64 data URI of the PDF: data:application/pdf;base64,<base64>.

string

required

Must be file.

string

Original file name (e.g. statement.pdf).

string

MIME type of the file. Use application/pdf for PDF statements.

string

PDF password if the file is password-protected. Pass an empty string if not.

Do not include action in this call. Omit it or pass null.

Sample request

curl --request POST \
  --url 'https://<base_url>/orchestration/submit' \
  --header 'Content-Type: application/json' \
  --header 'client_id: <your_client_id>' \
  --header 'client_secret: <your_client_secret>' \
  --header 'organisationId: <your_organisation_id>' \
  --header 'appIdentifier: <your_app_identifier>' \
  --data '{
    "transactionId": "<transactionId>",
    "input_data": [
      {
        "name": "bank_statement_file",
        "value": "data:application/pdf;base64,<base64_string>",
        "type": "file",
        "meta": { "file_name": "statement1.pdf", "file_type": "application/pdf", "password": "" }
      }
    ]
  }'

Step 3 — Confirm Submission

POST /orchestration/submit

Once all files are uploaded, send a CONTINUE action with an empty input_data array to start OCR processing and analytics computation.

Request body

{
  "transactionId": "<transactionId>",
  "input_data": [],
  "action": "CONTINUE"
}

Sample request

curl --request POST \
  --url 'https://<base_url>/orchestration/submit' \
  --header 'Content-Type: application/json' \
  --header 'client_id: <your_client_id>' \
  --header 'client_secret: <your_client_secret>' \
  --header 'organisationId: <your_organisation_id>' \
  --header 'appIdentifier: <your_app_identifier>' \
  --data '{
    "transactionId": "<transactionId>",
    "input_data": [],
    "action": "CONTINUE"
  }'

After this call, the workflow begins processing. Continue to Track Status.

Error Codes

HTTP Status	Condition
`400 Bad Request`	`transactionId` is missing, or `input_data` items are malformed.
`401 Unauthorized`	Credentials are missing or invalid.
`404 Not Found`	`transactionId` does not exist — call `/orchestration/init` first.
`500 Internal Server Error`	An unexpected server-side error occurred.

AA Enabled

AA + PDF Enabled

PDF Enabled

PDF API Upload

Checks Enabled

KYC

Step 1 — Init

Request body

Sample request

Response

Step 2 — Submit PDF Files

Request body

Sample request

Step 3 — Confirm Submission

Request body

Sample request

Error Codes

​Step 1 — Init

​Request body

​Sample request

​Response

​Step 2 — Submit PDF Files

​Request body

​Sample request

​Step 3 — Confirm Submission

​Request body

​Sample request

​Error Codes

Step 1 — Init

Request body

Sample request

Response

Step 2 — Submit PDF Files

Request body

Sample request

Step 3 — Confirm Submission

Request body

Sample request

Error Codes