API Documentation

Everything you need to integrate FinScan into your application.

Authentication

All API requests require an API key sent via the X-API-Key header.

http

GET /v1/scan/AAPL HTTP/1.1
Host: finscan-production.up.railway.app
X-API-Key: your_api_key_here
Accept: application/json

Get your API key by subscribing to a plan on the pricing page.

Scan Endpoint

GET/v1/scan/{ticker}

Returns a complete financial risk assessment for the given stock ticker, including composite risk score, Beneish M-Score, Altman Z-Score, Piotroski F-Score, accrual analysis, and red flags.

Parameters

Parameter	Type	Description
ticker	string	Stock ticker symbol (e.g., AAPL, MSFT)

Example Request

bash

curl -X GET "https://finscan-production.up.railway.app/v1/scan/AAPL" \
  -H "X-API-Key: your_api_key_here" \
  -H "Accept: application/json"

Response Format

Successful responses return a JSON object with the following structure:

json

{
  "ticker": "AAPL",
  "companyName": "Apple Inc.",
  "sector": "Technology",
  "scanDate": "2026-02-20",
  "compositeRisk": {
    "score": 23.5,
    "riskLevel": "LOW",
    "summary": "Low overall risk. Financial indicators are healthy."
  },
  "beneishScore": {
    "mScore": -2.85,
    "interpretation": "Score below -2.22 threshold — unlikely manipulator.",
    "isLikelyManipulator": false,
    "variables": { "DSRI": 1.02, "GMI": 0.98, "AQI": 1.01, "SGI": 1.15, "DEPI": 0.95, "SGAI": 1.03, "LVGI": 0.97, "TATA": -0.04 }
  },
  "altmanScore": {
    "zScore": 5.12,
    "zone": "SAFE",
    "interpretation": "Z-Score above 2.99 — safe zone, low bankruptcy risk.",
    "components": { "X1": 0.15, "X2": 0.85, "X3": 0.28, "X4": 6.12, "X5": 0.72 }
  },
  "piotroskiScore": {
    "fScore": 7,
    "maxScore": 9,
    "interpretation": "Strong financial position (7/9).",
    "criteria": {
      "positiveNetIncome": true,
      "positiveOperatingCashFlow": true,
      "increasingROA": true,
      "cashFlowExceedsNetIncome": true,
      "decreasingLeverage": false,
      "increasingCurrentRatio": true,
      "noNewSharesIssued": true,
      "increasingGrossMargin": false,
      "increasingAssetTurnover": true
    }
  },
  "accrualAnalysis": {
    "sloanRatio": -0.03,
    "cashToIncomeRatio": 1.25,
    "earningsQuality": "HIGH",
    "interpretation": "Cash flows support reported earnings."
  },
  "redFlags": [],
  "dataQuality": {
    "completeness": 1.0,
    "periodsAvailable": 5,
    "missingFields": []
  }
}

Field Descriptions

Field	Description
compositeRisk.score	Overall risk score (0-100). Lower is safer.
beneishScore.mScore	Beneish M-Score. Above -2.22 indicates likely manipulation.
altmanScore.zScore	Altman Z-Score. Below 1.81 = distress, above 2.99 = safe.
piotroskiScore.fScore	Piotroski F-Score (0-9). Higher indicates stronger financials.
accrualAnalysis	Earnings quality metrics based on cash flow vs. reported income.
redFlags	Array of detected anomalies with severity, category, and detail.
dataQuality	Completeness indicator. Partial data returns results with a lower completeness score.

Financial Models

Beneish M-Score (8-variable)

Detects earnings manipulation probability.

Threshold: Score > -2.22 indicates likely manipulation.

Altman Z-Score

Predicts bankruptcy probability within 2 years.

Threshold: < 1.81 distress, 1.81-2.99 grey zone, > 2.99 safe.

Piotroski F-Score

Measures overall financial strength using 9 binary criteria.

Threshold: 0-3 weak, 4-6 moderate, 7-9 strong.

Sloan Accrual Ratio

Measures earnings quality by comparing accruals to total assets.

Threshold: High accruals relative to assets suggest lower earnings quality.

Cash-to-Income Ratio

Compares operating cash flow to net income.

Threshold: Ratio < 1.0 means earnings are not backed by cash flow.

Composite Risk Score

Weighted combination of all models into a single 0-100 score.

Threshold: 0-25 low, 26-50 moderate, 51-75 elevated, 76-100 high risk.

Error Codes

Code	Meaning	Resolution
400	Bad Request	Check your request parameters.
401	Unauthorized	Verify your X-API-Key header.
404	Not Found	The ticker symbol was not found.
429	Rate Limited	You've exceeded your plan's scan limit. Upgrade or wait.
500	Server Error	An internal error occurred. Retry or contact support.

Rate Limits

Rate limits are enforced per API key on a monthly billing cycle.

Plan	Monthly Scans	Price
Free	10	$0
Starter	100	$29/mo
Professional	500	$79/mo
Enterprise	Unlimited	$199/mo

Code Examples

bash

curl -X GET "https://finscan-production.up.railway.app/v1/scan/AAPL" \
  -H "X-API-Key: your_api_key_here" \
  -H "Accept: application/json"