PORTIQA
Log in Get API key
Developer guide

How to integrate a portfolio analysis API.

A useful portfolio API does more than return a number. It resolves holdings, measures structure, exposes evidence quality, and gives your product enough detail to explain the result.

Last reviewed: · By

What a portfolio analysis API should do

The core input is simple: a list of securities and their values. The hard part begins after the request arrives. Tickers must be matched to the correct instruments, values normalised into weights, classifications and market evidence attached, and missing data surfaced. The result then has to separate portfolio structure from market opinion.

PORTIQA’s POST /evaluate endpoint returns a health score and status alongside concentration metrics, component scores, holding analysis, an exposure plan, coverage, diagnostics, insights, and suggestions. The component and diagnostic fields are the important part for an integration because they explain why the headline score exists.

1. Define the request contract

Send market values when you already calculate them. If you send amounts, the service must have a usable reference price. Use the canonical ticker format expected by the security master, keep cash separate from invested positions, and choose a risk level deliberately rather than accepting a default without telling the user.

curl -X POST https://portiqa.ai/evaluate \
  -H "Authorization: Bearer $PORTIQA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "risk_level": "medium",
    "cash_balance": 5000,
    "positions": [
      {"ticker": "AAPL", "market_value": 25000},
      {"ticker": "MSFT", "market_value": 22000},
      {"ticker": "NVDA", "market_value": 8000}
    ]
  }'

Keep the bearer key on your server. Browser and mobile clients should call your backend, which validates the user and then calls PORTIQA. This prevents a public bundle from exposing a reusable credential.

2. Read the response in layers

  1. Identity: store engine_version with the result.
  2. Triage: use score and status for the initial summary.
  3. Structure: inspect maximum position weight, effective positions, top sector, and its weight.
  4. Components: compare diversification, risk, quality, signal, and trend instead of treating the composite as a diagnosis.
  5. Confidence: check coverage, classification quality, factor-evidence quality, and data_gaps.
  6. Action: present holding analysis, exposure planning, insights, and suggestions only with their supporting evidence.

3. Design for disagreement

Component disagreement is information. A portfolio can contain strong companies and still be concentrated in one sector. It can be diversified but poorly aligned with the selected risk level. Your UI should make those tensions visible with separate labels or bars. A single green score that hides a weak component creates false certainty.

4. Handle incomplete evidence

An unresolved ticker should produce a visible warning. Low factor coverage should reduce confidence in forward-looking context. A missing beta should not become zero, because zero is a real value with a different meaning. Use the response coverage and diagnostics to decide whether to show a component, mark it provisional, or ask the user to correct an identifier.

5. Make versioning explicit

Persist the request, result, evaluation time, and engine_version when the user saves an analysis. If a later engine version changes thresholds or weights, do not draw an unexplained trend line across the version boundary. Re-evaluate the old portfolio with the new version or clearly label the comparison.

6. Treat errors as product states

Build checklist

Use the API reference for the field contract, the code examples for complete requests, and the methodology for calculation context.