REST API

FaithScreener API

Screen any stock against 10 faith-based compliance frameworks via REST API. 124,000+ stocks. 42 markets. JSON responses.

Get API Access Read the Docs

Base URL: https://api.faithscreener.com

Authentication

All API requests require a Bearer token in the Authorization header.

Authorization: Bearer fs_your_api_key

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

Screen a single stock

GET/api/v1/screen/{ticker}

Screen a single stock against all or selected compliance frameworks. Returns verdicts, financial ratios, and purification data.

Query Parameters

market	string	Two-letter market code. Defaults to US.
frameworks	string	Comma-separated list of framework IDs to evaluate. Omit to screen against all 10.

Response

200 OK

{
  "ticker": "AAPL",
  "company": "Apple Inc.",
  "market": "US",
  "exchange": "NASDAQ",
  "verdicts": {
    "aaoifi": {
      "status": "COMPLIANT",
      "details": {
        "debt_ratio": 0.32,
        "interest_income_ratio": 0.004,
        "impermissible_revenue_ratio": 0.0
      }
    },
    "sp_shariah": {
      "status": "COMPLIANT",
      "details": { /* ... */ }
    }
  },
  "financials": {
    "market_cap": 3200000000000,
    "total_debt": 108000000000,
    "total_assets": 352000000000
  },
  "purification": {
    "per_share": 0.042,
    "percentage": 0.38
  },
  "screened_at": "2026-04-11T14:30:00Z"
}

Search companies

GET/api/v1/search

Search for companies by name or ticker symbol. Returns up to 20 matches.

Query Parameters

q*	string	Search query. Matches against ticker symbols and company names.
market	string	Filter results to a specific market. Omit to search all markets.

Response

200 OK

[
  {
    "ticker": "AAPL",
    "name": "Apple Inc.",
    "market": "US",
    "exchange": "NASDAQ"
  },
  {
    "ticker": "AAPJ.L",
    "name": "AAP Industries PLC",
    "market": "GB",
    "exchange": "LSE"
  }
]

List frameworks

GET/api/v1/frameworks

List all supported compliance frameworks with their IDs, full names, and descriptions.

Response

200 OK

[
  {
    "id": "aaoifi",
    "name": "AAOIFI Shariah Standard",
    "description": "Accounting and Auditing Organization for Islamic Financial Institutions standard.",
    "category": "islamic"
  },
  {
    "id": "bri",
    "name": "Biblically Responsible Investing",
    "description": "Christian values-based framework filtering companies by moral and ethical criteria.",
    "category": "christian"
  }
  // ... 8 more frameworks
]

Bulk screening

POST/api/v1/screen/bulk

Screen multiple tickers in a single request. Up to 100 tickers per call.

Request Body

tickers*	string[]	Array of ticker symbols. Maximum 100 per request.
market	string	Market code. Defaults to US.
frameworks	string[]	Array of framework IDs. Omit to screen all.

Request example

curl -X POST "https://api.faithscreener.com/api/v1/screen/bulk" \
  -H "Authorization: Bearer fs_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"tickers":["AAPL","MSFT","TSLA"],"market":"US","frameworks":["aaoifi","sp_shariah"]}'

Returns an array of screening result objects, one per ticker. Each object follows the same schema as the single-screen endpoint.

List markets

GET/api/v1/markets

List all 42 supported markets with their codes, names, and stock counts.

Response

200 OK

[
  {
    "code": "US",
    "name": "United States",
    "stock_count": 8942,
    "exchanges": ["NYSE", "NASDAQ", "AMEX"]
  },
  {
    "code": "GB",
    "name": "United Kingdom",
    "stock_count": 3215,
    "exchanges": ["LSE"]
  }
  // ... 40 more markets
]

Code examples

Screen Apple (AAPL) against AAOIFI and S&P Shariah frameworks:

curl -X GET "https://api.faithscreener.com/api/v1/screen/AAPL?frameworks=aaoifi,sp_shariah" \
  -H "Authorization: Bearer fs_your_api_key"

Rate limits

Rate limits are applied per API key on a rolling 24-hour window. Current usage and limit are returned in response headers.

X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4832
X-RateLimit-Reset: 1718294400

Plan	Daily Limit	Bulk Max
Free	10	--
Pro	100	10
Basic API	5,000	100
Institutional	50,000	100

Error codes

All errors return a JSON body with error and message fields.

Status	Error	Description
401	unauthorized	Missing or invalid API key.
403	rate_limit_exceeded	Daily rate limit exceeded. Upgrade your plan or wait for the reset window.
404	not_found	Ticker not found in the specified market.
422	invalid_params	Invalid query parameter or request body. Check the message field for details.
500	server_error	Internal server error. Retry after a moment or contact support.

Example error response

{
  "error": "not_found",
  "message": "Ticker 'XYZ123' not found in market 'US'."
}

Ready to integrate?

Create an account and get your API key in under a minute.

Create Free Account View Pricing