Migrate from Beta

Map connection-first beta routes and SDK wrappers to the account-first API.

The beta API exposed broker connections as the primary integration resource. The API makes the financial account and company grant the public resource. Existing beta routes remain available during the migration window, but new integrations should use sessions, Connect grants, account-scoped data reads, account-scoped trading, and webhook subscriptions.

Migration checklist

Replace stored connectionId references with financial accountId references returned by account APIs.
Create company-owned sessions from your backend.
Open Connect through a portal link and create account grants.
Read balances, positions, transactions, and orders under /api/v1/accounts/{accountId}/....
Add Idempotency-Key to order create/modify/cancel commands.
Subscribe to webhook event types and route events by companyAccountId, accountId, and grantId.

Route mapping

Beta route family	Current API
`POST /api/beta/session/init`	`POST /api/v1/sessions` from a backend with `X-API-Key`.
`POST /api/beta/session/start`	Browser SDK initialization from a one-time token.
`GET /api/beta/session/portal`	`POST /api/v1/sessions/{sessionId}/portal-links`, then open Connect.
`GET /api/beta/session/{sessionId}/user`	`GET /api/v1/sessions/{sessionId}/user` from the backend.
`POST /api/beta/session/link-user`	`POST /api/v1/portal/{sessionId}/user-link`.
`GET /api/beta/portal/{token}`	`GET /api/v1/portal/{token}`.
`POST /api/beta/portal/{sessionId}/complete`	`POST /api/v1/portal/{sessionId}/complete`.
`GET /api/beta/brokers`	`GET /api/v1/portal/{sessionId}/institutions`.
`POST /api/beta/brokers/connect`	`POST /api/v1/portal/{sessionId}/auth-attempts`.
`GET /api/beta/brokers/data/accounts`	`GET /api/v1/accounts`.
`GET /api/beta/brokers/data/balances`	`GET /api/v1/accounts/{accountId}/balances`.
`GET /api/beta/brokers/data/positions`	`GET /api/v1/accounts/{accountId}/positions`.
`GET /api/beta/brokers/data/orders`	`GET /api/v1/accounts/{accountId}/orders`.
`GET /api/beta/brokers/data/orders/{orderId}/fills`	`GET /api/v1/accounts/{accountId}/orders/{orderId}/fills`.
`GET /api/beta/brokers/data/orders/{orderId}/events`	`GET /api/v1/accounts/{accountId}/orders/{orderId}/events`.
`GET /api/beta/brokers/data/transactions`	`GET /api/v1/accounts/{accountId}/transactions`.
`POST /api/beta/brokers/orders`	`POST /api/v1/accounts/{accountId}/orders`.
`PATCH /api/beta/brokers/orders/{orderId}`	`PATCH /api/v1/accounts/{accountId}/orders/{orderId}`.
`DELETE /api/beta/brokers/orders/{orderId}`	`DELETE /api/v1/accounts/{accountId}/orders/{orderId}`.
`GET /api/beta/brokers/connections`	`GET /api/v1/accounts` and `GET /api/v1/account-grants`.

SDK mapping

Beta SDK pattern	SDK pattern
`finatic.getBrokerConnections()`	`finatic.v1.listAccounts()` plus `finatic.v1.listAccountGrants()`.
`finatic.getAccounts({ connectionId })`	`finatic.v1.listAccounts()` then account-scoped methods.
`finatic.getPositions({ connectionId, accountId })`	`finatic.v1.listPositions({ accountId })`.
`finatic.getOrders({ connectionId, accountId })`	`finatic.v1.listOrders({ accountId })`.
`finatic.placeOrder({ broker, accountNumber, order })`	`finatic.v1.createAccountOrder({ accountId, body,
idempotencyKey })`.
Server `getToken()` only	Server session plus portal-link flow for new Connect sessions.

Webhook migration

Beta webhook event names such as account.orders.updated and connection.updated are replaced by current event names such as order.updated, account.sync.succeeded, and connection.reauth.required.

Use the catalog endpoint and this docs page as the source of truth for current event strings:

curl https://api.finatic.dev/api/v1/webhooks/catalog