# Fondo Partner API

# Overview

This API is intended for registered partners in agreement with Fondo.

The API is subject to change.


Version: 2.0.0
License: Proprietary

## Servers

Sandbox
```
https://api.sandbox.fondo.se
```

NPC
```
https://api.npc.fondo.se
```

Production
```
https://api.fondo.se
```

## Security

### oAuth

Exchange OAuth 2.0 Client Credentials: `client_id` and `client_secret' for a short-lived bearer token.
The token grants access to all clients (power of attorney assignees) under your partner.


Type: oauth2

## Download OpenAPI description

[Fondo Partner API](https://docs.fondo.se/_bundle/openapi/api.yaml)

## Authorization

Obtain and manage access tokens via **OAuth 2.0 Client Credentials**.
Send `grant_type=client_credentials` with your `client_id` and `client_secret`.
Use the returned `access_token` in `Authorization: Bearer <token>`.
Tokens are short-lived—reuse during validity and renew on expiry.


### Obtain access token

 - [POST /v2/partner/auth/token](https://docs.fondo.se/openapi/api/authorization/authtoken.md): Issues a short-lived bearer token using OAuth 2.0 Client Credentials. Send grant_type=client_credentials with your client_id and client_secret (optionally scope, state). Use the returned access_token in the Authorization: Bearer header on subsequent requests. The response also includes expires_in (seconds) and echoes state when provided.

The credentials identify your partner account. The resulting token grants access to all clients (power of attorney assignees) under your partner.

## Accounts

**Accounts** hold investor positions, balances, and cash movements under a client.
Endpoints let you **list accounts**, **fetch details**, and **close accounts**.
Responses include status, owner info, currency, linked bank accounts, positions, and timestamps.


### List client's accounts

 - [GET /v2/partner/client/{clientId}/account](https://docs.fondo.se/openapi/api/account/getaccounts.md): Returns every investment account linked to clientId, including identifiers, type, status, balances, positions, linked bank accounts, currency, and timestamps. Use this to display or manage the client's full account set.

### Get account performance

 - [GET /v2/partner/client/{clientId}/account/{accountId}/performance](https://docs.fondo.se/openapi/api/account/getaccountperformance.md): Returns daily Time-Weighted Return (TWR) data for the account. Each entry contains a date and the day's return as a decimal.

By default returns the full performance history. Optionally pass start and end query parameters (ISO 8601 dates) to limit the date range — both must be provided together.

### Get account market value

 - [GET /v2/partner/client/{clientId}/account/{accountId}/value](https://docs.fondo.se/openapi/api/account/getaccountvalue.md): Returns the total market value of the account, calculated as the sum of the settled cash balance, the value of settled fund positions, and pending subscription amounts.

### Get kyc status

 - [GET /v2/partner/client/{clientId}/kycstatus/account/{accountId}](https://docs.fondo.se/openapi/api/account/getkycstatusbyaccount.md): Get status of kyc

### Get account

 - [GET /v2/partner/client/{clientId}/account/{accountId}](https://docs.fondo.se/openapi/api/account/getaccountbyid.md): Returns the full record for accountId under clientId, including identifiers, status, account and service type, owner details, balances and cumulative amounts, current positions, linked bank accounts, currency, and timestamps. Use this to display or verify a single investment account and its latest state.

### Close client account

 - [DELETE /v2/partner/client/{clientId}/account/{accountId}](https://docs.fondo.se/openapi/api/account/deleteaccount.md): Marks the account accountId (under clientId) as closed so no new activity can occur. The response echoes the account record including deleted/closed state. Historical data remains available for regulatory/reporting needs.

### List transfers for account

 - [GET /v2/partner/client/{clientId}/account/{accountId}/transfer](https://docs.fondo.se/openapi/api/account/getaccounttransfers.md): Returns all 3rd-party transfer instructions associated with accountId under clientId.
Each item includes the custodian, an external reference, the transfer status, and creation/modification timestamps.

### List cash transactions

 - [GET /v2/partner/client/{clientId}/account/{accountId}/transaction/cash](https://docs.fondo.se/openapi/api/account/getaccountcashtransactions.md): Returns the cash ledger for accountId (under clientId), including transaction type (e.g., deposit/withdrawal/settlement/fee), references, accounts debited/credited, amount/currency, dates (createdDate, modifiedDate, settlementDate), and optional client/executor references. Use for cash reconciliation and statements.

### List fund transactions

 - [GET /v2/partner/client/{clientId}/account/{accountId}/transaction/fund](https://docs.fondo.se/openapi/api/account/getaccountfundtransactions.md): Returns fund activity for accountId (under clientId) such as subscriptions/redemptions with instrument identifiers, units, price, currency, references, and key dates (tradeDate, settlementDate). Use to build position histories and confirm settled/unspecified units.

### Create withdrawal

 - [POST /v2/partner/client/{clientId}/account/{accountId}/withdrawal](https://docs.fondo.se/openapi/api/account/createwithdrawal.md): Initiates a payout from accountId (under clientId). Provide withdrawal details (e.g., withdrawalType, target bankAccount) in the request body. The response returns the created transaction with identifiers, amounts, and settlement metadata for tracking.

### Get Swish deposit status

 - [GET /v2/partner/deposit/swish/{swishId}](https://docs.fondo.se/openapi/api/account/pollswishdeposit.md): Returns the current status of a previously initiated Swish deposit session. Use to confirm whether the deposit is pending or successfully paid; errorCode provides additional context if applicable.

### Create Swish deposit

 - [POST /v2/partner/client/{clientId}/account/{accountId}/deposit/swish](https://docs.fondo.se/openapi/api/account/createswishdeposit.md): Starts a new Swish payment session for accountId (under clientId). Send details like type (e.g., same_device), amount, and optional qrFormat. The response includes a session id, token, optional qrImage, and a paymentId to track the flow through status checks.

### Get withdrawal limit

 - [GET /v2/partner/client/{client_id}/account/{account_id}/withdrawal/limit](https://docs.fondo.se/openapi/api/account/getwithdrawallimit.md): Returns the minimum and maximum withdrawable amounts for the given account. For insurance accounts, the limits are determined by the insurance provider. For other account types, the minimum is 0 and the maximum equals the current cash balance.

## Agreements

Retrieve account agreements and generate PDF documents for account-related contracts.


### Get agreement types

 - [GET /v2/partner/client/{clientId}/account/{accountId}/agreement-types](https://docs.fondo.se/openapi/api/agreement/getaccountagreementtypes.md): Get available agreement types for an account.

### Get agreement PDF

 - [GET /v2/partner/client/{clientId}/account/{accountId}/agreement/{agreementTypeKey}](https://docs.fondo.se/openapi/api/agreement/getaccountagreementpdf.md): Get agreement document in PDF format.

## Clients

A **client** is the legal entity that holds power of attorney over end-investor accounts.
Use these endpoints to **list, create, read, and update** clients, manage bank
accounts and service types, and fetch client-specific resources (instruments, custodians).


### List clients

 - [GET /v2/partner/client](https://docs.fondo.se/openapi/api/client/getclients.md): Returns all clients associated with the authenticated partner, including IDs, display names, bank account info for fees/settlements, service types, registration/country details, and timestamps. Use to show or manage your client portfolio.

### Create client

 - [POST /v2/partner/client](https://docs.fondo.se/openapi/api/client/createclient.md): Creates a client record (company or individual) with identifiers (name, displayName, optional id), regulatory and operational details (crn, country), optional bank accounts for fee handling, and service types. The response returns the full persisted client including sortedId and timestamps.

### Get client

 - [GET /v2/partner/client/{clientId}](https://docs.fondo.se/openapi/api/client/getclientbyid.md): Returns the full client object for clientId, including names, service types (with any assigned codes), bank accounts, and timestamps. Use to display or verify a single client's profile.

### Update client

 - [PATCH /v2/partner/client/{clientId}](https://docs.fondo.se/openapi/api/client/updateclient.md): Partially updates the client identified by clientId. Provide only the fields to change (e.g., displayName, bank accounts, service types, country). The response returns the updated client with refreshed timestamps.

### List client's instrument universe

 - [GET /v2/partner/client/{clientId}/instrument](https://docs.fondo.se/openapi/api/client/getclientinstrumentuniverse.md): Returns instruments available for the given clientId, including identifiers (id, isincode), name, currency, latest price (closePrice, priceDate), KIID links, trade flags (isBuyable, isSellable, isTradable), cost breakdowns, rebates, and rules (unit decimals, minimum investment). Use to power search, eligibility checks, and order tickets for that client.

## Custodians

Fetch **custodians** linked to a client—useful for transfer instructions and operational routing.
Returns identifiers and names for display and validation.


### List client custodians

 - [GET /v2/partner/client/{clientId}/custodian](https://docs.fondo.se/openapi/api/custodian/getcustodians.md): Returns all custodians (e.g., for transfers), including identifiers and display names. Use this to populate custodian selectors or to validate transfer instructions.

## Journeys (Hosted Flows)

**Journeys** are secure, hosted web flows for customer interactions: account opening (e-sign),
KYC/KYB questionnaires, fund transfers, and allocation plan setup.
Create a Journey via API, redirect customers to the time-limited URL, and poll/callback for results.


### Get journey

 - [GET /v2/partner/client/{clientId}/journey/{journeyId}](https://docs.fondo.se/openapi/api/journey/getjourney.md): Returns the current state, configuration, and outcome of a web journey identified by journeyId under clientId (e.g., createAccount). Includes journey URL, expiry, callback/redirect URLs, context/scope, and any produced results (such as created account, bank account, transfer instructions, allocation plan). Use it to monitor progress and fetch results after end-customer completion.

### Create journey

 - [POST /v2/partner/client/{clientId}/journey](https://docs.fondo.se/openapi/api/journey/postjourney.md): Initiates a new web journey (e.g., createAccount) for the specified clientId. Provide journey configuration (account types, service type, optional allocation plan, KYC questions, transfer instructions) plus callback/redirect URLs. The response returns a journey id, a launchable url, status, and metadata you can track until completion.

## Allocation Plans

**Allocation plans** allow deposits to be distributed across instruments for an account.
List, fetch, and delete allocation plans. Allocation plans are created and updated via journeys.


### List allocation plans

 - [GET /v2/partner/client/{clientId}/allocationplan](https://docs.fondo.se/openapi/api/allocationplan/getallocationplans.md): Returns all allocation plans for the specified client.

### Get allocation plan

 - [GET /v2/partner/client/{clientId}/allocationplan/{allocationPlanId}](https://docs.fondo.se/openapi/api/allocationplan/getallocationplan.md): Returns a single allocation plan by ID for the specified client.

### Delete allocation plan

 - [DELETE /v2/partner/client/{clientId}/allocationplan/{allocationPlanId}](https://docs.fondo.se/openapi/api/allocationplan/deleteallocationplan.md): Deletes an allocation plan by ID for the specified client.

### Get allocation plan by account

 - [GET /v2/partner/client/{clientId}/allocationplan/account/{accountId}](https://docs.fondo.se/openapi/api/allocationplan/getallocationplanbyaccount.md): Returns the allocation plan associated with the specified account.

## Savings Plans

**Savings plans** define recurring fixed-amount investments into instruments for an account.
Savings plans are created via journeys and can be fetched by account.


### Get savings plan by account

 - [GET /v2/partner/client/{clientId}/account/{accountId}/savingsplan](https://docs.fondo.se/openapi/api/savingsplan/getsavingsplanbyaccount.md): Returns the savings plan associated with the specified account.

### Delete savings plan by account

 - [DELETE /v2/partner/client/{clientId}/account/{accountId}/savingsplan](https://docs.fondo.se/openapi/api/savingsplan/deletesavingsplanbyaccount.md): Deletes the savings plan associated with the specified account.
Returns the deleted savings plan.

## Instruments

The **instrument universe** consists of mutual funds available for a given client or globally.
Retrieve instrument metadata: identifiers (e.g., ISIN), currency, latest price, **KIID** links,
tradability flags, unit decimals, minimums, and cost/fee breakdowns.


### List instruments

 - [GET /v2/partner/instrument](https://docs.fondo.se/openapi/api/instrument/getinstruments.md): Returns all mutual fund instruments available on the platform, including identifiers, currency, latest prices and dates, KIID links, tradability flags, costs/fees, rebates, and instrument rules (unit decimals, minimums). Use for global discovery, search, or to pre-filter a client's instrument set.

### Get instrument

 - [GET /v2/partner/instrument/{instrumentId}](https://docs.fondo.se/openapi/api/instrument/getinstrumentbyid.md): Returns the full instrument record for instrumentId, including identifiers (id, isincode), name, currency, latest pricing, KIID links, tradability flags, cost breakdowns, rebates, and unit/amount constraints. Use to power instrument detail pages and to validate order tickets.

### Get instrument prices

 - [GET /v2/partner/client/{clientId}/instrument/{instrumentId}/prices](https://docs.fondo.se/openapi/api/instrument/getinstrumentprices.md): Returns historical price data for the instrument identified by instrumentId.
Filter by date range using start and end query parameters (YYYY-MM-DD).
The date range is limited to a maximum of 365 days.
Only available for specific clients in agreement with Morningstar.

## Payment Instructions

**Payment instructions** (e.g., autogiro) batch one or more payments to accounts.
Create instructions, then track the **payments** under each instruction (amounts, status, and references).


### Create payment instruction

 - [POST /v2/partner/client/{clientId}/instruction/payment](https://docs.fondo.se/openapi/api/instruction/createpaymentinstruction.md): Creates a new payment instruction of the specified type (for example autogiro) for the client identified by clientId.
Provide an array of payments with details such as amount, destination account, and a unique clientRef.
The response returns the instruction id, the list of created payments, a bankTransferRef if available, and the initial status (for example new) so you can track subsequent processing and settlements.

### Get payments by instruction

 - [GET /v2/partner/client/{clientId}/instruction/{instructionId}/payment](https://docs.fondo.se/openapi/api/instruction/getinstructionpayment.md): Returns the list of individual payments linked to an instruction identified by instructionId under the given clientId.
Each payment record includes its id, destination account, amount, optional clientRef, current status (such as new or completed), and any explanatory reason or reasonCode. Use this endpoint to monitor execution and settlement of all payments created within a given payment instruction.

### Get payment instruction

 - [GET /v2/partner/client/{clientId}/instruction/{instructionId}](https://docs.fondo.se/openapi/api/instruction/getpaymentinstruction.md): Returns the full payment instruction identified by instructionId under the given clientId. The response includes the instruction id, a list of scheduled payments (each with amount, target account, and optional clientRef), any bankTransferRef provided by the payment system, and the current status (such as new, processing, or completed). Use this endpoint to track the overall lifecycle and settlement state of a particular payment instruction.

## Orders

**Fund orders** (subscription/redemption) drive the trading lifecycle.
Create, read, list, and cancel orders; track status from `received` → `sent` → `confirmed` → `settled`.
Orders reference **accounts** and **instruments**, and map to cash/fund transactions on settlement.


### Create order withdrawal

 - [POST /v2/partner/client/{clientId}/order/withdrawal](https://docs.fondo.se/openapi/api/order/createorderwithdrawal.md): Sell fund units and withdraw the resulting amount

### Create redemption transfer order

 - [POST /v2/partner/client/{clientId}/order/redemptionTransfer](https://docs.fondo.se/openapi/api/order/createorderredemptiontransfer.md): Sell fund units and transfer the resulting cash to another Fondo
account belonging to the same client and owner. The redeemed amount
settles on the source account first and is then transferred to the
target account.

### List orders

 - [GET /v2/partner/client/{clientId}/order](https://docs.fondo.se/openapi/api/order/getorders.md): Returns every order placed under clientId, including both subscriptions and redemptions.
Each order object provides its id, orderType, current status (e.g., received, sent, confirmed, settled), associated account, references (clientRef, executorRef), the targeted instrument, requested units or amount, and full lifecycle timestamps (createdDate, modifiedDate, canceledDate).
Use this endpoint to monitor all fund orders and their progress from initiation through settlement.

### Create order

 - [POST /v2/partner/client/{clientId}/order](https://docs.fondo.se/openapi/api/order/createorder.md): Creates a new fund order (subscription or redemption) on the account specified by account under the given clientId.
Provide details such as orderType, instrument, amount or units, and optional references (clientRef, executorRef) to help track the order.
The response includes the generated order id, its initial status (typically received), and full order details for monitoring as it moves through execution and settlement.

### Get order

 - [GET /v2/partner/client/{clientId}/order/{orderId}](https://docs.fondo.se/openapi/api/order/getorderbyid.md): Returns the full details of a single order identified by orderId under the given clientId.
The response includes the order's status (for example received, sent, confirmed, settled), orderType (subscription or redemption), associated account, instrument details, requested amount or units, and lifecycle timestamps (createdDate, modifiedDate, canceledDate).
Use this endpoint to track an individual order's progress from initiation through settlement or cancellation.

### Cancel order

 - [DELETE /v2/partner/client/{clientId}/order/{orderId}](https://docs.fondo.se/openapi/api/order/cancelorder.md): Cancels the order identified by orderId for the given clientId.
Use this endpoint to stop an order that has been created but not yet fully executed or settled.
The response returns the complete order object with its status updated to canceled (if the cancellation succeeded), including all key fields such as orderType, instrument, and lifecycle timestamps.

## Transactions

**Transactions** record movements of money and units.
 - **Cash transactions (CT):** deposits, withdrawals, cash legs of fund orders (with settlement dates).
 - **Fund transactions (FT):** unit movements from subscriptions/redemptions (trade & settlement dates).
Use these endpoints to reconcile ledgers and statements.


### List cash transactions

 - [GET /v2/partner/client/{clientId}/transaction/cash](https://docs.fondo.se/openapi/api/transaction/getcashtransactions.md): Returns every cash movement across all accounts belonging to the specified clientId. Each transaction includes its id, transactionType (e.g. deposit, withdrawal, or cash leg of a fund order), linked references (ref, refType, clientRef, executorRef), debit and credit accounts, monetary details (amount, currency), and full lifecycle timestamps (createdDate, modifiedDate, settlementDate). Use this endpoint to audit or reconcile every cash inflow and outflow associated with the client.

### Get cash transaction

 - [GET /v2/partner/client/{clientId}/transaction/cash/{transactionId}](https://docs.fondo.se/openapi/api/transaction/getcashtransactionbyid.md): Returns the full record of a single cash movement identified by transactionId for the given clientId. The response provides all key properties—transactionType (deposit, withdrawal, or cash leg of a fund order), linked references (ref, refType, clientRef, executorRef), debit and credit accounts, amount, currency, optional free text, and full lifecycle timestamps (createdDate, modifiedDate, settlementDate). Use this endpoint to inspect or audit an individual cash transaction in detail.

### List fund transactions

 - [GET /v2/partner/client/{clientId}/transaction/fund](https://docs.fondo.se/openapi/api/transaction/getfundtransactions.md): Returns every fund‐unit movement across the accounts of the specified clientId, including both subscriptions and redemptions. Each transaction details its transactionType (e.g. subscription, redemption), linked references (ref, refType, clientRef, executorRef), target account, instrument identifiers, number of units, executed price, currency, and full lifecycle timestamps (createdDate, modifiedDate, tradeDate, settlementDate). Use this endpoint to audit or reconcile all fund‐unit inflows and outflows associated with the client.

### Get fund transaction

 - [GET /v2/partner/client/{clientId}/transaction/fund/{transactionId}](https://docs.fondo.se/openapi/api/transaction/getfundtransactionbyid.md): Returns the complete record of a single fund‐unit movement identified by transactionId for the given clientId. The response includes the transactionType (subscription or redemption), related references (ref, refType, clientRef, executorRef), account and instrument identifiers, number of units, executed price, currency, and full lifecycle timestamps (createdDate, modifiedDate, tradeDate, settlementDate). Use this endpoint to inspect or audit an individual subscription or redemption transaction.

## Subscriptions (WebSocket)

Receive **real-time updates** from Fondo without polling.
- **WebSocket:** open a persistent stream for `.create`, `.update`, `.delete`, and `heartbeat` events.
- **Journey callbacks:** Fondo sends HTTP POST updates to the `callbackUrl` you provide when creating a journey.
Include replay/retry handling in your consumers.


### Open WebSocket connection

 - [GET /v2/partner/client/{clientId}/subscribe](https://docs.fondo.se/openapi/api/subscription/getwebsocket.md): This is a WebSocket endpoint, not a regular HTTP GET. A plain GET against this path returns 404. The client must perform the WebSocket opening handshake (Upgrade: websocket, Connection: Upgrade, Sec-WebSocket-Version: 13, Sec-WebSocket-Key). On success the server responds with 101 Switching Protocols and the connection is upgraded.

Use this endpoint to receive live updates (for example on orders, transactions, or journeys) without polling the REST API.

Use the wss:// scheme (TLS is required). The full URL is wss://{host}/v2/partner/client/{clientId}/subscribe — for example wss://api.sandbox.fondo.se/... in sandbox.

### Authentication

Authenticate the upgrade with the same OAuth2 bearer token used for REST requests, sent as the Authorization: Bearer  header. Browsers cannot set this header on the WebSocket handshake — partners should connect from a backend.

### Events

Once connected, the server pushes JSON-encoded events. Every event has an eventType; events that carry data also have an eventId and a payload:

- .create — payload.current is the newly created object.
- .update — payload.current is the new state, payload.previous is the prior state.
- .delete — payload.previous is the removed object.
- hello — sent once when the connection opens. Includes an instanceId identifying the server instance handling this connection; a different value on reconnect means you've been routed to a different instance.
- heartbeat — sent at regular intervals to keep the connection alive.
- server_closing — sent shortly before the server initiates a graceful close (for example during a deploy), typically ~2 seconds ahead. Use this signal to open a parallel connection and switch over before the close. Not emitted for unplanned disconnects or the load balancer's hourly connection cap.

### eventId and deduplication

Every data event (.create, .update, .delete) carries an eventId — an opaque UUID string that is unique per WebSocket message and deterministic across server instances. Use it to deduplicate when running parallel connections during reconnect: the same logical event delivered on both connections shares the same eventId, even when the connections are routed to different server instances. eventId is not set on hello, heartbeat, or server_closing, which are per-connection control signals.

### Connection lifetime

The upstream load balancer enforces a maximum lifetime of approximately one hour per connection. Expect a clean close at roughly connectTime + 3600s and reconnect on your side. The hourly cap has no heads-up — server_closing is only emitted for planned server shutdowns (for example deploys), not for the LB timer. To avoid missing events on the cap, open a parallel connection shortly before the hour expires, deduplicate using eventId, then close the original.

See the Real-Time Events guide for the event-type catalogue, code samples, and reconnection guidance.

## System

API Service functions

### Ping service

 - [GET /ping](https://docs.fondo.se/openapi/api/system/ping.md): Simple health-check endpoint that replies with a { "pong": ... } JSON object. Use it to verify that the Fondo API is reachable and responsive before making production calls.