Purification API

Dividend purification

AAOIFI-aligned calculator: send a ticker and dividends received — get the purification amount, compliance status, and a clear recommendation. One product, no tariff tiers.

Quick start

  1. Get an API key from Ailat (keys look like rpuri_…).
  2. Send X-Api-Key (or Bearer) on every request.
  3. Call POST /v1/calculate with ticker and dividendsReceived.

Base URL

https://purification.ailat.kz

How it works

The API looks up Shariah financial reports for the ticker (26 000+ companies), applies methodology rules, and returns a status + recommendation:

Situation Status Purification Recommendation
Company not in DB NOT_FOUND 0 MANUAL_INPUT_REQUIRED
Halal — 0% impure income COMPLIANT_PURE 0 NO_ACTION
Halal — impure fraction COMPLIANT_IMPURE ceil(dividends × haram %) PURIFY_ONLY
Haram core business NON_COMPLIANT_CORE_BUSINESS 100% of dividends SELL_IMMEDIATELY
Failed financial ratios NON_COMPLIANT_FINANCIAL_RATIOS ceil(dividends × haram %) GRACE_PERIOD_2_QUARTERS

Amounts are rounded up to whole currency units. Optional manual overrides: impureIncomeRatio (0–1) and isProhibitedBusiness.

Authentication

Partners authenticate with an API key on every request:

Preferred — header

X-Api-Key: rpuri_YOUR_KEY

Also accepted

Authorization: Bearer rpuri_YOUR_KEY

If the subscription has expired, metered routes return 403. GET /v1/me still works so you can see why access stopped.

Limits

Quota applies only to calculation calls. Account endpoints are free.

LimitDefaultNotes
Per minute 100 Stops tight retry loops
Per day 5 000 May be lower per client (rateLimitPerDay)
Holdings in portfolio 20 Max items in one POST /v1/portfolio

Metered: POST /v1/calculate, /v1/screen (alias), /v1/portfolio. Free: GET /v1/me, /v1/usage, /v1/usage/history, /v1/meta. Over limit → 429.

Calculate — single security

POST /v1/calculate (alias: POST /v1/screen)

FieldRequiredDescription
ticker Yes Trading symbol, e.g. AAPL
dividendsReceived Yes Number ≥ 0
year No Report year (number or string)
date No ISO date; year is taken from the first 4 chars if year omitted
currency No Display currency label
lang No en or ru (default ru). Also: Accept-Language
impureIncomeRatio No 0–1. Manual fallback if the ticker is not in the DB
isProhibitedBusiness No Manual fallback: treat core business as haram

Request

curl -X POST "https://purification.ailat.kz/v1/calculate" \
  -H "X-Api-Key: rpuri_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "ticker": "AAPL",
  "dividendsReceived": 1000,
  "year": 2025,
  "lang": "en"
}'

Example response

{
  "ticker": "AAPL",
  "companyName": "Apple Inc",
  "currency": "USD",
  "reportYear": "2025",
  "quarter": "FY",
  "dividendsReceived": 1000,
  "purificationAmount": 28,
  "appliedHaramRatio": 0.0274,
  "status": "COMPLIANT_IMPURE",
  "recommendation": "PURIFY_ONLY",
  "notes": "Company is Shariah-compliant. … Purify 28 USD. No need to sell shares.",
  "lang": "en",
  "disclaimer": "Informational estimate aligned with common AAOIFI screening practice. Not a fatwa or investment advice."
}

Portfolio — batch

POST /v1/portfolio — up to 20 holdings in one call.

Request

curl -X POST "https://purification.ailat.kz/v1/portfolio" \
  -H "X-Api-Key: rpuri_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "defaultYear": 2025,
  "lang": "en",
  "holdings": [
    { "ticker": "AAPL", "dividendsReceived": 1000 },
    { "ticker": "MSFT", "dividendsReceived": 500 }
  ]
}'

Example response (shape)

{
  "totalDividendsReceived": 1500,
  "totalPurificationAmount": 40,
  "securityCount": 2,
  "compliantPureCount": 0,
  "compliantImpureCount": 2,
  "nonCompliantCoreBusinessCount": 0,
  "nonCompliantFinancialRatiosCount": 0,
  "notFoundCount": 0,
  "items": [ /* same shape as /v1/calculate per holding */ ],
  "lang": "en",
  "disclaimer": "…"
}

Account helpers

MethodPathReturns
GET /v1/me Client identity, plan, subscription, key prefix, limits
GET /v1/usage Used / remaining for minute and day
GET /v1/usage/history Recent calls (?limit=, ?offset=)
GET /v1/meta Methodology thresholds, service limits, disclaimer

curl

curl "https://purification.ailat.kz/v1/me" -H "X-Api-Key: rpuri_YOUR_KEY"
curl "https://purification.ailat.kz/v1/usage" -H "X-Api-Key: rpuri_YOUR_KEY"
curl "https://purification.ailat.kz/v1/meta" -H "X-Api-Key: rpuri_YOUR_KEY"

Errors

CodeWhen
400 Validation error (bad body / missing fields)
401 Missing or invalid API key
403 Subscription expired (except /v1/me)
429 Per-minute or daily quota exceeded