HEherondata
EndUserIntegrations

Update PDF attributes including status

Changed on

Update PDF attributes including status

put/api/integrations/pdfs/{heron_id}

Request

  • Base URL
    https://app.herondata.io
  • URL
    https://app.herondata.io/api/integrations/pdfs/{heron_id}
  • Auth
    API key in header x-api-key

Path parameters

heron_idstring required

heron_id of the pdf

Request body

filenamestring

The filename of the PDF

fraud_reasonstring nullable

If fraud reason

is_fraudboolean

True if fraud was detected in the PDF

notesstring

Notes associated with PDF, e.g., rejected reason, failed reason

reconciliation_status'reconciled' | 'unreconciled' | 'not_possible' | 'null' nullable

The reconciliation status a reviewer sets for the document.

  • reconciled — the reviewer confirmed the document reconciles.
  • unreconciled — load the transactions but keep the document out of the reconciled scope, so default summaries and policy floors skip it.
  • not_possible — there was nothing to reconcile against.

Send it with status=approved, or on its own to restamp a document whose transactions already loaded. Any other status, or no status on a document still in review, is a 400. unreconciled and not_possible also need unreconciled transaction loading enabled. Omit or null the field to leave the automatic status standing.

What you send is what a reviewer can decide, not always what gets stored: unreconciled is stored as failed, the same value an automatic check writes when it does not match. Read reconciliation_method to tell them apart — human marks a reviewer's ruling. GET /integrations/pdfs/<id>, GET /end_users/<id>/pdfs, GET /end_users/<id>/data_sources/summary, and End User SQL (EUSQL) transactions_all expose both fields. GET /end_users/<id>/data_source_account_summary and the data_source_account_summary.created webhook expose the status without the method.

Restamping a loaded document changes nothing else: its status stays put and no event fires. Scoped summaries follow on the next read, policy data on the next evaluation.

reconciled overrides the stored status but not the pdf.processed event, so for a document whose automatic check failed that event keeps reporting is_reconciled: false.

reference_idstring

An optional field for your unique identifier for the PDF

status'new' | 'parsing' | 'parsed' | 'processed' | 'human_reviewing' | 'approved' | 'rejected' | 'failed' | 'transactions_loaded' | 'transactions_unloaded'

Status of PDF

Example request

{
  "filename": "my-favourite.pdf",
  "reconciliation_status": "unreconciled",
  "reference_id": "my-favourite-pdf",
  "status": "processed"
}

Response

OK

request_idstring

Unique UUID per request

Example response

{
  "pdf": {
    "account_id": "checking_account_202348",
    "created": "2026-11-02T23:44:30.814976",
    "currency": "USD",
    "end_user": {
      "heron_id": "eus_hyaMkfjmgiZgrk4d2rMbok"
    },
    "filename": "my-favourite.pdf",
    "heron_id": "pdf_hX7v63EYDYa7gLijntntaE",
    "last_updated": "2026-11-02T23:44:30.815007",
    "notes": "Statement processed successfully. All balances verified.",
    "reference_id": "my-favourite-pdf",
    "status": "processed"
  }
}

Changes

  • bd8008e49534Revision changes
    • breaking

      the response property / became nullable for the status

    • info

      added the new optional request property

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property /// to the response with the status

    • info

      added the optional property /// to the response with the status

    • info

      the response optional property / became read-only for the status