Portfolio API: Getting started

Integrate your portfolio data with external applications using the Consumer API. Create API keys, authenticate requests, and automate your investment workflows.

Last reviewed

Screenshot, for illustration only

The Developer page under Account, where API keys and webhook endpoints are created and managedThe Developer page under Account, where API keys and webhook endpoints are created and managed
The Developer page under Account, where API keys and webhook endpoints are created and managedThe Developer page under Account, where API keys and webhook endpoints are created and managed
The Developer page under Account, where you create and manage API keys.

Getting started

What the Consumer API is and who can use it.

What is the consumer API?

The Portfolio Tracker Consumer API allows you to access your portfolio data programmatically. You can fetch holdings, record transactions, import broker statements, and receive real-time notifications via webhooks, all from your own scripts, spreadsheets, or third-party tools.

The API follows RESTful conventions and returns JSON responses. All endpoints are versioned under /api/v1/portfolio/ext/ to ensure stability as we add new features.

Who can use the API?

The Consumer API is included in these plans. Each plan’s request allowance is listed under Rate Limits below.

  • Silver: API access
  • Gold: API access plus webhook support
  • Platinum: API access plus webhook support
  • VIP Concierge: API access plus webhook support

Note

If your plan does not include the Consumer API, you can upgrade from the Subscription page to get started.

What can you do with it?

The API gives you full programmatic access to your portfolio data. Common use cases include:

  • Retrieve holdings: Fetch your current positions, market values, and gain/loss data
  • Record transactions: Log buy, sell, and dividend transactions automatically
  • Import statements: Upload broker statements for automatic parsing
  • Set up webhooks: Receive notifications when a price alert triggers or a transaction is processed (on the Gold, Platinum and VIP Concierge plans)
  • Export data: Pull your portfolio data into spreadsheets, dashboards, or analytics tools

Endpoint groups

Each group below lives under /api/v1/portfolio/ext/. Reading any of them needs portfolio:read; the groups marked as writable also take POST requests, which need portfolio:write.

  • Holdings and valuations: your current positions and their saved valuations. holdings/, holdings/valuations/
  • Income and dividends: income received, yield, the dividend calendar, the income forecast and your reinvestment preferences. income/, income/yield/, income/calendar/, income/forecast/, income/reinvestment-preferences/
  • Investment costs: a breakdown of what your investments cost, with account charges, currency conversion costs and margin interest. costs/, costs/types/, costs/account-charges/, costs/fx/, costs/margin/
  • Returns, benchmarks and allocation: returns over standard periods, comparison with a benchmark, attribution, risk figures, portfolio history and allocation by sector, region and currency. analytics/allocation/, analytics/performance/, analytics/periods/, analytics/returns/, analytics/benchmark/, analytics/attribution/, analytics/risk/, analytics/portfolio-history/, analytics/allocation/sector/, analytics/allocation/geographic/, analytics/allocation/currency/
  • Tax figures: estimated disposals, dividends, pooled holdings, tax years, losses carried forward, wash sales, tax lots and tax documents. tax/summary/, tax/events/, tax/disposals/, tax/dividends/, tax/section104/, tax/years/, tax/carry-forward/, tax/wash-sales/, tax/lots/, tax/documents/
  • Family members, households and sharing: the family members and households you manage, the portfolios shared with you or by you, and pending transfers between members. members/, members/consolidated/, households/, shares/, shares/incoming/, snapshots/, pending-transactions/, transfers/
  • Cash, leveraged positions and export: cash balances and movements, leveraged positions and their fills, and a download of your whole portfolio. cash-balances/, cash-movements/, leveraged-positions/, leveraged-transactions/, export/
  • Watchlists, accounts, imports and corporate actions (writable): create watchlists and add securities to them, add and change accounts, review and confirm imports, and confirm or undo corporate actions. watchlists/, accounts/, imports/, corporate-actions/, transactions/
  • Sector news: news headlines with links to the source, filtered by topic or country, and the list of topics. news/articles/, news/topics/

Every write accepts an Idempotency-Key header, so a retried request is applied once. The two writes that cannot be undone, reversing an import and undoing a corporate action, also need "confirm": true in the request body.

Authentication

How to create and use API keys to authenticate your requests.

Creating an API key

API keys are created from the Developer hub. Each key is scoped to your account and can be revoked at any time.

  1. Open the Developer hub with the Go to developer hub button at the foot of this page (the Portfolio Tracker Developer page shows the same tools, so either route works)
  2. Click "Create key" and give your key a descriptive name (e.g. "My Spreadsheet Integration")
  3. Choose the scopes the key needs (listed below). Give each key only the scopes its integration uses
  4. Copy the key immediately, because it will only be displayed once
  5. Store the key securely (e.g. in a password manager or environment variable)

Each request needs the exact scope its endpoint asks for. Scopes never imply one another, so a key with only portfolio:write is refused with 403 when it reads holdings. The scopes are:

  • portfolio:read: read holdings, transactions, performance and other portfolio data
  • portfolio:write: create, change or delete records, such as recording a transaction or importing a statement. It does not include reading: add portfolio:read as well
  • estate:read: read your estate plan (people, gifts, wishes, document details and residency history, never will wording or document files)
  • residency:read: read residency day counts through an AI assistant connection (days per country, never your location history)
  • documents:read: download the original files in your document vault and your will PDFs. A key with this scope must expire within 90 days

Important

Your API key is shown only once at creation time. We store a one-way Argon2 hash of the key, so it cannot be retrieved later. If you lose your key, revoke it and create a new one.

Using your API key

All API requests must include your key in the Authorization header using the Bearer scheme. Keys use a twai_ prefix so they are easy to identify in your code (older keys beginning pk_ keep working).

Example header:

Authorization: Bearer twai_your_api_key_here

Tip

Never hard-code your API key directly in source files. Use environment variables or a secrets manager to keep your key safe.

Your first API call

A step-by-step guide to making your first request.

Step-by-step

Follow these steps to verify your API key is working and retrieve your holdings.

  1. Create an API key from the Developer hub (see Authentication above)
  2. Make a GET request to the holdings endpoint:
    GET /api/v1/portfolio/ext/holdings/
    Include your API key in the Authorization header as described above
  3. Check the response. A successful request returns a JSON object containing your holdings array along with summary data such as total market value and daily change
  4. If you receive a 401 Unauthorised response, verify that your key is correct and has not been revoked

Tip

Use a tool such as cURL or your programming language’s HTTP library to make your first request. See the Code Examples page for ready-to-use snippets in Python, JavaScript, and more.

Every endpoint, field and error is described in the API reference. Try requests in the interactive console, or download the OpenAPI schema to generate a client or import it into an API tool of your choice.

Rate limits

Understand how request limits work for each plan tier.

Limits are counted on a sliding window. When you go over one, the API answers 429 Too Many Requests with a Retry-After header telling you how long to wait.

Consumer API

Every request to /api/v1/portfolio/ext/.

  • Silver: 50 requests per hour
  • Gold: 2,000 requests per hour
  • Platinum: 2,000 requests per hour
  • VIP Concierge: unlimited

Shared by every key you hold, so a new key never adds to it. Plans not listed here have no access to this API. Scopes: portfolio:read, portfolio:write, estate:read, residency:read, documents:read.

Document downloads

Each vault file or will PDF handed out, on top of the Consumer API budget.

  • Every plan: 60 requests per hour

Shared by every key you hold, so a new key never adds to it. Scopes: documents:read.

Consumer MCP agent tools

MCP tool calls, counted separately from your REST budget.

  • Silver: 50 requests per hour
  • Gold: 2,000 requests per hour
  • Platinum: 2,000 requests per hour
  • VIP Concierge: unlimited

Shared by every key you hold, so a new key never adds to it. Plans not listed here have no access to this API. Scopes: portfolio:read, estate:read, residency:read.

These figures come from the limits the API enforces, also served as JSON at /api/v1/portfolio/rate-limits/.

Every response reports your allowance in the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers, so an integration can pace itself. The Usage panel on the Developer Page breaks the hour down by key so you can find the integration spending it.

Tip

Cache responses locally where possible and avoid polling more frequently than necessary. If you need real-time updates, consider setting up webhooks (available on the Gold, Platinum and VIP Concierge plans) instead of polling.

Common workflows

Typical ways to use the Consumer API.

Popular use cases

Below are some of the most common workflows that API users set up. Each one is covered in detail in the Code Examples help page.

  • Fetching holdings: Retrieve your current portfolio positions, including quantities, market values, and unrealised gains
  • Recording transactions: Programmatically log buy, sell, and dividend transactions to keep your portfolio up to date
  • Importing broker statements: Upload CSV or PDF statements from supported brokers for automatic parsing and reconciliation
  • Setting up webhooks: Register callback URLs to receive real-time notifications when a transaction is created, a corporate action is detected, a price alert triggers, tax figures are recalculated, or an import completes (on the Gold, Platinum and VIP Concierge plans)

Related topics

Can’t find what you’re looking for?

Our support team is here to help. Contact us and we’ll get back to you as soon as possible.

Contact us

We use cookies to improve your experience. See our Cookie policy (opens in a new tab) for details.