Quick Start for Agents

This guide walks through integrating the finoOS API from scratch in five steps: authenticate, create a user, connect banking data, track analysis, and retrieve results.

Base URL: https://os.test.fino.cloud/api

All paths below are relative to this base URL.

---

Machine-Readable Documentation

For AI agents and coding assistants, the full documentation is available in plain-text formats optimized for LLM consumption:

Resource	URL	Description
llms.txt	https://docs.fino.cloud/llms.txt	Documentation index with agent instructions and API endpoint listing
llms-full.txt	https://docs.fino.cloud/llms-full.txt	Complete documentation as a single Markdown file (~29k tokens)
API Reference	https://docs.fino.cloud/api	Interactive OpenAPI documentation

Load llms.txt first for an overview, then fetch llms-full.txt if you need the full context.

---

Step 1 -- Authenticate

Exchange your client credentials for an access token.

POST /api/auth (content type: application/x-www-form-urlencoded)

curl -X POST https://os.test.fino.cloud/api/auth \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "grant_type=client_credentials"

Response (200):

{
  "access_token": "eyJhbGciOi...",
  "expires_in": 300,
  "token_type": "Bearer",
  "scope": "banking categorization ...",
  "session_state": "1e2212ad-..."
}

Use the access_token value in all subsequent requests as a Bearer token:

Authorization: Bearer <access_token>

The token expires after expires_in seconds (typically 300). Re-authenticate before it expires.

---

Step 2 -- Create a User

Create a user to represent the person or company whose financial data you will analyze.

POST /api/users

{
  "type": "person",
  "automaticAnalysis": "active"
}

• type -- person or company. Determines available analytics scopes.
• automaticAnalysis -- Set to active (default) for Banking Connect flows so analysis runs automatically. Set to suspended for manual upload flows.
• Optionally set expiresIn (e.g. "P7D" for 7 days) to auto-delete the user later.

The response includes a userId -- store it for all user-scoped requests.

---

Step 3 -- Connect Banking Data

Choose one of two paths depending on whether you have existing banking data.

Path A: Banking Connect (recommended)

Redirect end users to the fino Banking Connect UI to log in to their bank.

POST /api/users/{user-id}/banking/connect

The response contains:

• A redirect URL for the end user to complete the bank connection.
• A Finoos-Correlation-Id response header -- save this to track the analysis.

Once the user completes the connection, analysis is triggered automatically (if automaticAnalysis is active).

Path B: Manual Upload

Upload account and transaction data you already possess.

1. Upload accounts and transactions: POST /api/users/{user-id}/banking/accounts with a JSON body containing an accounts array (each with transactions).

2. Trigger analysis manually: POST /api/users/{user-id}/trigger-analysis

   The response includes a Finoos-Correlation-Id header.

---

Step 4 -- Track Analysis

Use the Finoos-Correlation-Id from Step 3 to monitor progress. Two options:

Option A: Webhooks (recommended)

Subscribe to webhook notifications to receive the correlation ID and status when analysis completes. See the Webhooks documentation for setup.

Option B: Polling

Poll the correlation endpoint:

GET /api/users/{user-id}/categorization/correlation

Pass the correlation ID as a query parameter or header.

Status	Meaning
200	Analysis completed successfully
404	Analysis still in progress (or connection was canceled)

Polling best practices:

• Start polling only after a successful connection or upload.
• Use exponential backoff. Do not poll more than twice per second initially.
• Increase the interval over time.

---

Step 5 -- Retrieve Results

Once analysis is complete, fetch results from the analytics endpoints relevant to your enabled scopes:

Endpoint	Description
GET /api/users/{user-id}/categorization	Categorized transactions
GET /api/users/{user-id}/analysis/person/income	Person income analysis
GET /api/users/{user-id}/analysis/company/cashflow	Company cashflow analysis
GET /api/users/{user-id}/analysis/company/credits	Company credits analysis

All analytics endpoints follow the same pattern: GET /api/users/{user-id}/analysis/{scope}.

Refer to the API Reference for the full list of available analytics endpoints matching your enabled scopes.

---

Summary

Step	Method	Endpoint
Authenticate	POST	/api/auth
Create User	POST	/api/users
Banking Connect	POST	/api/users/{user-id}/banking/connect
Upload Accounts	POST	/api/users/{user-id}/banking/accounts
Trigger Analysis	POST	/api/users/{user-id}/trigger-analysis
Track Progress	GET	/api/users/{user-id}/categorization/correlation
Get Results	GET	/api/users/{user-id}/categorization