---
title: "Portfolio Scan"
method: POST
path: "/api/portfolio/scan"
tags: ["portfolio"]
---

# Portfolio Scan

`POST /api/portfolio/scan`

## Request

- Base URL: `https://api.halalterminal.com`
- URL: `https://api.halalterminal.com/api/portfolio/scan`
- Auth: API key in header `X-API-Key`

Scan a portfolio of stocks for Shariah compliance.

Set `force_refresh=true` to bypass cached screening data — available
only for enterprise and internal plans. For other plans the flag is
silently treated as False.

## Request body

- PortfolioScanRequest: Request to scan a portfolio of stock symbols for Shariah compliance.
  - `symbols` string[], required: List of ticker symbols to screen (e.g. ['AAPL', 'MSFT', 'GOOGL']).
  - `force_refresh` boolean: When true, bypass cached screening results and re-screen from scratch.

## Response `200`

Per-symbol screening results and aggregate portfolio compliance summary.

- PortfolioScanResponse: Full portfolio scan result with per-symbol details and summary statistics.
  - `results` object, required: Mapping of ticker symbol to its screening result.
  - `summary` PortfolioSummaryResponse, required: Aggregate compliance statistics for a portfolio scan.
    - `total` integer, required: Total number of symbols scanned.
    - `compliant` integer, required: Number of Shariah-compliant symbols.
    - `non_compliant` integer, required: Number of non-compliant symbols.
    - `pending` integer, required: Number of symbols still pending screening (data unavailable).
    - `avg_purification_rate` number, required: Average purification rate across all screened holdings (e.g. 0.03 = 3%).
    - `engine_version` string, required: Build identifier of the screening engine that produced this scan.

## Other responses

- `422`: Validation Error
- `429`: Rate limit exceeded. Try again later.

---

[API](https://skmtc.dev/halalterminal/apis/halal-terminal-api.md) · [All operations](https://skmtc.dev/halalterminal/apis/halal-terminal-api/llms.txt) · [OpenAPI document](https://skmtc.dev/halalterminal/apis/halal-terminal-api/revisions/78768b250943?raw)