Shariah Screening API: Docs, Endpoints & Quickstart

This is a hands-on quickstart for adding Shariah screening to your product with the Akinda Halal API. In a few minutes you'll go from an API key to your first compliance verdict, then see how to screen a whole portfolio, handle errors, and run the integration in production. Automated Shariah screening has become mainstream, digital Islamic investment platforms have grown by roughly a third year on year, and modern screeners now check compliance across 12,000+ listed global equities, so a clean API integration is worth getting right. The code below is illustrative to show the shape of a call; the authoritative request parameters and response schema always live in the live developer docs, which are linked throughout.

Table of Contents

• What the API gives you
• The endpoints
• Authentication
• Quickstart: your first compliance check
• Screening a whole portfolio
• Reading the response
• Handling errors and edge cases
• Production tips

What the API gives you

The Shariah screening API turns “is this stock halal?” into a single HTTP request. You send a ticker; it returns a Shariah-compliance verdict and, depending on the endpoint, the business-activity result, the financial ratios, and purification data behind it. The rules come from a published, AAOIFI-based screening methodology, so the output is auditable rather than a black-box flag. You can see the same screening from the user's side on Akinda's live screener.

The endpoints

Three endpoints cover everything from a quick gate check to a full compliance view. Start narrow and add detail where your UI needs it.

Each endpoint is documented with its exact parameters and response fields, jump straight to the compliance, basic report, or full report reference.

Authentication

The API uses key-based authentication. Generate a key in the dashboard, then send it with every request as a bearer token in the Authorization header. Two rules keep you safe:

• Keep keys server-side. Never ship an API key in client-side code or a mobile bundle, where it can be extracted. Proxy screening calls through your backend.
• Use environment variables. Load the key from an environment variable or secret manager rather than committing it to source control.

The exact header format and any additional parameters are in the developer docs; the illustrative examples below assume a bearer token.

Quickstart: your first compliance check

Four steps take you from zero to a verdict.

1. Sign in and generate an API key from the dashboard.
2. Store the key as an environment variable, for example AKINDA_API_KEY.
3. Call the compliance endpoint with a ticker, passing your key as a bearer token.
4. Parse the JSON verdict and render it in your app.

An illustrative request (check the docs for the exact parameter format):

# Illustrative only - see b2b.akinda.io/developer/docs for exact params
curl -H "Authorization: Bearer $AKINDA_API_KEY" \
    "https://b2b.akinda.io/api/v1/compliance?symbol=AAPL"

An illustrative response shape (field names are examples; the docs define the real schema):

{
  "symbol": "AAPL",
  "status": "COMPLIANT",        // or NON_COMPLIANT
  "as_of": "2026-01-31"
}

Screening a whole portfolio

Most real integrations screen more than one ticker. The pattern is simple: iterate over the holdings, call the endpoint for each, and aggregate the verdicts. An illustrative loop:

# Illustrative pseudocode - confirm bulk options and limits in the docs
import os, requests

API = "https://b2b.akinda.io/api/v1/compliance"
KEY = os.environ["AKINDA_API_KEY"]
holdings = ["AAPL", "NVDA", "XOM", "JPM"]

results = {}
for symbol in holdings:
    r = requests.get(API, headers={"Authorization": f"Bearer {KEY}"},
                    params={"symbol": symbol}, timeout=10)
    r.raise_for_status()
    results[symbol] = r.json().get("status")

non_compliant = [s for s, v in results.items() if v != "COMPLIANT"]

Cache the results and re-run the loop on a schedule rather than on every page load. If you need to screen large indices at once, check the developer docs for any bulk or batch options and the current rate limits before designing the job.

Reading the response

Whatever the exact field names, a screening response carries a few conceptual pieces you'll build around:

• The verdict - a compliant / non-compliant status you map to a badge or a gate decision.
• The business-activity result - whether the company's core business passed the first screen.
• The financial ratios - debt and liquidity measured against the methodology's thresholds (available on the report endpoints).
• Purification data - the figure your app uses to tell users how much dividend income to cleanse (full report).
• A timestamp - so you know how fresh the verdict is and when to re-screen.

The full-report endpoint is where the ratios and purification fields live; the developer docs list every field and type.

Handling errors and edge cases

A production integration has to handle more than the happy path. Plan for these cases:

• Unknown or unlisted tickers. Not every symbol will have coverage. Decide how your UI shows “not screened” rather than defaulting it to compliant or non-compliant.
• Rate limiting. If you exceed your plan's limits, expect a throttling response, back off and retry rather than hammering the endpoint.
• Timeouts and transient errors. Wrap calls in retry-with-backoff logic and set sensible timeouts so a slow response doesn't block a trade screen.
• Fail safe, not open. If a verdict genuinely can't be fetched, degrade gracefully, show an “unable to verify” state instead of silently passing a stock through a compliance gate.
• Stale verdicts. Use the timestamp to flag data that's older than your re-screening window.

Production tips

A few practices keep the integration reliable as you scale.

• Cache and re-screen. Store verdicts and refresh them quarterly, after earnings season, rather than calling on every page load.
• Monitor your usage. Track request volume against your plan so a spike, say a portfolio re-screen for every user on the same day, doesn't hit a limit unexpectedly.
• Mind rate limits. Check the current limits on the pricing page and batch portfolio re-screens accordingly.
• Wire it into AI agents. Because responses are structured JSON, you can expose the endpoints to an AI agent or MCP toolchain so a model can screen tickers mid-conversation.
• Test against the documented schema. Point your integration tests at the fields defined in the docs so you catch any schema change early.

Frequently asked questions

How do I authenticate with the Shariah screening API?

Generate an API key from the dashboard and send it as a bearer token in the Authorization header of each request. Keep the key server-side, in an environment variable or secret manager, rather than exposing it in client code. The developer docs describe the exact authentication scheme and any additional headers.

Which endpoint should I start with?

Start with the compliance endpoint. It returns a fast halal / non-compliant verdict that's perfect for a badge or a pre-trade gate, the most common first integration. Move to the basic or full report endpoints when you need to show the ratios and purification data behind the verdict on a detail screen.

Can I screen an entire portfolio or index at once?

You can screen many tickers by calling the endpoint for each holding and aggregating the results, which is how portfolio-monitoring features are built. For large indices, check the developer docs for any bulk or batch options and the current rate limits, then schedule the job rather than screening everything on demand.

How should I handle tickers the API doesn't cover?

Treat an unknown ticker as “not screened,” not as a pass or fail. Surface a neutral state in your UI and, if it matters for a trade gate, fail safe by blocking or warning rather than letting an unverified stock through. This keeps your compliance guarantees honest.

Where do I find the exact response schema?

In the live developer docs. Field names and types are defined there per endpoint, and because a schema can evolve, the docs are the authoritative source, treat any example in a tutorial (including this one) as illustrative. Link your integration tests to the documented schema so you catch changes early.

Sources

AAOIFI Shari'ah Standard No. 21: Financial Paper (Shares and Bonds) – the standard the Akinda API's screening methodology is built around.

Akinda API screening methodology – the full three-phase screen, ratio formulas, and purification rule, published for integrators to audit.

Akinda API Shariah advisor – the scholar governance behind the API's halal verdicts.

Mordor Intelligence – Global Islamic Finance Market (2026) – Islamic finance market size and growth projections.

Disclaimer

This article is about a software product and is for general information only. It is not financial or religious advice. Automated Shariah screening produces data-driven signals, not a fatwa; integrators should pair it with their own Shariah governance and consult qualified scholars. API features, endpoints, coverage, and pricing change over time, so verify current details on b2b.akinda.io before building.