> ## 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 Evidence Packet > Returns a complete compliance audit bundle: the determination, every screen with its calculation and source filings (accession number, XBRL tags, extraction strategy, raw values), a confidence breakdown, and stability metrics. Built for audit, reporting, and reproducibility. Returns `404` while the stock's analysis is still `pending`. ## OpenAPI ````yaml GET /instruments/{symbol}/evidence 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}/evidence: get: tags: - Instruments summary: Get an Evidence Packet description: | Returns a complete compliance audit bundle: the determination, every screen with its calculation and source filings (accession number, XBRL tags, extraction strategy, raw values), a confidence breakdown, and stability metrics. Built for audit, reporting, and reproducibility. Returns `404` while the stock's analysis is still `pending`. operationId: getEvidence parameters: - $ref: '#/components/parameters/Symbol' responses: '200': description: Evidence Packet content: application/json: schema: $ref: '#/components/schemas/EvidencePacketResponse' '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: EvidencePacketResponse: type: object properties: data: $ref: '#/components/schemas/EvidencePacket' meta: $ref: '#/components/schemas/Meta' EvidencePacket: type: object description: Complete compliance audit bundle with full provenance. properties: instrument: type: object properties: symbol: type: string name: type: string exchange: type: string nullable: true as_of: type: string format: date period: type: string example: FY2026 currency: type: string example: USD methodology: type: object properties: id: type: string example: aaoifi-ss21 version: type: string example: '2026.1' name: type: string example: AAOIFI Shariah Standard No. 21 determination: type: object properties: status: $ref: '#/components/schemas/ComplianceStatus' confidence: type: number reason_codes: type: array items: type: string example: - all_screens_pass - high_data_quality purification: $ref: '#/components/schemas/Purification' screens: type: array description: | One entry per screen. Business-activity screens carry a `detail` object; financial-ratio screens carry a `metric` object with the numerator/denominator breakdown. items: $ref: '#/components/schemas/EvidenceScreen' confidence_detail: type: object properties: score: type: number base_confidence: type: number extraction_strategies_used: type: array items: type: string fallbacks_used: type: array items: type: string penalties: type: array items: $ref: '#/components/schemas/ConfidenceAdjustment' boosts: type: array items: $ref: '#/components/schemas/ConfidenceAdjustment' stability: $ref: '#/components/schemas/EvidenceStability' disclosures: type: array items: type: string 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' ComplianceStatus: type: string enum: - compliant - non-compliant - pending description: | Compliance determination. `pending` means the instrument has not been analysed yet. This enum may gain values in future; treat any unknown value as `pending`. Purification: type: object properties: required: type: boolean example: true percentage: type: number nullable: true description: >- Percentage of dividends to purify (prohibited revenue ÷ total revenue). example: 1.012 amount_per_1000: type: number nullable: true description: >- Amount to purify per 1,000 units of dividends received (percentage × 10). example: 10.12 EvidenceScreen: type: object properties: name: type: string description: >- `business_activity`, `debt_to_market_cap`, `cash_to_market_cap`, or `prohibited_revenue`. example: debt_to_market_cap result: $ref: '#/components/schemas/ScreenOutcome' detail: type: object description: Present only for the business_activity screen. properties: primary_activities: type: array items: type: string prohibited_activities: type: array items: type: string activity_compliance: type: string enum: - permissible - non-permissible concerns: type: array items: type: string metric: type: object description: Present only for financial-ratio screens. properties: value: type: number nullable: true description: > Computed ratio (decimal). `null` when the ratio is undefined or does not apply — either a pre-revenue issuer earning interest income on $0 operating revenue, or the `prohibited_revenue` screen on a company whose core business is non-permissible (the income screen is N/A and `result` is `not_applicable`; the `business_activity` screen decides). See `note` for which. `numerator`/`denominator` are still populated in both cases. note: type: string description: >- Present only when `value` is `null`; plain-language explanation of why the ratio is undefined. threshold: type: number operator: type: string example: <= formula: type: string example: total_interest_bearing_debt / market_cap numerator: type: object properties: value: type: number label: type: string components: type: object additionalProperties: true denominator: type: object properties: value: type: number label: type: string example: Spot Market Cap method: type: string description: '`spot` or `12-month-avg`.' example: spot months_used: type: integer description: >- Months averaged for a `12-month-avg` market-cap denominator; absent for a `spot` denominator. sources: type: array items: $ref: '#/components/schemas/FilingSource' ConfidenceAdjustment: type: object properties: type: type: string impact: type: number reason: type: string EvidenceStability: type: object properties: quarters_compliant: type: integer nullable: true quarters_total: type: integer nullable: true flip_rate: type: number nullable: true closest_threshold: type: object properties: screen: type: string example: prohibited_revenue current_distance: type: number example: 0.041 trend: type: string enum: - stable - narrowing - widening stability_rating: type: string enum: - stable - watch - borderline stability_drivers: type: array items: type: object properties: code: type: string message: type: string severity: type: string enum: - info - warning - critical 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 FilingSource: type: object properties: filing_type: type: string example: 10-Q accession_number: type: string example: 0001045810-26-000052 period_end: type: string format: date filing_date: type: string format: date xbrl_tags: type: array items: type: string example: - us-gaap:LongTermDebt extraction_strategy: type: string example: PrimaryFields raw_values: type: object additionalProperties: true 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 ````