---
title: "Add/Sync Holdings"
method: POST
path: "/portfolio"
tags: ["Widgets"]
---

# Add/Sync Holdings

`POST /portfolio`

## Request

- Base URL: `https://nzxplorer.co.nz/api/v1`
- URL: `https://nzxplorer.co.nz/api/v1/portfolio`
- Auth: one of:
  - API key in header `X-API-Key`
  - API key in query parameter `api_key`

Add a single holding or bulk sync all holdings. Single: send {ticker, shares_held?, avg_cost_nzd?, weight?}. Bulk: send {holdings: [...]} to replace all holdings. Max 100 holdings.

## Request body

- object
  - `ticker` string: NZX ticker (for single add)
  - `shares_held` number: Number of shares held
  - `avg_cost_nzd` number: Average cost per share in NZD
  - `weight` number: Target allocation weight (0-100)
  - `holdings` string: Array of holdings for bulk sync

## Response `200`

Add/Sync Holdings

- Envelope: Standard API response envelope
  - `data` unknown
  - `meta` object
    - `api_version` string
    - `timestamp` string, date-time
    - `format` 'standard' | 'llm' | 'fdc3' | 'toon'
    - `endpoint` string

## Other responses

- `401`: Missing or invalid API key
- `429`: Rate limit exceeded
- `500`: Internal server error

---

[API](https://skmtc.dev/nzxplorer/apis/nzxplorer-api.md) · [All operations](https://skmtc.dev/nzxplorer/apis/nzxplorer-api/llms.txt) · [OpenAPI document](https://skmtc.dev/nzxplorer/apis/nzxplorer-api/revisions/f3b95341783a?raw)