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




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
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.
- 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)
- Click "Create key" and give your key a descriptive name (e.g. "My Spreadsheet Integration")
- Choose the scopes the key needs (listed below). Give each key only the scopes its integration uses
- Copy the key immediately, because it will only be displayed once
- 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 dataportfolio:write: create, change or delete records, such as recording a transaction or importing a statement. It does not include reading: add portfolio:read as wellestate: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
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
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.
- Create an API key from the Developer hub (see Authentication above)
- Make a GET request to the holdings endpoint:
GET /api/v1/portfolio/ext/holdings/
Include your API key in theAuthorizationheader as described above - 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
- If you receive a
401 Unauthorisedresponse, verify that your key is correct and has not been revoked
Tip
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
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
Code examples
Ready-to-use snippets in Python, JavaScript, and more
Connect an AI agent
Hook an MCP client up to your portfolio
Webhook reference
Set up real-time notifications for portfolio events
API changelog
Track changes, deprecations, and new endpoints
API documentation
Full endpoint reference with request and response schemas
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
