> ## Documentation Index > Fetch the complete documentation index at: https://docs.halal.sh/llms.txt > Use this file to discover all available pages before exploring further. # Get Financials > Returns the financial metrics extracted from the latest filings and the three calculated AAOIFI ratios. For per-metric provenance (accession numbers, XBRL tags, extraction strategies) use the Evidence Packet. ## OpenAPI ````yaml GET /instruments/{symbol}/financials openapi: 3.1.0 info: title: halal.sh API version: 1.0.0 description: > The halal.sh API provides Shariah compliance screening for public equities and ETFs, based on AAOIFI Shari'ah Standard No. 21. Unlike a black-box verdict, every determination exposes the individual screens, the financial ratios with their thresholds, the revenue breakdown, and the source filings behind each number. The Evidence Packet endpoint returns the full audit trail — accession numbers, XBRL tags, and extraction strategies — for compliance, reporting, and reproducibility. ## Conventions - **Base URL** — `https://api.halal.sh/v1` - **Authentication** — send your key in the `X-API-Key` header. - **Envelope** — every success response is `{ "data": …, "meta": … }`. Every error is `{ "error": { "code", "message" } }`. - **Ratios** — screen `value`, `threshold`, and `buffer` are decimals (`0.082` means 8.2%, `0.30` means 30%). Fields named `*percentage`, `purity.percentage`, and holding `weight` are whole-number percentages (`66.74` means 66.74%). Each field documents its unit. - **Status** — compliance status is always `compliant`, `non-compliant`, or `pending`. Treat unknown future values as `pending`. - **Money** — values are in the instrument's reporting currency (USD for US filers). contact: name: halal.sh API support url: https://halal.sh/developers email: api@halal.sh servers: - url: https://api.halal.sh/v1 description: Production security: - apiKey: [] tags: - name: Instruments description: Compliance, financials, evidence, history, and health for a single stock. - name: Screening description: Batch screening and search across the instrument universe. - name: ETFs description: Shariah purity and holdings breakdown for ETFs. - name: Methodology description: The screening methodology, its thresholds, and version. paths: /instruments/{symbol}/financials: get: tags: - Instruments summary: Get extracted financials description: | Returns the financial metrics extracted from the latest filings and the three calculated AAOIFI ratios. For per-metric provenance (accession numbers, XBRL tags, extraction strategies) use the Evidence Packet. operationId: getFinancials parameters: - $ref: '#/components/parameters/Symbol' responses: '200': description: Financial data content: application/json: schema: $ref: '#/components/schemas/FinancialsResponse' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/SandboxRestricted' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' components: parameters: Symbol: name: symbol in: path required: true description: Stock ticker symbol (e.g. AAPL, NVDA, MSFT). schema: type: string minLength: 1 maxLength: 10 example: AAPL schemas: FinancialsResponse: type: object properties: data: type: object properties: symbol: type: string example: NVDA name: type: string example: NVIDIA Corporation currency: type: string example: USD as_of: type: string format: date-time nullable: true filing_set_summary: type: string nullable: true example: 10-K(2026-02-25) + 10-Q(2026-05-20) metrics: type: object properties: total_revenue: type: number nullable: true total_assets: type: number nullable: true total_debt: type: number nullable: true cash_and_equivalents: type: number nullable: true marketable_securities: type: number nullable: true accounts_receivable: type: number nullable: true interest_income: type: number nullable: true market_cap: type: number nullable: true ratios: type: object properties: debt_to_market_cap: $ref: '#/components/schemas/FinancialScreen' nullable: true cash_to_market_cap: $ref: '#/components/schemas/FinancialScreen' nullable: true prohibited_revenue: $ref: '#/components/schemas/FinancialScreen' nullable: true meta: $ref: '#/components/schemas/Meta' FinancialScreen: type: object description: >- A financial-ratio screen — value, threshold, and pass/fail (or not_applicable when deferred to business activity). properties: result: $ref: '#/components/schemas/ScreenOutcome' value: type: number nullable: true description: The calculated ratio as a decimal (0.082 = 8.2%). example: 0.020616 threshold: type: number description: The AAOIFI threshold as a decimal (0.30 = 30%). example: 0.3 operator: type: string description: Comparison operator. AAOIFI uses `<=` for all financial screens. example: <= buffer: type: number nullable: true description: >- Distance from the threshold in percentage points. Negative when failing. example: 27.9384 Meta: type: object properties: request_id: type: string description: Unique ID for this request. Include it in support requests. example: req_abc123 as_of: type: string format: date-time description: When this response was generated. methodology: type: string description: Methodology used, as `id@version`. Present on compliance responses. example: aaoifi-ss21@2026.1 ErrorResponse: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string enum: - bad_request - unauthorized - sandbox_restricted - not_found - rate_limit_exceeded - service_unavailable - internal_error example: not_found message: type: string example: No instrument found for symbol 'XYZ'. retry_after: type: integer description: Seconds until the rate limit resets (only on 429). meta: $ref: '#/components/schemas/Meta' ScreenOutcome: type: string description: > `pass` / `fail`, or `not_applicable` — used by the `prohibited_revenue` screen when the company's core business is non-permissible. AAOIFI's prohibited-income screen (Rule 3/4/4) applies to companies whose core business is permissible; when the core business is itself non-permissible (bank, casino, etc.), the income screen is N/A — the `business_activity` screen decides — and `value`/`buffer` are `null`. enum: - pass - fail - not_applicable responses: Unauthorized: description: Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: unauthorized message: Invalid or revoked API key. meta: request_id: req_abc123 SandboxRestricted: description: Symbol or feature not available on the sandbox plan content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: sandbox_restricted message: >- Symbol 'TSLA' is not available in the sandbox. Upgrade to Plus for full access. meta: request_id: req_abc123 NotFound: description: Resource not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: not_found message: No instrument found for symbol 'XYZ'. meta: request_id: req_abc123 RateLimited: description: Rate limit exceeded headers: X-RateLimit-Limit: schema: type: integer description: Maximum requests allowed in the current daily window. X-RateLimit-Remaining: schema: type: integer description: Requests remaining in the current daily window. X-RateLimit-Reset: schema: type: string format: date-time description: ISO 8601 timestamp when the daily window resets (midnight UTC). Retry-After: schema: type: integer description: Seconds to wait before retrying. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: rate_limit_exceeded message: Daily request limit (100) exceeded. Resets at midnight UTC. retry_after: 3600 meta: request_id: req_abc123 securitySchemes: apiKey: type: apiKey in: header name: X-API-Key ````