---
title: "Get Dividend Purification"
method: GET
path: "/api/dividends/{symbol}/purification"
tags: ["dividends"]
---

# Get Dividend Purification

`GET /api/dividends/{symbol}/purification`

## Request

- Base URL: `https://api.halalterminal.com`
- URL: `https://api.halalterminal.com/api/dividends/{symbol}/purification`
- Auth: API key in header `X-API-Key`

Calculate dividend purification amounts for a stock.

Applies the company's Shariah purification rate to each historical
dividend payment and returns per-dividend purification amounts, the
halal portion, and aggregate totals.

Key fields in the response:
- `purification_rate`: the company-level rate (e.g. 0.031 = 3.1%)
- `total_dividends`: sum of all dividends
- `total_purification`: total amount to donate
- `total_halal`: total amount that is halal to keep

**curl example:**

    curl -X GET "http://localhost:8000/api/dividends/MSFT/purification"

**Python requests example:**

```python
import requests
resp = requests.get("http://localhost:8000/api/dividends/MSFT/purification")
data = resp.json()
print(f"Purification rate: {data['purification_rate']:.1%}")
print(f"Total to purify: ${data['total_purification']:.2f}")
```

## Path parameters

- `symbol` string, required: Ticker symbol, e.g. AAPL.

## Response `200`

Dividend purification breakdown with per-payment and total amounts.

- DividendPurificationResponse: Dividend purification breakdown for a stock over its full history.
  - `symbol` string, required: Ticker symbol (e.g. 'MSFT').
  - `purification_rate` number, nullable: Company-level purification rate (e.g. 0.031 = 3.1%).
  - `count` integer, required: Total number of dividend payments included.
  - `dividends` PurifiedDividend[], required: List of dividends with purification amounts.
    - `date` string, required: Payment date in YYYY-MM-DD format.
    - `amount` number, required: Original dividend amount per share in USD.
    - `purification_rate` number, nullable: Purification rate applied to this dividend (e.g. 0.031 = 3.1%).
    - `purification_amount` number, nullable: Dollar amount to purify (donate) from this dividend.
    - `halal_amount` number, nullable: Remaining halal amount after purification.
  - `total_dividends` number, required: Sum of all dividend amounts in USD.
  - `total_purification` number, required: Total amount to purify across all dividends in USD.
  - `total_halal` number, required: Total halal amount after purification in USD.

## Other responses

- `404`: Symbol not found or has no dividend/screening data.
- `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)