> ## 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 Compliance

> Returns the full AAOIFI Standard 21 determination for a stock: the
business-activity screen, all three financial-ratio screens with their
thresholds, the revenue breakdown, purification, and a stability signal.

If the stock has not been analysed yet, `determination.status` is
`pending` and `screens`, `revenue`, `purification`, `stability`, and
`filing` are `null`.




## OpenAPI

````yaml GET /instruments/{symbol}/compliance
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}/compliance:
    get:
      tags:
        - Instruments
      summary: Get compliance screening
      description: |
        Returns the full AAOIFI Standard 21 determination for a stock: the
        business-activity screen, all three financial-ratio screens with their
        thresholds, the revenue breakdown, purification, and a stability signal.

        If the stock has not been analysed yet, `determination.status` is
        `pending` and `screens`, `revenue`, `purification`, `stability`, and
        `filing` are `null`.
      operationId: getCompliance
      parameters:
        - $ref: '#/components/parameters/Symbol'
      responses:
        '200':
          description: Compliance determination
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComplianceResponse'
        '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:
    ComplianceResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/ComplianceData'
        meta:
          $ref: '#/components/schemas/Meta'
    ComplianceData:
      type: object
      description: |
        When `determination.status` is `pending`, `screens`, `revenue`,
        `purification`, `stability`, and `filing` are all `null`.
      properties:
        symbol:
          type: string
          example: AAPL
        name:
          type: string
          example: Apple Inc.
        methodology:
          type: string
          example: aaoifi-ss21@2026.1
        as_of:
          type: string
          format: date-time
          nullable: true
          description: When this determination was computed.
        determination:
          type: object
          properties:
            status:
              $ref: '#/components/schemas/ComplianceStatus'
            confidence:
              type: number
              nullable: true
              example: 0.95
            explanation:
              type: string
              nullable: true
              description: Human-readable explanation of the determination (Markdown).
        screens:
          nullable: true
          type: object
          properties:
            business_activity:
              $ref: '#/components/schemas/BusinessActivityScreen'
            debt_to_market_cap:
              $ref: '#/components/schemas/FinancialScreen'
            cash_to_market_cap:
              $ref: '#/components/schemas/FinancialScreen'
            prohibited_revenue:
              $ref: '#/components/schemas/FinancialScreen'
        revenue:
          $ref: '#/components/schemas/RevenueBreakdown'
          nullable: true
        purification:
          $ref: '#/components/schemas/Purification'
          nullable: true
        stability:
          $ref: '#/components/schemas/Stability'
          nullable: true
        filing:
          $ref: '#/components/schemas/FilingContext'
          nullable: true
    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`.
    BusinessActivityScreen:
      type: object
      description: >
        Business-activity screen. Unlike the financial screens, this evaluates

        whether the company's core business is permissible — not a numeric
        ratio.
      properties:
        result:
          $ref: '#/components/schemas/ScreenOutcome'
        activities:
          type: array
          items:
            type: string
          description: Primary permissible activities identified.
        prohibited_activities:
          type: array
          items:
            type: string
        concerns:
          type: array
          items:
            type: string
          description: Activities that warrant awareness even when the screen passes.
        segments:
          type: array
          description: Reported business segments behind the screen, by revenue.
          items:
            type: object
            properties:
              name:
                type: string
                example: iPhone
              revenue_percentage:
                type: number
                nullable: true
                example: 50
              prohibited_revenue_impact:
                type: string
                nullable: true
                description: >-
                  Qualitative impact of this segment on prohibited income (e.g.
                  negligible, minor, major).
                example: negligible
              significance:
                type: string
                nullable: true
                description: Revenue significance of this segment (e.g. major, minor).
                example: major
    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
    RevenueBreakdown:
      type: object
      properties:
        total:
          type: number
          example: 451442000000
        permissible:
          type: object
          properties:
            amount:
              type: number
              example: 446873510000
            percentage:
              type: number
              nullable: true
              example: 98.988
        prohibited:
          type: object
          properties:
            amount:
              type: number
              example: 4568490000
            percentage:
              type: number
              nullable: true
              example: 1.012
            breakdown:
              type: object
              description: Prohibited revenue by category, in reporting currency.
              properties:
                interest_income:
                  type: number
                  example: 4568490000
                gambling:
                  type: number
                  example: 0
                alcohol:
                  type: number
                  example: 0
                weapons:
                  type: number
                  example: 0
                tobacco:
                  type: number
                  example: 0
                adult_entertainment:
                  type: number
                  example: 0
    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
    Stability:
      type: object
      description: How likely the compliance status is to change.
      properties:
        rating:
          type: string
          enum:
            - stable
            - watch
            - borderline
          nullable: true
        drivers:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
                example: COMFORTABLE_BUFFERS
              message:
                type: string
                example: All financial ratios are well within limits
              severity:
                type: string
                enum:
                  - info
                  - warning
                  - critical
    FilingContext:
      type: object
      properties:
        summary:
          type: string
          nullable: true
          example: 10-K(2025-10-31) + 10-Q(2026-05-01)
        as_of:
          type: string
          format: date-time
          nullable: true
        hash:
          type: string
          nullable: true
          description: Deterministic hash of the filing set used for this analysis.
        filings:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                example: 10-K
              period_end:
                type: string
                format: date
                nullable: true
              filing_date:
                type: string
                format: date
                nullable: true
              accession_number:
                type: string
                nullable: true
                example: 0000320193-25-000079
    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

````