FaithScreener API

Base URL: https://faithscreener.com

Prefer a machine-readable spec? Download the OpenAPI spec

Authentication

All authenticated requests send your API key in the X-API-Key header.

X-API-Key: fsk_live_your_key

Manage your API keys at /account/api-keys. Keys start with fsk_live_ and are tied to your subscription tier.

Screen a single stock

Response

{
  "ticker": "AAPL",
  "market": "us",
  "report": {
    "ticker": "AAPL",
    "company_name": "Apple Inc.",
    "catholic_usccb": {
      "status": "compliant",
      "reasons": [/* ... */]
    },
    "christian_bri": {
      "status": "compliant"
    },
    "financial_data": { /* market_cap, ratios, provenance ... */ },
    "frameworks_returned": ["catholic_usccb", "christian_bri"]
  },
  "from_cache": true,
  "cache_age_days": 2,
  "stale": false
}

Framework scoping

Every screen computes all 10 frameworks. The framework query parameter filters the response down to the ids you name - it never changes what is computed or how results are cached.

Partner keys can be provisioned with allowed_frameworks. Such a key gets every response scoped to its grant automatically, and an explicit framework= ask outside the grant returns 403 naming the denied ids.

madhhab_views is derived from the five Shariah methodologies and is only included when at least one shariah_* framework is returned. faithscreener_consensus blends Shariah signal and requires its own grant.

Point-in-time (as_of)

Add as_of=YYYY-MM-DD to read the verdict FaithScreener's compliance history holds for that date - 872,000+ snapshots reaching back to 2009. The response is snapshot-shaped (per-framework status plus key ratios) with historical: true.

Available to API keys (endpoint tag screen/history, 2 units per call) and Pro/Enterprise accounts (counts as one screen). Malformed dates, dates before 2009-01-01, and future dates return 400; a date before the ticker's first snapshot returns 404.

Response

{
  "ticker": "AAPL",
  "market": "us",
  "as_of": "2024-06-01",
  "snapshot_date": "2024-05-31",
  "screened_at": "2024-05-31T00:00:00",
  "source": "historical_backfill",
  "era": "legacy",
  "data_quality": {
    "warning": "This snapshot predates the 2026-07-04 screening-engine revision. ...",
    "engine_current_since": "2026-07-04"
  },
  "frameworks": {
    "catholic_usccb": { "status": "compliant" },
    "christian_bri": { "status": "compliant" }
  },
  "historical": true
}

Bulk screening

Request example

curl -X POST "https://faithscreener.com/api/screen/batch" \
  -H "X-API-Key: fsk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"tickers":[{"market":"us","ticker":"AAPL"},{"market":"uk","ticker":"ULVR"}],"frameworks":["catholic_usccb"]}'

Returns requested / succeeded / failed counts plus results[] (each result carries the same report shape as the single-screen endpoint) and errors[].

ETF screening

Request example

curl -X POST "https://faithscreener.com/api/screen/etf" \
  -H "X-API-Key: fsk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"etf_ticker":"SPY","market":"us","max_holdings":15}'

Compare stocks

Request example

curl "https://faithscreener.com/api/screen/compare?tickers=AAPL,MSFT,GOOG&market=us" \
  -H "X-API-Key: fsk_live_your_key"

List frameworks

Response

{
  "count": 10,
  "frameworks": [
    { "id": "catholic_usccb", "label": "USCCB 2021 Guidelines", "tradition": "Catholic" },
    { "id": "christian_bri", "label": "Biblically Responsible Investing", "tradition": "Christian" }
    // ... 8 more
  ],
  "key_scope": {
    "allowed_frameworks": ["catholic_usccb", "christian_bri"],
    "allowed_markets": null,
    "allowed_endpoints": ["screen", "screen/history"]
  }
}

Search companies

Response

{
  "query": "APP",
  "count": 2,
  "results": [
    { "ticker": "AAPL", "name": "Apple Inc.", "market": "us", "exchange": "NASDAQ" },
    { "ticker": "APP", "name": "AppLovin Corporation", "market": "us", "exchange": "NASDAQ" }
  ]
}

List markets

Response

{
  "count": 46,
  "markets": [
    {
      "slug": "usa-nyse-nasdaq",
      "name": "NYSE & Nasdaq",
      "market_key": "us",
      "total_listed": 8942
    }
    // ... use market_key as the {market} path segment
  ]
}

Partner keys

Partner keys are admin-minted B2B credentials with their own quotas and access control, independent of subscription tiers. They power framework-scoped integrations - for example a Catholic robo-advisor whose key only ever sees catholic_usccb verdicts.

Available scopes: allowed_markets (market slugs), allowed_endpoints (endpoint tags: screen, screen/history, screen/batch, screen/etf, screen/compare), allowed_frameworks (framework ids), plus custom daily limits, rolling 30-day monthly quotas, and per-endpoint cost weights.

Attestations

Mint machine-verifiable, HMAC-SHA256-signed compliance certificates from the current verdict — “as of DATE, TICKER was AAOIFI-compliant, purification Y/share”. Each certificate is stored permanently, addressable at an unguessable URL, and can be independently re-checked at any later date against the immutable snapshot written at mint time. Negative verdicts (questionable, non_compliant) are attestable too — a negative cert is still an audit-grade statement. insufficient_data is not (422).

Request example

curl -X POST "https://faithscreener.com/api/attest/us/AAPL?standard=shariah_aaoifi" \
  -H "X-API-Key: fsk_live_your_key"

Response

{
  "cert_id": "fsat_9f2c41d0a3b45e6f7a8b9c0d",
  "payload_version": 1,
  "ticker": "AAPL",
  "market": "us",
  "standard": "shariah_aaoifi",
  "verdict": "compliant",
  "score": null,
  "purification_per_share": 0.0412,
  "as_of": "2026-07-04T18:22:07Z",
  "minted_at": "2026-07-04T18:22:07Z",
  "snapshot_ref": { "source": "runtime", "day": "2026-07-04" },
  "key_id": "2026-07-a",
  "sig": "3f6a...c9",
  "company_name": "Apple Inc.",
  "issuer_type": "api_key",
  "verify_url": "https://faithscreener.com/api/attest/verify/fsat_9f2c41d0a3b45e6f7a8b9c0d",
  "cert_url": "https://faithscreener.com/attest/fsat_9f2c41d0a3b45e6f7a8b9c0d"
}

Response

{
  "cert_id": "fsat_9f2c41d0a3b45e6f7a8b9c0d",
  "status": "valid",
  "valid": true,
  "sig_valid": true,
  "snapshot_check": "match",
  "revoked": false,
  "revoked_at": null,
  "revocation_note": null,
  "checked_at": "2026-07-05T09:00:00Z",
  "attestation": { /* the full public cert incl. sig */ }
}

Every certificate also has a print-friendly public page at /attest/{cert_id} (unlisted, never indexed). Partner keys are provisioned for attestation with allowed_endpoints: ["attest"]. Authenticity is proven by the verify endpoint; the audit value comes from the snapshot cross-check against the 872k+ snapshot history — a claim, once issued, can be re-checked years later.

Code examples

Screen Apple (AAPL) and return only the Catholic USCCB and Christian BRI verdicts:

curl "https://faithscreener.com/api/screen/us/AAPL?framework=catholic_usccb,christian_bri" \
  -H "X-API-Key: fsk_live_your_key"

Rate limits

Rate limits are applied per API key on a rolling 24-hour window; partner keys can also carry a rolling 30-day monthly quota.

Quotas are charged in units: a single screen is 1 unit, a batch charges 1 unit per ticker, and a point-in-time (as_of) read is 2 units. There are no X-RateLimit response headers; exceeding a quota returns 429 with details in the body.

The Free tier does not include API access - keys are available from Pro upward. Partner quotas and cost weights are set per contract.

Error codes

All errors return a JSON body with a detail field. Some 403 and 429 responses carry a structured detail object with limits and an upgrade_url.

{
  "detail": "This API key is not provisioned for framework(s): shariah_aaoifi."
}