📊 Financial Report API Guide

This guide explains how to generate a financial report using the Open Finance API. It includes steps for authentication and how to initiate and retrieve the report generation process.

🔐 Step 1: Create a Token

To use the API, you need to obtain an access token using the OAuth 2.0 Client Credentials flow.

Request

URL: https://api.open-finance.ai/oauth/token

Method: POST

Create Token

Request Body

Key	Type	Description	Example	Required
`userId`	string	Unique user identifier	`[email protected]`	true
`clientId`	string	Provided in dashboard	`1234`	true
`clientSecret`	string	Provided in dashboard	`1234`	true

Headers

Key	Value
`Content-Type`	`application/json`

Example Request

{
  "userId": "[email protected]",
  "clientId": "{{CLIENT_ID}}",
  "clientSecret": "{{CLIENT_SECRET}}"
}

Example Response (Status 200)

{
  "tokenType": "Bearer",
  "expiresIn": 86400,
  "accessToken": "iJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InQ4"
}

Error Responses

401 Unauthorized

{
  "type": "CLIENT_ERROR",
  "message": "{\"error\":\"access_denied\",\"error_description\":\"Unauthorized\"}"
}

400 Bad Request

{
  "type": "CLIENT_ERROR",
  "message": "[\"\\\"clientSecret\\\" is required\"]"
}

500 Internal Server Error

🧾 Step 2: Create a Financial Report

Endpoint

POST /financial-report/{customerId}

Use this endpoint to start generating a financial report for a specific customer.

Path Parameters

Name	Type	Description
`customerId`	`string`	A unique identifier for the customer

Security

Requires read:connections scope
Use the access_token from Step 1 as a Bearer token

Request

POST https://api.open-finance.ai/financial-report/{customerId}

Headers

Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

Response

200 OK

{
  "jobId": "01HZZYPQTN3CW7RR3PKR55A6JK"
}

Use this jobId to check the status of the report.

400 Bad Request

{
  "message": "Missing customerId",
  "code": "INVALID_REQUEST"
}

500 Internal Server Error

{
  "message": "Something went wrong",
  "code": "INTERNAL_ERROR"
}

📅 Step 3: Get the Financial Report Status & Result

Endpoint

GET /financial-report/{jobId}

Use this endpoint to check the status of a financial report and retrieve it when it's ready.

Path Parameters

Name	Type	Description
`jobId`	`string`	A unique identifier for the job returned in Step 2

Query Parameters

Name	Type	Description
`withPdf`	`string`	Optional. Set to `1` to include a downloadable PDF URL in the response

Security

Requires read:connections scope
Use the access_token from Step 1 as a Bearer token

Request

GET https://api.open-finance.ai/financial-report/{jobId}?withPdf=1

Headers

Authorization: Bearer YOUR_ACCESS_TOKEN

Response

200 OK (when report is ready)

{
  "financialReport": {
    "customerId": "318422557",
    "ownerName": "John Doe",
    "parsedAccountNumber": "123456789",
    "providerId": "leumi",
    "currentDate": "2025-04-23",
    "checkingAccountsILS": [...],
    "checkingAccounts": [...],
    "yearMonthBalance": [...],
    "totalIncomesOutcome": {
      "date": "2025-04-01",
      "sumIncomePerMonth": 15000,
      "sumExpansesPerMonth": 12000,
      "sumNetIncomePerMonth": 3000,
      "regularIncomeSources": [
        { "classificationSource": "SALARY", "amount": 14000 }
      ]
    },
    "balancesPerDays": [...],
    "monthlyAverageProviderFees": [...],
    "creditCardOutcomes": [...],
    "creditCardOutcomesByCat": [...],
    "creditCardFees": [...],
    "savingsAndSecurities": {
      "totalSavings": 20000,
      "totalSecuritiesValue": 15000,
      "totalForeignCurrencyAmount": [
        { "currency": "USD", "amount": 3000 }
      ]
    },
    "savings": [...],
    "securities": [...],
    "countAkam": 2,
    "countAlertNotice": 0,
    "countCancelled": 0,
    "countForeclosure": 0,
    "countLoanOverDue": 1,
    "loansTotal": {
      "totalMortgageAmount": 450000,
      "totalLoansAmount": 150000
    },
    "loans": [...],
    "totalLoans": [...]
  },
  "status": "DONE",
  "url": "https://open-finance-assets.s3.amazonaws.com/.../report.pdf"
}

200 OK (when report is still processing)

{
  "status": "RUNNING"
}

400 Bad Request

{
  "message": "Invalid jobId",
  "code": "INVALID_REQUEST"
}

500 Internal Server Error

{
  "message": "Something went wrong",
  "code": "INTERNAL_ERROR"
}

✅ Next Steps

You can now monitor the report generation progress using the job ID. Once the report is ready, you'll receive a full report object and optionally a PDF download link.