The usual advice for choosing a stock screener API starts with filter counts, market coverage, and how quickly you can display a pass badge. That's the wrong starting point for an investment product. A pass or fail isn't a product if your team can't explain it when a user asks why another app reached the opposite conclusion.

Start with decision lineage: the record connecting a verdict to its rules, denominator, financial inputs, and source filing. Then design requests, reports, and notifications around that record. Your integration needs to answer both what qualifies today and what changed in a portfolio yesterday.

Table of Contents

Response Fields a Stock Screener API Should Return

Design the JSON object your client will store before designing the badge it will display. A response containing only a ticker and verdict can populate a watchlist, but it can't support a disputed classification, a filing correction, or a compliance review.

Treat the stored object as a decision record, not a disposable cache entry. Group it into identity, time, result, provenance, and quality. Keep those blocks together so an exported result remains understandable without another request against a potentially changed database.

Start with the calculation

Consider a hypothetical debt test, not a reported company result. Interest-bearing debt is 42.1 billion dollars, and the applicable twelve-quarter average market capitalization is 180 billion dollars. Dividing the former by the latter produces a rounded ratio of 23.4%, below an illustrative 30% cutoff.

Suppose the figures belong to a period ending September 30, 2025, and the filing was published November 1, 2025. The response must preserve both dates, because the period describes the accounts while the filing date helps establish when those accounts became available. Neither date substitutes for the calculation timestamp.

The SEC's EDGAR API documentation provides a useful reference pattern: company-level XBRL facts retain taxonomy, units, periods, and filing contexts rather than flattening each concept into a context-free number. Follow that pattern even when you normalize the result into a simpler application schema.

Stock screener API response fields

The calculation cells below continue the hypothetical example. AAPL illustrates a request symbol only; these are not Apple's financial figures or verdict. Descriptive placeholders identify fields your production response must populate from an actual record.

Field Block Meaning Example
ticker Identity Listing symbol, not the only key AAPL
stable_id Identity ISIN or other durable identifier Provider's permanent security identifier
exchange Identity Venue of this listing Nasdaq
currency Identity Currency as reported, not a silent conversion USD
as_of Time When this payload was calculated Calculation timestamp in UTC
period_end Time Fiscal period the figures belong to Hypothetical 2025-09-30
filing_date Time Date of the source filing Hypothetical 2025-11-01
methodology_version Time Named rulebook and version Archived rulebook release identifier
verdict Result Classification under that version pass
threshold Result Cutoff the rule applied Illustrative 30%
ratio Result Computed test result Illustrative 23.4%, rounded
numerator Result Top of the ratio Illustrative debt of 42.1
denominator Result Base the standard divides by Illustrative twelve-quarter average market cap of 180
line_item Provenance Concept or extracted account Interest-bearing debt
unit Provenance Scale and currency of the figure USD billions
accession Provenance Filing identifier Accession of the source filing
restatement_flag Provenance Whether a later filing replaced the fact false
coverage Quality Share of required inputs present Present required inputs divided by all required inputs
value_or_null Quality Null if undisclosed, never a guessed zero null

The provenance block also needs the taxonomy or rule name, source document, and extraction reference. Quality should distinguish input completeness from freshness and confidence. A complete set of old accounts isn't fresh, and a confident extraction doesn't prove the selected accounting concept is appropriate.

Acceptance rule: Reject a decision endpoint that can't supply the threshold, denominator definition, and source evidence together.

Use null when a figure wasn't disclosed, and preserve a reported zero as zero. If you convert currency, retain the reported amount and currency alongside the converted value, conversion date, and FX source. Otherwise, your client can reproduce the arithmetic but still fail to reproduce the decision.

Filter Parameters and Single Security Requests

A holding detail page and a discovery screen need different request shapes. The detail page starts with a known security; the discovery screen starts with conditions and asks which securities satisfy them.

For a single security, a path such as /compliance/AAPL is appropriate. Use uppercase ticker inputs where the contract requires them, and resolve the response to a stable identifier before storing it. Paths such as /basic-report/AAPL, /full-report/AAPL, and /methodology/AAPL represent progressively different questions, not interchangeable copies of the same response.

Separate lookup from universe search

A universe endpoint should apply filters on the server. Don't build an interactive browse screen by issuing a detail request for every ticker whenever someone changes a dropdown. That approach couples page latency to universe size and makes partial failures difficult to distinguish from genuine exclusions.

For an illustrative contract, express a request with country=US, methodology=AAOIFI, debt_ratio_max=0.30, coverage_min=0.90, sort=market_cap, and limit=100. These are hypothetical parameter names and test settings, not a claim about an available stock-universe endpoint or a methodology's complete rules.

The important detail is the operator. Equality suits a verdict or venue, lists suit multiple countries, and ranges suit market capitalization, fees, or assets under management. Publish whether combined filters mean intersection or union, and reject unsupported operators rather than ignoring them.

Screener filters and how they fail

Filter Parameter shape Example Failure if ignored
Verdict Equality pass Mixing rulebooks in one unlabeled pass
Rulebook Equality AAOIFI Treating distinct standards as an identical debt test
Country or venue List US,GB,CA Assuming a ticker is unique across markets
Sector List Banks excluded Filtering a label instead of revenue activity
Market cap Range plus currency Explicit USD-denominated range Comparing incompatible currency scales
Debt ratio Maximum Illustrative 0.30 Applying the cap to assets when the rule uses market cap
Impermissible revenue Maximum Caller-selected cap under the named rule Using a missing segment as zero
Coverage Minimum Illustrative 0.90 Showing a pass despite inadequate assessed exposure
As of Date Requested archived snapshot date Replacing historical results with today's verdict
Page Cursor and limit Returned cursor with illustrative limit 100 Offset pages skipping rows after a rebuild

Define coverage's denominator before exposing the filter. For a fund, it might represent assessed portfolio weight; for a company report, it might describe required financial inputs. Those meanings shouldn't share an undocumented parameter merely because both produce a fraction.

A market-cap range also needs an explicit currency and scale. A bare minimum value leaves the caller guessing whether the service compares normalized amounts or listing-local values.

Use server-side screening to retrieve identifiers, then fetch detailed evidence for names a person opens or a portfolio action requires. Keep a downloadable country-level ticker inventory alongside discovery so your client can distinguish an excluded security from one outside the supported universe.

Endpoint Families for Screens Reports and Events

Don't hang the whole application off the endpoint that returns the shortest response. Organize the interface around the job each screen performs, and give expensive evidence requests a different retrieval and caching policy from compact classifications.

The main separation is between screens, reports, and events. Universe discovery and fund analysis then build on those responsibilities rather than turning a badge endpoint into an all-purpose service.

This diagram shows the boundary between displaying a result, explaining it, and distributing a change.

A diagram illustrating three endpoint families for stock screener APIs: screens, reports, and events.

Match each family to a product surface

Family Application surface Return or perform Must not replace
Security screen Holding badge or watchlist Headline verdict and key ratios Evidence report
Evidence report Explain-result screen Screening grid, extracted figures, revenue sources Cross-rulebook comparison
Methodology view Standards comparison panel Parallel outcomes with their own rules A universal compliance label
Universe discovery Search and browse Searchable identifiers and supported filters Per-security evidence
Fund analysis Fund detail and portfolio review Holdings-weighted assessment A stock classification attached to a fund name
Events Alerts and restriction workflows Status changes and rule updates Authoritative record retrieval

A compact security response should be cheap to display, but compact doesn't mean context-free. Keep the decision reference available so the client can retrieve the exact evidence behind the badge rather than whichever report happens to be current.

An evidence report serves a different reader. Someone inspecting an exclusion needs the account selection, revenue sources, and failed checks, not merely a longer explanation string. A methodology view serves the support ticket where another application disagrees, so it must preserve separate outcomes instead of blending standards into a consensus.

Keep fund logic and delivery separate

For fund analysis, assess constituent exposure by weight rather than by the fund's name. Rebuild the fund result after the underlying stock assessments, and retain an unrated outcome when coverage is insufficient and no breach is already established. A holdings table is necessary evidence, but it isn't itself a completed fund assessment.

  • Evidence ownership: Put calculation lineage in reports and methodology responses.
  • Listing ownership: Put venue, currency, and identifier mapping in security metadata.
  • Delivery ownership: Put event identity and delivery behavior in the event contract.

Use the screening endpoint quickstart to map initial calls to application screens before implementing the whole surface. Keep quote retrieval outside that map: a classification response can be complete without a last-trade price.

Decision Lineage Behind a Pass or Fail

The support ticket is predictable: a user's holding passes in your application and fails elsewhere. Returning the same badge again won't resolve it. Your team needs to compare the decisions that produced both labels.

Begin with rulebook version, denominator definition, and averaging window. Those stored choices explain disagreements that otherwise look like bad data. Then inspect source periods and extracted figures to determine whether the applications evaluated the same information.

The decision record should make each of those choices inspectable.

A diagram illustrating the five core components of a decision verdict, including methodology, denominator, averaging, source, and replay.

Explain differences without inventing a universal label

A debt-to-market-cap calculation and a debt-to-assets calculation answer different questions. Even if their cutoffs look alike, their verdicts needn't match. An averaging window must also be explicit: averaging quarterly observations and averaging monthly observations aren't interchangeable implementations.

Business activity can decide the result before a financial ratio matters. Under a methodology that excludes conventional banking, a conventional bank doesn't become eligible because its debt calculation looks acceptable. Preserve the rule order and the decisive exclusion, not just a list of ratios.

Return separate outcomes for AAOIFI, Dow Jones, FTSE, MSCI, and S&P, with the applicable version and calculation basis attached to each. Don't resolve a methodology conflict by selecting whichever result looks most favorable. The product needs an explicit policy for which standard governs its users.

A disagreement is explainable only when both results identify what was measured, under which rules, using which information.

Archive changes as portfolio events

A study of ETF holdings from May 2020 through December 2024 found simulated rule breaches were associated with subsequent portfolio sales, with probabilities of 4.9% versus 1.5% for one ETF and 8.7% versus 3.5% for another. That's an association in the studied holdings, not a promise that every breach triggers a sale. It does justify treating a status change as an input to portfolio review rather than a cosmetic refresh.

Append verdict records instead of overwriting them. When a restatement changes a source fact, create a new calculation linked to the superseded record and retain the reason for recomputation. Distinguish the result originally available to users from a result reconstructed later using corrected accounts.

Our filing trail uses SEC EDGAR 10-K and 10-Q filings for US tickers, Companies House annual accounts for UK tickers, and SEC 40-F filings plus company investor relations reports for Canadian tickers. Preserve the actual filing reference, not merely the name of the repository.

The following video provides additional context for reviewing screening decisions.

Connect archived decisions to the verdict-change documentation so your application can associate a notification with the relevant change record. A status change should initiate the product's review policy, not an undocumented automatic sale.

The minimum archive row is ticker, stable identifier, as_of, methodology version, verdict, denominator, inputs, and filing identifier. Add a decision identifier and supersession relationship so a compliance officer can replay the calculation without reconstructing its history from application logs.

Identifiers Currencies and Missing Fundamentals

A long country list can hide a weak integration. If your client can't identify the listing, interpret its units, or distinguish an absent disclosure from an extracted value, additional markets create additional opportunities for incorrect comparisons.

The DataCamp guide to selecting a stock-market data API identifies corporate actions, ticker changes, missing records, schema consistency, errors, and rate limits as practical selection concerns. Treat those as acceptance criteria, not cleanup tasks to schedule after launch.

Model the issuer and the listing separately

Maintain an identifier map connecting the issuer, security, listing, and ticker history. ISIN or CUSIP can help identify a security, but your model still needs the exchange-specific listing and effective dates for symbol changes. Never make a ticker string the permanent primary key of a financial decision.

A response may represent the primary listing rather than every trading line. Don't assume a secondary listing inherits identical quote units, identifiers, or availability. Equally, don't collapse distinct share classes into one security just because they belong to the same issuer.

The data model needs to preserve those boundaries across markets.

A hand-drawn illustration explaining a Stock Screener API and how it consolidates data across multiple international markets.

Currency handling needs both a currency code and a quote scale. As a hypothetical unit-conversion example, a quote of 250 GBp represents 2.50 pounds, not 250 pounds. An integration that mistakes pence for pounds can produce a plausible-looking but incorrect market-cap comparison.

Keep conversion policy consistent across the calculation. Don't combine a filing amount converted at one date with a market-based denominator converted under an undocumented alternative policy. Store the exchange rate as well as its date and source so you can inspect rounding and conversion choices.

Quarantine incomplete changes

Corporate-action records can arrive before all the information required to apply them. Stage incomplete records rather than updating identifier mappings or price adjustments before the required effective date and security reference are available. Record why the change is pending so operations staff can distinguish delay from processing failure.

Missing fundamentals require the same discipline. Don't average an absent reporting period as if the company disclosed no debt, and don't mark an aggregate assessment complete merely because the calculation skipped unclassified holdings.

  • Debt completeness: Measure which eligible names have usable debt facts.
  • Revenue completeness: Track whether business-segment disclosures support the activity screen.
  • Filing freshness: Evaluate age against an explicitly stated reporting policy.
  • Mapping integrity: Flag unresolved identifiers and unexpected share-class merges.

Avoid compressing all of that into one coverage slogan. The engineering team needs field-level diagnostics, while the user needs a clear explanation of what remains unknown.

Before accepting global coverage, select a small cross-market sample from your own book. Confirm the listing, inspect quote units, count absent fundamentals, and check whether separate share classes remain separate. That exercise tests comparability, not merely whether a symbol returns a response.

Price History for Backtests Only

Keep the verdict archive and price archive separate. A live classification and a historical performance simulation need different inputs, and a price move isn't evidence that a compliance decision changed.

The workflow should distinguish the current observation from the archives needed for testing.

A diagram illustrating the three components of price history for backtests including current observation, verdict archive, and price archive.

Align information availability before returns

Nasdaq Data Link describes U.S. Equity Daily History extending back to January 2014, with open, high, low, close, and volume data covering Nasdaq, NYSE, NYSE American, BATS, NYSE Arca, NYSE MKT, and OTC markets. Its adjusted and unadjusted series serve different purposes.

  • Use adjusted history: Select split- and dividend-adjusted series for return, momentum, drawdown, and moving-average calculations.
  • Retain raw observations: Keep unadjusted prices when reconstructing the quoted price at the time.
  • Keep failed and delisted names: Don't construct the historical universe from today's survivors.
  • Join by availability: Associate each trading date with the verdict available then, including its methodology version and inputs hash.

A backtest must not use a filing before its publication or a corrected decision before the correction became available. Keep retrospective recalculations distinguishable from historically available verdicts.

A classification integration doesn't need a streaming quote feed unless the surrounding product also supports a trading use case. Add market data for that separate requirement, not to make the screening payload look more complete.

Pagination Errors and Webhook Contracts

Portfolio restrictions shouldn't depend on undocumented response behavior. Publish a formal contract that defines schemas, filter serialization, pagination, failures, and event delivery before another team builds operational controls around the API.

The OpenAPI specification provides structures for request and response schemas, reusable components, and provider-initiated webhooks. Use those structures to describe actual behavior, including optional fields and unavailable results, rather than documenting only the successful example.

Make replay deterministic

Every result should retain its as_of, methodology version, calculation denominator, and effective filing reference. Require stable security identifiers in events so a symbol change doesn't break the association with a holding. Document whether as_of selects an archived snapshot or merely limits eligible source information.

Prefer snapshot-bound cursor pagination over offset-only pagination. An offset can shift when a nightly rebuild adds or removes rows; a cursor alone also isn't sufficient unless its relationship to the snapshot is defined. Specify token expiry and how a client restarts an interrupted export.

Screener API error classes

The following machine-readable codes are proposed contract labels, not claims about a particular implementation.

Class Client action Do not
Authentication, authentication_failed Refresh or replace credentials as appropriate Retry the body blindly
Rate limit, rate_limited Follow retry guidance, back off, and resume the cursor Restart the entire export
Invalid parameter, invalid_parameter Fix the filter or ticker case Treat the response as an empty universe
Unavailable data, data_unavailable Show unknown and preserve nulls Store a pass or a zero
Upstream source, upstream_source_failed Retry later and retain the last good as_of Overwrite history with an error

Include a request identifier, retryability indicator, and actionable detail in error responses. Authentication failures and source outages require different owners and different recovery behavior. Collapsing both into a generic server error makes automated recovery unreliable.

Rate limits belong in this contract, not in the filter catalog. State how the client receives retry guidance and whether a cursor remains valid while it waits. Otherwise, a client can obey the backoff instruction and still lose its place.

Treat notifications as delivery, not evidence

For verdict-change delivery, require a stable event identifier and a signature. Verify the signature against the original request body, persist the event durably, acknowledge promptly, and process it asynchronously. Deduplicate before issuing user alerts or initiating portfolio workflows.

Operational rule: A webhook tells your application to inspect a change. It doesn't replace the authoritative decision record.

After receiving an event, retrieve the authoritative record and reconcile its version with local state. Handle delayed or out-of-order events without moving a holding back to an older verdict. Define retry and recovery behavior alongside the webhook integration contract.

Our screening data is automated, depends on company-reported and third-party inputs, isn't real-time, and may be incomplete or incorrect. Reflect that policy in the interface by exposing provenance and uncertainty instead of presenting every label as an unquestionable fact.

The acceptance test is concrete: identical requests against the same archived decision context return the same verdict, and replaying an event doesn't alert the user again.

Test a Sample Book Before You Integrate

The deciding factor isn't the longest coverage list. It's whether securities your users hold return usable evidence, coherent methodology comparisons, and explicit unknowns when disclosures don't support a calculation.

Use a representative sample book rather than a collection of easy large-cap names. Include a conventional bank, an industrial company near a screening boundary, a fund, and securities with different listing and reporting characteristics.

Run an evidence-first acceptance test

  1. Export existing holdings. Keep the original ticker, venue, currency, and internal holding identifier so you can detect incorrect resolution rather than merely successful responses.
  2. Retrieve the verdict and evidence. Test uppercase symbols such as AAPL, then inspect the full report rather than accepting a successful badge response as proof of completeness.
  3. Compare methodology outcomes. Confirm that differing verdicts can be explained by the governing rule, denominator, or source facts. An absent field isn't an acceptable explanation disguised as a standards difference.
  4. Exercise the alert workflow. Replay notifications and check deduplication, delayed processing, and reconciliation with the authoritative record.

For production-like testing, GoReplay's guide explains how to validate endpoints with real traffic. Use representative request patterns without copying customer credentials or sensitive portfolio details into an uncontrolled test environment.

Keep the provider only if the evidence survives

Akinda is a practical candidate when the requirement is Shariah screening rather than prices. Our REST API runs over HTTPS and returns JSON through five stock endpoints and six ETF endpoints, with AAOIFI primary among five methodologies across four markets. It doesn't include real-time stock prices.

The stock calls cover compliance, basic report, full report, methodology, and verdict changes. ETF calls cover details, holdings, screening, list, screener, and comparison. The same JSON shape supports a founder's halal portfolio application and a bank's multi-desk integration.

Use the documentation and request playground with your sample book, then inspect the returned evidence against your storage requirements. Keep the integration only if the fields needed to explain a decision are populated, missing information stays visible, and your team can reconstruct the result without guessing.

Akinda offers Shariah screening for stocks and ETFs, with reports and methodology comparisons that help developers explain results rather than display an unexplained badge. Visit Akinda to test your sample holdings in the documentation and playground, then verify the denominators, filing references, and unknown values before connecting portfolio actions.