---
title: "Calculate Purification"
method: POST
path: "/api/purification/calculate"
tags: ["zakat"]
---

# Calculate Purification

`POST /api/purification/calculate`

## Request

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

Calculate dividend purification amounts for multiple holdings at once.

For each holding, looks up its Shariah purification rate and applies it to
the provided dividend income to determine how much should be donated. Also
returns the halal amount and whether each holding is compliant.

Key response fields:
- `total_purification`: total dollar amount to donate across all holdings
- `total_halal`: total halal dividend amount to keep
- Each holding includes `purification_rate`, `purification_amount`, and
  `is_compliant`

**curl example:**

    curl -X POST "http://localhost:8000/api/purification/calculate" \
         -H "Content-Type: application/json" \
         -d '{"holdings": [{"symbol": "MSFT", "dividend_income": 320}, {"symbol": "AAPL", "dividend_income": 150}]}'

**Python requests example:**

```python
import requests
resp = requests.post(
    "http://localhost:8000/api/purification/calculate",
    json={
        "holdings": [
            {"symbol": "MSFT", "dividend_income": 320},
            {"symbol": "AAPL", "dividend_income": 150},
        ],
    },
)
data = resp.json()
print(f"Total to purify: ${data['total_purification']:.2f}")
print(f"Halal to keep:   ${data['total_halal']:.2f}")
```

## Request body

- PurificationCalculateRequest: Request to calculate dividend purification amounts for a set of holdings.
  - `holdings` PurificationHolding[], required: List of holdings with dividend income to purify.
    - `symbol` string, required: Ticker symbol (e.g. 'AAPL').
    - `dividend_income` number, required: Dividend income received from this holding in USD.

## Response `200`

Purification amounts per holding with halal/non-halal split.

- PurificationCalculateResponse: Aggregate purification calculation across all holdings.
  - `total_dividend_income` number, required: Sum of all dividend income in USD.
  - `total_purification` number, required: Total amount to purify across all holdings in USD.
  - `total_halal` number, required: Total halal dividend amount after purification in USD.
  - `holdings` PurificationHoldingResult[], required: Per-holding purification details.
    - `symbol` string, required: Ticker symbol.
    - `dividend_income` number, required: Dividend income in USD.
    - `purification_rate` number, nullable: Company-specific purification rate (e.g. 0.031 = 3.1%). Null if unknown.
    - `purification_amount` number, required: Dollar amount to purify (donate) from this holding's dividends.
    - `halal_amount` number, required: Remaining halal dividend amount after purification.
    - `is_compliant` boolean, nullable: Whether the holding is Shariah-compliant. Null if unscreened.
  - `disclaimers` Disclaimer[], nullable: Attached by middleware; see /api/disclaimers.
    - `id` string, required: Stable category identifier — safe for clients to dedupe and cache on.
    - `version` string, required: ISO-8601 date of the most recent edit to `text`. Advances whenever the wording changes, even for typo fixes.
    - `lang` string: BCP-47 language tag for `text`. Today always 'en'; reserved for future i18n.
    - `severity` string, required: Grouping hint for UIs. 'religious' for fatwa/scholar caveats; 'data' for data-freshness, sourcing, or coverage caveats.
    - `text` string, required: Short inline disclaimer text.
    - `url` string, required: Canonical legal page URL (deep-linked to the relevant section).

## Other responses

- `401`: Authentication required (if auth is enabled).
- `422`: Validation Error

---

[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)