# Zoya API Reference

The Zoya API offers data covering Shariah compliance information for global stocks. It is available in basic and advanced packages, where the advanced package includes additional data fields, screening methodologies, and global coverage. The basic package is limited to the US market using the AAOIFI methodology.

The API has two environments: sandbox and live. The sandbox environment is free to use and does not require an active subscription. All you need is a Zoya developer account and an API key that is available for free after registration. Data in the sandbox environment is randomized and does not reflect real-world data. The live environment requires an active subscription to use and has real data.

We are still actively expanding the API to add new capabilities. If you have specific ideas or feature requests that you would be interested in, please reach out to our team at [support+api@zoya.finance](mailto:support+api@zoya.finance).

You can sign up for a free account to try the sandbox API and subscribe to a live data plan at [developer.zoya.finance](https://developer.zoya.finance).

## Quickstart

Check a stock's Shariah compliance status in about a minute. The sandbox is free and does not require a subscription — all you need is a Zoya developer account.

Get a sandbox API key

Sign up at [developer.zoya.finance](https://developer.zoya.finance) and copy a key from your dashboard.

Send a request

Every call is an HTTP `POST` to the GraphQL endpoint with your key in the `Authorization` header.

```bash
curl https://sandbox-api.zoya.finance/graphql \
  -X POST \
  -H "Authorization: sandbox-YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  --data '{"query":"query { basicCompliance { report(symbol: \"AMD\") { symbol name exchange status reportDate } } }"}'
```

Read the response

A successful request returns its payload under `data`.

```json
{
  "data": {
    "basicCompliance": {
      "report": {
        "symbol": "AMD",
        "name": "Advanced Micro Devices Inc.",
        "exchange": "XNAS",
        "status": "COMPLIANT",
        "reportDate": "2026-08-07T00:00:00.000Z"
      }
    }
  }
}
```

When you are ready for real data, point the same request at `https://api.zoya.finance/graphql` and swap the key prefix to `live-`. From there, the Guides cover the common workflows, and the Concepts explain what the returned values mean.

## Authentication

The Zoya API uses API keys to authenticate requests. You can create an API key by signing up for an account at [developer.zoya.finance](https://developer.zoya.finance). Once you have an account, you can view your API keys from the dashboard page there. You can then use these API keys to authenticate requests by setting the `Authorization` header to `live-YOUR_API_KEY_HERE` for the live environment or `sandbox-YOUR_API_KEY_HERE` for the sandbox environment.

This API key should not be exposed publicly. If you need to make requests from a client-side application, you should proxy the requests through your own server. This will prevent your API key from being exposed to the public.

## Environments

Zoya keeps testing and production traffic separate. The schema is identical in both, so you can build against the sandbox and switch by changing the endpoint and the key prefix.

Sandbox

Test dataUse while building and testing. No subscription required.

```text
https://sandbox-api.zoya.finance/graphql
```

Key prefix `sandbox-`

Live

Real dataReturns real compliance data. Requires an active subscription.

```text
https://api.zoya.finance/graphql
```

Key prefix `live-`

Do not treat sandbox data as real

Sandbox responses are randomized and must not be surfaced as investment or compliance information.

## API Explorer

While the API documentation here serves as a reference, we recommend actually experimenting with the API using our API Explorer. You can find the API Explorer at [developer.zoya.finance/explorer](https://developer.zoya.finance/explorer). The API Explorer allows you to run queries against the API and see the results in real-time. It also provides in-line documentation and auto-completion for API queries as you type, so you can learn about the API as you use it.

If you already have another GraphQL API explorer that you would prefer to use instead, the Zoya GraphQL API supports introspection. All you need to do is include your API key in the `Authorization` header for the introspection query.

The complete schema is also published as SDL at [developer.zoya.finance/schema.graphql](https://developer.zoya.finance/schema.graphql). It needs no API key and is republished on every deploy, so it always matches the live schema. Point your editor, code generator, or AI coding assistant at it to get accurate type and field names.

## Changelog

- **September 2026:** `BasicFundReport.purificationRatio` is returned for all customers.
- **August 2026:** The schema is published at [/schema.graphql](https://developer.zoya.finance/schema.graphql), and machine-readable docs at [/llms.txt](https://developer.zoya.finance/llms.txt) and [/llms-full.txt](https://developer.zoya.finance/llms-full.txt).
- **July 2026:** Advanced plan subscribers can download data as CSV from the developer portal.
- **November 2025:** Added `advancedCompliance.menaScreens`. `advancedCompliance.externalScreens` is deprecated.
- **June 2025:** Added `basicCompliance.funds` for US ETFs.
- **June 2024:** Added `zakat.calculate` and `purificationRatio` on compliance reports.

## Plans and licensing

The API is available in two packages. Advanced contains everything in Basic and adds to it, so moving up is additive — nothing you already query stops working. Most integrations start with Basic and move to Advanced when they need markets beyond the US, or need to show users the screening detail behind a rating.

Basic

For US-market products that need a verdict per security. AAOIFI methodology, US stocks and US-listed ETFs, purification ratios.

Advanced

Everything in Basic, plus international markets and the screening detail behind a rating — per-screen results, revenue classification, and FIGI lookup.

Current pricing for both packages is listed on your dashboard at [developer.zoya.finance](https://developer.zoya.finance).

| Capability | Basic | Advanced |
| --- | --- | --- |
| US stock compliance reports | ✓ | ✓ |
| Overall compliance status | ✓ | ✓ |
| Purification ratio | ✓ | ✓ |
| Fund and ETF reports | ✓ | ✓ |
| International markets | – | ✓ |
| Business and financial screen breakdown | – | ✓ |
| Revenue classification amounts | – | ✓ |
| Lookup by FIGI | – | ✓ |
| Zakat calculations | – | – |

Fund and ETF reports come from `basicCompliance.funds` on both packages — `advancedCompliance` has no `funds` field, so an Advanced integration still reads fund coverage through the basic namespace.

Zakat calculation queries sit outside both packages. They are enabled for every account in the sandbox; live access is granted separately — contact [support@zoya.finance](mailto:support@zoya.finance).

Both packages carry distinct licensing models for personal and commercial use:

- **Personal Use License:** For individuals such as investors and researchers for personal and non-public use. Public display of API data on forums, websites, social media, or other public mediums is prohibited.
- **Commercial Use License:** For businesses and professional users. Allows broader use, including internal display within an organization. External display to third parties or the public requires Zoya's prior written approval, which can be requested by submitting a proposal detailing the intended use and presentation of the data. Approval is at Zoya's discretion.

## Attribution

Attribution is required for all users. It is as simple as putting "Data provided by Zoya" somewhere near the data and linking that text to [https://zoya.finance/api](https://zoya.finance/api).

Example:

```html
<a href="https://zoya.finance/api">Data provided by Zoya</a>
```

## Terms of use

Use of the Zoya API, in both the sandbox and live environments, is governed by the Zoya Terms of Use. The personal and commercial licence models under Plans and licensing set out how the data itself may be displayed.

[Read the Terms of Use](https://zoya.finance/terms-of-use)

## GraphQL

The API is modeled after the [GraphQL](https://graphql.org/) specification. This allows you to query the API for exactly the data you need from our schema. GraphQL clients are available for most languages and frameworks. If you need assistance, reach out to our team for support.

In the end, this is an HTTP API that takes in a request according to the GraphQL request specification and returns a JSON response.

Queries are organized into top-level namespaces that map to what you have access to: `basicCompliance` and `advancedCompliance`, documented in full under Operations below. See Plans and licensing for what each one covers.

A third namespace, `zakat`, calculates zakat liability on a set of holdings. It is enabled for every account in the sandbox, so you can build against it without a subscription. Live access is granted separately — contact [support@zoya.finance](mailto:support@zoya.finance).

## Compliance statuses

Compliance is an enum, not a boolean. Treat it as four possible values so that an unrated or ambiguous security does not silently render as non-compliant in your product.

| Status | Meaning |
| --- | --- |
| COMPLIANT | The security passes the given screening methodology. |
| NON_COMPLIANT | The security fails the given screening methodology. |
| QUESTIONABLE | Revenue sources fall in an area of significant scholarly disagreement, or the financial reports do not contain enough information for a definitive judgement. |
| UNRATED | No rating exists for this security under the given methodology. |

A status is always relative to a screening methodology — the same security can be rated differently under different methodologies. New values may be added to this enum over time, so handle unrecognized statuses gracefully rather than assuming the set is closed.

The treatment above is the convention Zoya's own apps use. Reusing it is not required, but keeping `QUESTIONABLE` and `UNRATED` visually distinct from `NON_COMPLIANT` is: those two mean "we cannot tell you", not "no".

## Screening methodology

Zoya screens securities in two stages, and the advanced package exposes each stage separately via the `businessScreen` and `financialScreen` fields alongside the overall `status`.

Business screen

RevenueAnalyses where the company's revenue comes from. The advanced report breaks this down into `compliantRevenue`, `nonCompliantRevenue`, and `questionableRevenue`.

Financial screen

RatiosAnalyses the company's debt and interest ratios. A financial screen never returns `QUESTIONABLE` — it is always `COMPLIANT`, `NON_COMPLIANT`, or `UNRATED`.

`ScreeningMethodology` currently has a single value, `AAOIFI`, which is the same methodology used in the Zoya mobile app. It is a required input on advanced queries so that adding methodologies later is not a breaking change.

The `purificationRatio` field is the portion of dividend income to donate to charity. Multiply it by the dividends received from that security to get the amount to donate; it does not apply to securities that pay no dividend. A `COMPLIANT` fund's ratio is the share of its holdings' revenue that's non-compliant, each holding weighted by its share of the fund. It is `1` for a `NON_COMPLIANT` fund, as for a `NON_COMPLIANT` stock, and `null` for a fund without a `COMPLIANT` or `NON_COMPLIANT` status.

## Symbols and identifiers

A ticker symbol on its own does not uniquely identify a security. Multiple distinct stocks across different markets can share the same symbol, so a symbol is only unambiguous when paired with its exchange.

| Field | Use |
| --- | --- |
| `symbol` | The canonical symbol used by the Zoya API. |
| `rawSymbol` | The ticker without any exchange suffix. |
| `exchange` | Disambiguates securities sharing a symbol across markets. Nullable on some funds, such as mutual funds with no listing exchange. |
| `figi` | A stable security identifier, available on advanced reports. |

Advanced report lookups accept either `symbol` or `figi`. Prefer `figi` when you have it, since it survives ticker changes.

## Markets and coverage

Coverage depends on your package. The basic package covers US equities and US-listed ETFs. The advanced package adds international markets.

Rather than hardcoding a list of markets, query `advancedCompliance.regions` for the set of regions that currently have reports available. Regions are always ISO 3166-1 alpha-2 country codes, such as `US`. Passing a region that is not in that list will not return results.

`advancedCompliance.menaScreens` is a separate endpoint covering Shariah-compliant stocks from MENA regions.

## Data freshness

Zoya's dataset is refreshed regularly to incorporate newly available information across the market, including updated company financials, new listings, delistings, and other relevant changes.

Because companies publish new information on different schedules, the underlying data for any individual company may change less frequently. When new information becomes available, it is incorporated into subsequent dataset refreshes.

Fund reports carry `holdingsAsOfDate`, the latest date holdings information was available for that fund. Funds publish holdings at varying frequencies, and a fund's compliance status can change even when no new holdings data has been published, because the compliance status of its underlying holdings may have changed.

Responses are also cached at the edge for up to 15 minutes, so a newly published report can take that long to appear in your results.

## Required vs optional fields

Some inputs in the API are required, while others are optional. Required inputs are suffixed with an exclamation point `!` in the documentation. If you do not provide a required input, the API will return an error. Optional inputs are not marked with an exclamation point. If you do not provide an optional input, the API will use a default value for that input or ignore it altogether.

Similarly, the `!` suffix in documented response types indicates that the field is always present in the response. If the field is not suffixed with a `!`, it is optional and may return `null` in the response.

## Pagination

Some queries in this API return paginated results. These queries return response pages that contain an `items` field and a `nextToken` field. As the name implies, `items` contains the items for a given page of results. Subsequent queries using the `nextToken` field will return the next page. When the last page is reached, `nextToken` is `null`.

It is important that your filter criteria is consistent across all pages, or an error will be thrown.

Page size limits differ per query:

| Query | Default | Maximum |
| --- | --- | --- |
| `basicCompliance.reports` | 100 | 1000 |
| `basicCompliance.funds` | 2000 | 4000 |

## Error handling

GraphQL requests always return JSON responses with HTTP code 200. Errors are returned in the `errors` field of the response body, while successful requests have their data surfaced in the `data` field. If there are any errors in your request, the `errors` property will be an array of error objects. Every error object will have at least a `message` and `errorType` field to signify the type of error that occurred. There are additional fields that may be useful for debugging, such as locations in your query that encountered the error and the path to the field that encountered the error. For more details, see the [GraphQL Errors spec](https://spec.graphql.org/draft/#sec-Errors).

```json
{
  "data": null,
  "errors": [
    {
      "message": "Not Authorized to access report on type BasicComplianceQuery",
      "errorType": "Unauthorized",
      "path": ["basicCompliance", "report"],
      "locations": [{ "line": 2, "column": 5 }]
    }
  ]
}
```

A response can carry both `data` and `errors` — a partial failure resolves the fields it can and reports the rest, so check `errors` even when `data` is present.

Rate limiting is the exception: exceeding the limit returns a `429 Too Many Requests` HTTP response rather than a 200 with an `errors` array.

## Rate limits

Requests to the Zoya API are rate limited to 10 requests per second. If you exceed this limit, you will receive a `429 Too Many Requests` response. If you need a higher rate limit, please contact our team for assistance.

Each guide below is a complete, runnable query for a common task, with the response it returns. For the exact arguments, fields, and enums behind them, see the

[Operations](https://developer.zoya.finance/docs#group-Operations-Basic-Compliance)reference further down.

## Get Shariah compliance rating for a specific stock

To get the compliance report for a stock, you can query the `basicCompliance.report` field. The example below shows a query that retrieves the latest compliance report for AMD. To request a different stock, just set a different value for `symbol`.

### Query

```graphql
query GetReport {
  basicCompliance {
    report(symbol: "AMD") {
      symbol
      name
      exchange
      status
    }
  }
}
```

### Response

```json
{
  "data": {
    "basicCompliance": {
      "report": {
        "symbol": "AMD",
        "name": "Advanced Micro Devices Inc.",
        "exchange": "XNAS",
        "status": "COMPLIANT"
      }
    }
  }
}
```

## Get all Shariah compliance ratings for the US market

To get a list of all compliance reports, you can query the `basicCompliance.reports` field. The example below fetches the first page of results.

### Query

```graphql
query ListReports {
  basicCompliance {
    reports {
      items {
        symbol
        name
        exchange
        status
      }
      nextToken
    }
  }
}
```

### Response

```json
{
  "data": {
    "basicCompliance": {
      "reports": {
        "items": [
          {
            "symbol": "A",
            "name": "Agilent Technologies Inc.",
            "exchange": "XNYS",
            "status": "COMPLIANT"
          },
          {
            "symbol": "AA",
            "name": "Alcoa Corp",
            "exchange": "XNYS",
            "status": "NON_COMPLIANT"
          },
          // ...
        ],
        "nextToken": "exampleNextPageToken"
      }
    }
  }
}
```

To fetch the next page of results, run the same query again, but with the `nextToken` passed along to the query `input`. Continue to do this until the `nextToken` field is `null`, at which point all pages will have been returned.

This example shows how to fetch the second page of results.

### Query

```graphql
query ListReports {
  basicCompliance {
    reports(input: { nextToken: "exampleNextPageToken" }) {
      items {
        symbol
        name
        exchange
        status
      }
      nextToken
    }
  }
}
```

### Response

```json
{
  "data": {
    "basicCompliance": {
      "reports": {
        "items": [
          {
            "symbol": "BAC",
            "name": "Bank Of America Corp.",
            "exchange": "XNYS",
            "status": "NON_COMPLIANT",
            "reportDate": "2023-12-12:08:03.420Z"
          },
          // ...
        ],
        "nextToken": "anotherNextPageToken"
      }
    }
  }
}
```

## Get a list of all Shariah-compliant stocks in the US market

To get a list of just the compliant stocks, you can query the `basicCompliance.reports` field with a filter for the compliance status.

### Query

```graphql
query ListCompliantStocks {
  basicCompliance {
    reports(input: {
      filters: { status: COMPLIANT }
    }) {
      items {
        symbol
        reportDate
        name
        exchange
      }
      nextToken
    }
  }
}
```

### Response

```json
{
  "data": {
    "basicCompliance": {
      "reports": {
        "items": [
          {
            "symbol": "A",
            "reportDate": "2023-11-20T17:00:00.000Z",
            "name": "Agilent Technologies Inc.",
            "exchange": "XNYS"
          },
          {
            "symbol": "AACG",
            "reportDate": "2023-11-13T17:00:00.000Z",
            "name": "ATA Creativity Global - ADR",
            "exchange": "XNAS"
          },
          // ...
        ],
        "nextToken": "exampleNextPageToken"
      }
    }
  }
}
```

Like the example for fetching all Shariah compliance reports above, this query returns paginated results. To retrieve the next page of results, run the same query again, but with the `nextToken` from the response passed along to the query `input`. Continue to do this until the `nextToken` response is `null`, at which point all pages will have been returned.

## Get the full Shariah compliance report for a specific stock

To get a detailed compliance report for a stock, you can query the `advancedCompliance.report` field. The example below shows a query that retrieves the latest compliance report for AMD. To request a different stock, just set a different value for `symbol`.

This query requires passing in a Shariah screening methodology as input. Currently, only the AAOIFI based screening methodology is supported, but there are plans to expand that in the near future.

Note that fetching detailed compliance reports requires an active subscription to our advanced data package.

### Query

```graphql
query GetAdvancedReport {
  advancedCompliance {
    report(input: {
      symbol: "AMD",
      methodology: AAOIFI
    }) {
      symbol
      rawSymbol
      name
      figi
      exchange
      status
      reportDate
      businessScreen
      financialScreen
      compliantRevenue
      nonCompliantRevenue
      questionableRevenue
      ... on AAOIFIReport {
        securitiesToMarketCapRatio
        debtToMarketCapRatio
      }
    }
  }
}
```

### Response

```json
{
  "data": {
    "advancedCompliance": {
      "report": {
        "symbol": "AMD",
        "rawSymbol": "AMD",
        "name": "Advanced Micro Devices Inc.",
        "figi": null,
        "exchange": "XNAS",
        "status": "COMPLIANT",
        "reportDate": "2023-11-01T16:00:00.000Z",
        "businessScreen": "COMPLIANT",
        "financialScreen": "COMPLIANT",
        "compliantRevenue": 99.7253443758979,
        "nonCompliantRevenue": 0.2746556241020874,
        "questionableRevenue": 0,
        "securitiesToMarketCapRatio": 0.03483800178616272,
        "debtToMarketCapRatio": 0.017235326034917495
      }
    }
  }
}
```

## Get a Shariah compliance report for a non-US stock

To get a detailed compliance report for an international stock, you can query the `advancedCompliance.report` field with a specific symbol. Note that the symbol must be the raw symbol for the stock suffixed with the Bloomberg exchange code. For example, the `TYT` symbol listed on the London Stock Exchange should be queried using `TYT-LN` as the symbol input.

The example below shows a query that retrieves the latest compliance report for ticker `0R0K` on the London Stock Exchange. To request a different stock, just set a different value for `symbol`.

This query requires passing in a Shariah screening methodology as input. Currently, only the AAOIFI based screening methodology is supported, but there are plans to expand that in the near future.

Note that fetching international compliance reports requires an active subscription to our advanced data package.

### Query

```graphql
query GetInternationalReport {
  advancedCompliance {
    report(input: {
      symbol: "0R0K-LN",
      methodology: AAOIFI,
    }) {
      symbol
      rawSymbol
      name
      figi
      exchange
      status
      reportDate
      businessScreen
      financialScreen
      ... on AAOIFIReport {
        debtToMarketCapRatio
        securitiesToMarketCapRatio
      }
    }
  }
}
```

### Response

```json
{
  "data": {
    "advancedCompliance": {
      "report": {
        "symbol": "0R0K-LN",
        "rawSymbol": "0R0K",
        "name": "Cisco Systems, Inc.",
        "figi": "BBG00QDG6DB5",
        "exchange": "XLON",
        "status": "COMPLIANT",
        "reportDate": "2023-12-10:08:03.420Z",
        "businessScreen": "COMPLIANT",
        "financialScreen": "COMPLIANT",
        "compliantRevenue": 98.34,
        "nonCompliantRevenue": 1.66,
        "questionableRevenue": 0,
        "debtToMarketCapRatio": 0.0416,
        "securitiesToMarketCapRatio": 0.1145
      }
    }
  }
}
```

## Get all Shariah compliance reports for a region

To get detailed compliance report for a given region, can query the `advancedCompliance.reports` field with a specific symbol.

The example below shows a query that retrieves a page of compliance reports for the United Kingdom region. To request a different region, just set a different stock, just set a different value for `region` on the input to any ISO 3166-1 alpha-2 country code (e.g., `"US", "CA", "GB", etc). The get a list of all supported regions, you can query the`advancedCompliance.regions` field.

This query requires passing in a Shariah screening methodology as input. Currently, only the AAOIFI based screening methodology is supported, but there are plans to expand that in the near future.

Note that fetching international compliance reports requires an active subscription to our advanced data package.

### Query

```graphql
query ListInternationalReports {
  advancedCompliance {
    reports(input: {
      region: "GB"
      methodology: AAOIFI,
    }) {
      items {
        symbol
        rawSymbol
        name
        figi
        exchange
        status
        reportDate
        businessScreen
        financialScreen
        ... on AAOIFIReport {
          debtToMarketCapRatio
          securitiesToMarketCapRatio
        }
      }
      nextToken
    }
  }
}
```

### Response

```json
{
  "data": {
    "advancedCompliance": {
      "reports": {
        "items": [
          {
            "symbol": "0A02-LN",
            "rawSymbol": "0A02",
            "name": "Neoen S.A.",
            "figi": null,
            "exchange": "XLON",
            "status": "NON_COMPLIANT",
            "reportDate": "2023-07-27T08:00:00.000Z",
            "businessScreen": "COMPLIANT",
            "financialScreen": "NON_COMPLIANT",
            "debtToMarketCapRatio": 0.819055573095525,
            "securitiesToMarketCapRatio": 0.248412711875593
          },
          {
            "symbol": "0A05-LN",
            "rawSymbol": "0A05",
            "name": "Medacta Group SA",
            "figi": null,
            "exchange": "XLON",
            "status": "COMPLIANT",
            "reportDate": "2023-09-22T08:00:00.000Z",
            "businessScreen": "COMPLIANT",
            "financialScreen": "COMPLIANT",
            "debtToMarketCapRatio": 0.07924711603883236,
            "securitiesToMarketCapRatio": 0.011141837087433886
          },
          // ...
      ],
      "nextToken": "exampleNextPageToken"
    }
  }
}
```

## Get all compliant stocks from MENA regions

To get a list of all compliant stocks from MENA regions, you can query the `advancedCompliance.menaScreens` field.

Note that fetching MENA compliance reports requires an active subscription to our advanced data package.

### Query

```graphql
query ListMENAScreens {
  advancedCompliance {
    menaScreens {
      rawSymbol
      name
      exchange
      region
      status
    }
  }
}
```

### Response

```json
{
  "data": {
    "advancedCompliance": {
      "menaScreens": [
        {
          "rawSymbol": "EIBK",
          "name": "Emirates Islamic Bank PJSC",
          "exchange": "XADX",
          "region": "AE",
          "status": "COMPLIANT"
        },
        {
          "rawSymbol": "NBK",
          "name": "National Bank of Kuwait S.A.K.P.",
          "exchange": "XKWD",
          "region": "KW",
          "status": "COMPLIANT"
        },
        // ...
      ]
    }
  }
}
```

## Get a list of Shariah compliance reports for ETFs

To get a list of compliance reports for ETFs, you can query the `basicCompliance.funds` field.

### Query

```graphql
query ListFundReports {
  basicCompliance {
    funds {
      items {
        symbol
        name
        status
        purificationRatio
        reportDate
        holdingsAsOfDate
      }
      nextToken
    }
  }
}
```

### Response

```json
{
  "data": {
    "basicCompliance": {
      "funds": {
        "items": [
          {
            "symbol": "GLD",
            "name": "SPDR Gold Shares",
            "status": "COMPLIANT",
            "purificationRatio": 0,
            "reportDate": "2025-06-04T08:00:00.000Z",
            "holdingsAsOfDate": "2025-06-03T08:00:00.000Z"
          },
          {
            "symbol": "BND",
            "name": "Vanguard Total Bond Market ETF",
            "status": "NON_COMPLIANT",
            "purificationRatio": 1,
            "reportDate": "2025-05-30T08:00:00.000Z",
            "holdingsAsOfDate": "2025-05-29T08:00:00.000Z"
          },
          // ...
        ],
        "nextToken": "exampleNextPageToken"
      }
    }
  }
}
```

## Get list of regions with available Shariah compliance reports

To list all available regions for which compliance reports are available, you can query the `advancedCompliance.regions` field.

Note that fetching international compliance reports requires an active subscription to our advanced data package.

### Query

```graphql
query ListRegions {
  advancedCompliance {
    regions
  }
}
```

### Response

```json
{
  "data": {
    "regions": [
      "CA",
      "DE",
      "FR",
      "GB",
      "IN",
      "JP",
      // ...
    ]
  }
}
```

## Calculate zakat due on a portfolio

The `zakat.calculate` field returns the zakat liability for a set of holdings. It is enabled for every account in the sandbox, so this guide runs without a subscription; live access is granted separately — contact [support@zoya.finance](mailto:support@zoya.finance).

Each holding carries a `strategy`, which is your statement of intent rather than a property of the security. Use `ACTIVE` for positions you intend to trade within a year, which are treated as cash, and `PASSIVE` for long-term holdings, where the calculation looks through to the company's share of current assets. For funds, `PASSIVE` is applied recursively across the fund's holdings.

### Query

```graphql
query CalculateZakat {
  zakat {
    calculate(
      holdings: [
        { symbol: "AAPL", strategy: PASSIVE, quantity: 100, unitPrice: 195.50 }
        { symbol: "AMD", strategy: ACTIVE, quantity: 40, unitPrice: 142.25 }
        { symbol: "GLD", strategy: PASSIVE, quantity: 25, unitPrice: 310.40 }
      ]
    ) {
      zakatLiableAmount
      zakatDue
      currency
      holdings {
        symbol
        strategy
        marketValue
        zakatLiableAmount
        zakatDue
        calculationMethod
      }
    }
  }
}
```

### Response

```json
{
  "data": {
    "zakat": {
      "calculate": {
        "zakatLiableAmount": 16166.45,
        "zakatDue": 404.16,
        "currency": "USD",
        "holdings": [
          {
            "symbol": "AAPL",
            "strategy": "PASSIVE",
            "marketValue": 19550.00,
            "zakatLiableAmount": 2716.45,
            "zakatDue": 67.91,
            "calculationMethod": "PASSIVE_INVESTMENT"
          },
          {
            "symbol": "AMD",
            "strategy": "ACTIVE",
            "marketValue": 5690.00,
            "zakatLiableAmount": 5690.00,
            "zakatDue": 142.25,
            "calculationMethod": "TREAT_AS_CASH"
          },
          {
            "symbol": "GLD",
            "strategy": "PASSIVE",
            "marketValue": 7760.00,
            "zakatLiableAmount": 7760.00,
            "zakatDue": 194.00,
            "calculationMethod": "TREAT_AS_CASH"
          }
        ]
      }
    }
  }
}
```

Read `calculationMethod` per holding rather than assuming the strategy you sent was applied. It is the method actually used, and the two can differ: `GLD` above was submitted as `PASSIVE` but returns `TREAT_AS_CASH`, because a precious metals spot fund is treated as cash for zakat purposes. A holding can also come back as `FALLBACK_30` — 2.5% of 30% of market value — when outstanding share or current asset data is not reliable enough to look through the company. Surfacing the method is what lets a user understand a number they may be asked to justify.

`zakatDue` is always 2.5% of `zakatLiableAmount`, at both the holding and portfolio level, so you can display either without recomputing. Mixed-currency holdings are returned in USD.

One thing the API does not decide for you: whether zakat is owed at all. That depends on the nisab threshold applied to the user's total wealth, not to the holdings in a single request.

## funds

### Description

Retrieves a list of funds and their compliance reports. Currently only covers US-based ETFs.

### Response

Returns a [`BasicFundReportsPage!`](https://developer.zoya.finance/docs#definition-BasicFundReportsPage)

### Arguments

| Name | Description |
| --- | --- |
| `input` - [`BasicFundsInput`](https://developer.zoya.finance/docs#definition-BasicFundsInput) | Optional input for pagination and filtering options when listing funds. Currently, it is recommended to omit this. It is for forward-compatibility of additional filtering capabilities and fund types. |

### Example

#### Query

```graphql
query Funds($input: BasicFundsInput) {
  funds(input: $input) {
    items {
      symbol
      name
      exchange
      status
      holdingsAsOfDate
      purificationRatio
      reportDate
    }
    nextToken
  }
}
```

#### Variables

```json
{"input": BasicFundsInput}
```

#### Response

```json
{
  "data": {
    "funds": {
      "items": [BasicFundReport],
      "nextToken": "xyz789"
    }
  }
}
```

## report

### Description

Retrieve the most recent Shariah compliance report for a given symbol based on the AAOIFI methodology. This endpoint is limited to US stocks only. If no report is found, this will return `null`.

### Response

Returns a [`BasicComplianceReport`](https://developer.zoya.finance/docs#definition-BasicComplianceReport)

### Arguments

| Name | Description |
| --- | --- |
| `symbol` - [`String!`](https://developer.zoya.finance/docs#definition-String) | The symbol of the stock to retrieve a compliance report for (e.g., "AAPL" or "AMD"). |

### Example

#### Query

```graphql
query Report($symbol: String!) {
  report(symbol: $symbol) {
    symbol
    name
    exchange
    status
    purificationRatio
    reportDate
  }
}
```

#### Variables

```json
{"symbol": "abc123"}
```

#### Response

```json
{
  "data": {
    "report": {
      "symbol": "xyz789",
      "name": "abc123",
      "exchange": "abc123",
      "status": "COMPLIANT",
      "purificationRatio": 987.65,
      "reportDate": "2023-12-10:08:03.420Z"
    }
  }
}
```

## reports

### Description

Retrieve a list of Shariah compliance reports based on the AAOIFI methodology. Limited to US equities only.

### Response

Returns a [`BasicComplianceReportsPage!`](https://developer.zoya.finance/docs#definition-BasicComplianceReportsPage)

### Arguments

| Name | Description |
| --- | --- |
| `input` - [`BasicReportsInput`](https://developer.zoya.finance/docs#definition-BasicReportsInput) | Optional input for pagination and filtering options when listing reports. |

### Example

#### Query

```graphql
query Reports($input: BasicReportsInput) {
  reports(input: $input) {
    items {
      symbol
      name
      exchange
      status
      purificationRatio
      reportDate
    }
    nextToken
  }
}
```

#### Variables

```json
{"input": BasicReportsInput}
```

#### Response

```json
{
  "data": {
    "reports": {
      "items": [BasicComplianceReport],
      "nextToken": "abc123"
    }
  }
}
```

## externalScreens

Use menaScreens instead.

### Response

Returns [`[MENAScreens!]`](https://developer.zoya.finance/docs#definition-MENAScreens)

### Example

#### Query

```graphql
query ExternalScreens {
  externalScreens {
    rawSymbol
    name
    exchange
    region
    status
    reportDate
  }
}
```

#### Response

```json
{
  "data": {
    "externalScreens": [
      {
        "rawSymbol": "xyz789",
        "name": "xyz789",
        "exchange": "abc123",
        "region": "abc123",
        "status": "COMPLIANT",
        "reportDate": "2023-12-10:08:03.420Z"
      }
    ]
  }
}
```

## menaScreens

### Description

Retrieve a list of stocks from MENA regions that are considered to be shariah compliant. The sandbox environment will just return a limited subset instead of mock data for this query.

### Response

Returns [`[MENAScreens!]`](https://developer.zoya.finance/docs#definition-MENAScreens)

### Example

#### Query

```graphql
query MenaScreens {
  menaScreens {
    rawSymbol
    name
    exchange
    region
    status
    reportDate
  }
}
```

#### Response

```json
{
  "data": {
    "menaScreens": [
      {
        "rawSymbol": "xyz789",
        "name": "xyz789",
        "exchange": "xyz789",
        "region": "xyz789",
        "status": "COMPLIANT",
        "reportDate": "2023-12-10:08:03.420Z"
      }
    ]
  }
}
```

## regions

### Description

Retrieve the list of supported regions/markets that have compliance reports available. These will always be ISO 3166-1 alpha-2 country codes (e.g. "US").

### Response

Returns [`[String!]!`](https://developer.zoya.finance/docs#definition-String)

### Example

#### Query

```graphql
query Regions {
  regions
}
```

#### Response

```json
{"data": {"regions": ["abc123"]}}
```

## report

### Description

Retrieve the most recent advanced Shariah compliance report for a given symbol or FIGI identifier based on the given methodology. If the identifier is not recognized or no report is found, this will return `null`.

### Response

Returns an [`AdvancedComplianceReport`](https://developer.zoya.finance/docs#definition-AdvancedComplianceReport)

### Arguments

| Name | Description |
| --- | --- |
| `input` - [`AdvancedReportInput!`](https://developer.zoya.finance/docs#definition-AdvancedReportInput) | The input for retrieving a detailed compliance report for a given identifier and methodology. Both the methodolgy and some identifier (either `symbol` or `figi`) must be provided. If both are provided, `figi` will be used. An error will be thrown if neither are provided. Different fields are returned depending on the screening methodology used. The `AdvancedComplianceReport` interface is the base type that contains all fields in common across different methodologies. GraphQL fragment queries can be used to retrieve fields unique to a specific methdology. |

### Example

#### Query

```graphql
query Report($input: AdvancedReportInput!) {
  report(input: $input) {
    symbol
    rawSymbol
    name
    figi
    exchange
    status
    reportDate
    businessScreen
    financialScreen
    compliantRevenue
    nonCompliantRevenue
    questionableRevenue
    purificationRatio
  }
}
```

#### Variables

```json
{"input": AdvancedReportInput}
```

#### Response

```json
{
  "data": {
    "report": {
      "symbol": "0R0K-LN",
      "rawSymbol": "0R0K",
      "name": "Cisco Systems, Inc.",
      "figi": "BBG00QDG6DB5",
      "exchange": "XLON",
      "status": "COMPLIANT",
      "reportDate": "2023-12-10:08:03.420Z",
      "businessScreen": "COMPLIANT",
      "financialScreen": "COMPLIANT",
      "compliantRevenue": 98.34,
      "nonCompliantRevenue": 1.66,
      "questionableRevenue": 0,
      "purificationRatio": 123.45
    }
  }
}
```

## reports

### Description

Retrieve a list of advanced Shariah compliance reports for a given region and methodology.

### Response

Returns an [`AdvancedComplianceReportsPage!`](https://developer.zoya.finance/docs#definition-AdvancedComplianceReportsPage)

### Arguments

| Name | Description |
| --- | --- |
| `input` - [`AdvancedReportsInput!`](https://developer.zoya.finance/docs#definition-AdvancedReportsInput) | The input for querying for a list of detailed compliance reports under the advancedCompliance API package. The `methodology` and `region` fields must be provided. The `filters` field is optional. This API is paginated. To retrieve the next page of results, pass the `nextToken` value from the previous API response as the `nextToken` parameter. When the last page of results is reached, the `nextToken` field will be `null`. |

### Example

#### Query

```graphql
query Reports($input: AdvancedReportsInput!) {
  reports(input: $input) {
    items {
      symbol
      rawSymbol
      name
      figi
      exchange
      status
      reportDate
      businessScreen
      financialScreen
      compliantRevenue
      nonCompliantRevenue
      questionableRevenue
      purificationRatio
    }
    nextToken
  }
}
```

#### Variables

```json
{"input": AdvancedReportsInput}
```

#### Response

```json
{
  "data": {
    "reports": {
      "items": [AdvancedComplianceReport],
      "nextToken": "xyz789"
    }
  }
}
```

## AAOIFIReport

### Description

Report shape used for the AAOIFI methodology.

### Fields

| Field Name | Description |
| --- | --- |
| `symbol` - [`String!`](https://developer.zoya.finance/docs#definition-String) | The symbol Zoya uses to uniquely identify a stock. Exchange specific suffixes will be used for international exchanges outside the US. |
| `rawSymbol` - [`String!`](https://developer.zoya.finance/docs#definition-String) | The symbol for the ticker without any exchange suffix included. Note that multiple distinct stocks may have identical symbols. |
| `name` - [`String!`](https://developer.zoya.finance/docs#definition-String) | The name of the entity associated with this report. |
| `figi` - [`String`](https://developer.zoya.finance/docs#definition-String) | The FIGI identifier for the entity associated with this report. This field may be `null` for some entities. |
| `exchange` - [`String!`](https://developer.zoya.finance/docs#definition-String) | The exchange on which the stock is traded. |
| `status` - [`ComplianceStatus!`](https://developer.zoya.finance/docs#definition-ComplianceStatus) | The overall Shariah compliance status of the stock or security. |
| `reportDate` - [`AWSDateTime!`](https://developer.zoya.finance/docs#definition-AWSDateTime) | The date the compliance report was last updated. Reports are updated based on company reports which are published at different times of the year. |
| `businessScreen` - [`ComplianceStatus!`](https://developer.zoya.finance/docs#definition-ComplianceStatus) | The Shariah compliance of the revenue sources of the associated entity. |
| `financialScreen` - [`ComplianceStatus!`](https://developer.zoya.finance/docs#definition-ComplianceStatus) | The Shariah compliance of financial ratios of the associated entity based on the screening methodology. |
| `compliantRevenue` - [`Float!`](https://developer.zoya.finance/docs#definition-Float) | Percentage of revenue earned that is considered Shariah compliant. |
| `nonCompliantRevenue` - [`Float!`](https://developer.zoya.finance/docs#definition-Float) | Percentage of revenue earned that is considered not Shariah compliant. |
| `questionableRevenue` - [`Float!`](https://developer.zoya.finance/docs#definition-Float) | Percentage of revenue earned that is considered questionable with regards to Shariah compliance. This may be due to broad differences of opinions among scholars or due to limited details published by the company for a given revenue segment. |
| `purificationRatio` - [`Float!`](https://developer.zoya.finance/docs#definition-Float) | The portion of profits to be donated to charity for purification. Multiply this number by dividends received or capital gains realized to determine the amount to donate. |
| `debtToMarketCapRatio` - [`Float!`](https://developer.zoya.finance/docs#definition-Float) | Ratio of interest-bearing debt relative to market capitalization. |
| `securitiesToMarketCapRatio` - [`Float!`](https://developer.zoya.finance/docs#definition-Float) | Ratio of interest bearing securities relative to market capitalization. |

### Example

```json
{
  "symbol": "0R0K-LN",
  "rawSymbol": "0R0K",
  "name": "Cisco Systems, Inc.",
  "figi": "BBG00QDG6DB5",
  "exchange": "abc123",
  "status": "COMPLIANT",
  "reportDate": "2023-12-10:08:03.420Z",
  "businessScreen": "COMPLIANT",
  "financialScreen": "COMPLIANT",
  "compliantRevenue": 98.34,
  "nonCompliantRevenue": 1.66,
  "questionableRevenue": 0,
  "purificationRatio": 987.65,
  "debtToMarketCapRatio": 0.0416,
  "securitiesToMarketCapRatio": 0.1145
}
```

## AWSDateTime

### Description

An ISO8601 formatted datetime string.

### Example

```graphql
"2023-12-10:08:03.420Z"
```

## AdvancedComplianceQuery

### Description

Queries available for users with the advancedCompliance subscription package.

### Fields

| Field Name | Description |
| --- | --- |
| `report` - [`AdvancedComplianceReport`](https://developer.zoya.finance/docs#definition-AdvancedComplianceReport) | Retrieve the most recent advanced Shariah compliance report for a given symbol or FIGI identifier based on the given methodology. If the identifier is not recognized or no report is found, this will return `null`. |
| Arguments `input` - [`AdvancedReportInput!`](https://developer.zoya.finance/docs#definition-AdvancedReportInput) The input for retrieving a detailed compliance report for a given identifier and methodology. Both the methodolgy and some identifier (either `symbol` or `figi`) must be provided. If both are provided, `figi` will be used. An error will be thrown if neither are provided. Different fields are returned depending on the screening methodology used. The `AdvancedComplianceReport` interface is the base type that contains all fields in common across different methodologies. GraphQL fragment queries can be used to retrieve fields unique to a specific methdology. |  |
| `reports` - [`AdvancedComplianceReportsPage!`](https://developer.zoya.finance/docs#definition-AdvancedComplianceReportsPage) | Retrieve a list of advanced Shariah compliance reports for a given region and methodology. |
| Arguments `input` - [`AdvancedReportsInput!`](https://developer.zoya.finance/docs#definition-AdvancedReportsInput) The input for querying for a list of detailed compliance reports under the advancedCompliance API package. The `methodology` and `region` fields must be provided. The `filters` field is optional. This API is paginated. To retrieve the next page of results, pass the `nextToken` value from the previous API response as the `nextToken` parameter. When the last page of results is reached, the `nextToken` field will be `null`. |  |
| `regions` - [`[String!]!`](https://developer.zoya.finance/docs#definition-String) | Retrieve the list of supported regions/markets that have compliance reports available. These will always be ISO 3166-1 alpha-2 country codes (e.g. "US"). |
| `menaScreens` - [`[MENAScreens!]`](https://developer.zoya.finance/docs#definition-MENAScreens) | Retrieve a list of stocks from MENA regions that are considered to be shariah compliant. The sandbox environment will just return a limited subset instead of mock data for this query. |
| `externalScreens` - [`[MENAScreens!]`](https://developer.zoya.finance/docs#definition-MENAScreens) | Use menaScreens instead. |

### Example

```json
{
  "report": AdvancedComplianceReport,
  "reports": AdvancedComplianceReportsPage,
  "regions": ["abc123"],
  "menaScreens": [MENAScreens],
  "externalScreens": [MENAScreens]
}
```

## AdvancedComplianceReport

### Description

Base interface used across a variety of Shariah compliance reports. Other reports may extend this interface with additional properties.

### Fields

| Field Name | Description |
| --- | --- |
| `symbol` - [`String!`](https://developer.zoya.finance/docs#definition-String) | The symbol Zoya uses to uniquely identify a stock. Exchange specific suffixes will be used for international exchanges outside the US. |
| `rawSymbol` - [`String!`](https://developer.zoya.finance/docs#definition-String) | The symbol for the ticker without any exchange suffix included. Note that multiple distinct stocks may have identical symbols. |
| `name` - [`String!`](https://developer.zoya.finance/docs#definition-String) | The name of the entity associated with this report. |
| `figi` - [`String`](https://developer.zoya.finance/docs#definition-String) | The FIGI identifier for the entity associated with this report. This field may be `null` for some entities. |
| `exchange` - [`String!`](https://developer.zoya.finance/docs#definition-String) | The exchange on which the stock is traded. |
| `status` - [`ComplianceStatus!`](https://developer.zoya.finance/docs#definition-ComplianceStatus) | The overall Shariah compliance status of the stock or security. |
| `reportDate` - [`AWSDateTime!`](https://developer.zoya.finance/docs#definition-AWSDateTime) | The date the compliance report was last updated. Reports are updated based on company reports which are published at different times of the year. |
| `businessScreen` - [`ComplianceStatus!`](https://developer.zoya.finance/docs#definition-ComplianceStatus) | The Shariah compliance of the revenue sources of the associated entity. |
| `financialScreen` - [`ComplianceStatus!`](https://developer.zoya.finance/docs#definition-ComplianceStatus) | The Shariah compliance of financial ratios of the associated entity based on the screening methodology. |
| `compliantRevenue` - [`Float!`](https://developer.zoya.finance/docs#definition-Float) | Percentage of revenue earned that is considered Shariah compliant. |
| `nonCompliantRevenue` - [`Float!`](https://developer.zoya.finance/docs#definition-Float) | Percentage of revenue earned that is considered not Shariah compliant. |
| `questionableRevenue` - [`Float!`](https://developer.zoya.finance/docs#definition-Float) | Percentage of revenue earned that is considered questionable with regards to Shariah compliance. This may be due to broad differences of opinions among scholars or due to limited details published by the company for a given revenue segment. |
| `purificationRatio` - [`Float!`](https://developer.zoya.finance/docs#definition-Float) | The portion of profits to be donated to charity for purification. Multiply this number by dividends received or capital gains realized to determine the amount to donate. |

### Possible Types

| AdvancedComplianceReport Types |
| --- |
| [`AAOIFIReport`](https://developer.zoya.finance/docs#definition-AAOIFIReport) |

### Example

```json
{
  "symbol": "0R0K-LN",
  "rawSymbol": "0R0K",
  "name": "Cisco Systems, Inc.",
  "figi": "BBG00QDG6DB5",
  "exchange": "XLON",
  "status": "COMPLIANT",
  "reportDate": "2023-12-10:08:03.420Z",
  "businessScreen": "COMPLIANT",
  "financialScreen": "COMPLIANT",
  "compliantRevenue": 98.34,
  "nonCompliantRevenue": 1.66,
  "questionableRevenue": 0,
  "purificationRatio": 123.45
}
```

## AdvancedComplianceReportsPage

### Description

A page of advanced Shariah compliance reports. Use the `nextToken` field to retrieve the next page of results via subsequent API calls.

### Fields

| Field Name | Description |
| --- | --- |
| `items` - [`[AdvancedComplianceReport!]!`](https://developer.zoya.finance/docs#definition-AdvancedComplianceReport) | A list of advanced Shariah compliance reports. |
| `nextToken` - [`String`](https://developer.zoya.finance/docs#definition-String) | The token to use to retrieve the next page of paginated results. This will be `null` if the last page has been reached and there are no more results. |

### Example

```json
{
  "items": [AdvancedComplianceReport],
  "nextToken": "xyz789"
}
```

## AdvancedReportFilters

### Description

Filters for limiting the list of Shariah compliance reports returned by the `advancedCompliance/reports` query.

### Fields

| Input Field | Description |
| --- | --- |
| `status` - [`ComplianceStatus`](https://developer.zoya.finance/docs#definition-ComplianceStatus) | Set to a compliance status to filter for reports with that status. |

### Example

```json
{"status": "COMPLIANT"}
```

## AdvancedReportInput

### Description

Input for querying for detailed compliance reports for a given identifier under the advancedCompliance API package.

Either `symbol` or `figi` must be provided. If both are provided, `figi` will be used. An error will be thrown if neither are provided.

### Fields

| Input Field | Description |
| --- | --- |
| `symbol` - [`String`](https://developer.zoya.finance/docs#definition-String) | The symbol/ticker used to identify the stock on exchanges. For non-US symbols, the Bloomberg exchange suffix should be included (e.g., "TYT-LN" for "TYT" listing on the London Stock Exchange). Either symbol or figi must be provided. If both are provided, figi will be used. An error will be thrown if neither are provided. |
| `figi` - [`String`](https://developer.zoya.finance/docs#definition-String) | The FIGI identifier for the entity whose compliance report is to be retrieved. Either figi or symbol must be provided. If both are provided, figi will be used. An error will be thrown if neither are provided. |
| `methodology` - [`ScreeningMethodology!`](https://developer.zoya.finance/docs#definition-ScreeningMethodology) | The screening methodology to use for Shariah compliance evaluation. |

### Example

```json
{
  "symbol": "xyz789",
  "figi": "abc123",
  "methodology": "AAOIFI"
}
```

## AdvancedReportsInput

### Description

Input for querying for a list of detailed compliance reports under the advancedCompliance API package.

This API is paginated. To retrieve the next page of results, pass the `nextToken` value from the previous API response as the `nextToken` parameter. When the last page of results is reached, the `nextToken` field will be `null`.

### Fields

| Input Field | Description |
| --- | --- |
| `region` - [`String!`](https://developer.zoya.finance/docs#definition-String) | The region to list reports from (e.g. "US", "GB", "CA"). Available regions can be discovered by querying the API by advancedCompliance/regions. |
| `methodology` - [`ScreeningMethodology!`](https://developer.zoya.finance/docs#definition-ScreeningMethodology) | The screening methodology to use for Shariah compliance evaluation. |
| `filters` - [`AdvancedReportFilters`](https://developer.zoya.finance/docs#definition-AdvancedReportFilters) | Filters will be applied to the list of reports returned by this API. Currently, you can use this to only fetch reports with a specific shariah compliance status. |
| `nextToken` - [`String`](https://developer.zoya.finance/docs#definition-String) | To retrieve the next page of results, pass the `nextToken` value from the previous API response as the `nextToken` parameter in the next API call. |
| `limit` - [`Int`](https://developer.zoya.finance/docs#definition-Int) | The maximum number of results to return per page. The default is 100 and the limit is 500. |

### Example

```json
{
  "region": "xyz789",
  "methodology": "AAOIFI",
  "filters": AdvancedReportFilters,
  "nextToken": "xyz789",
  "limit": 123
}
```

## BasicComplianceQuery

### Description

Queries available for users with the basicCompliance subscription package. Users with the advancedCompliance package also have permissions to these queries.

### Fields

| Field Name | Description |
| --- | --- |
| `report` - [`BasicComplianceReport`](https://developer.zoya.finance/docs#definition-BasicComplianceReport) | Retrieve the most recent Shariah compliance report for a given symbol based on the AAOIFI methodology. This endpoint is limited to US stocks only. If no report is found, this will return `null`. |
| Arguments `symbol` - [`String!`](https://developer.zoya.finance/docs#definition-String) The symbol of the stock to retrieve a compliance report for (e.g., "AAPL" or "AMD"). |  |
| `reports` - [`BasicComplianceReportsPage!`](https://developer.zoya.finance/docs#definition-BasicComplianceReportsPage) | Retrieve a list of Shariah compliance reports based on the AAOIFI methodology. Limited to US equities only. |
| Arguments `input` - [`BasicReportsInput`](https://developer.zoya.finance/docs#definition-BasicReportsInput) Optional input for pagination and filtering options when listing reports. |  |
| `funds` - [`BasicFundReportsPage!`](https://developer.zoya.finance/docs#definition-BasicFundReportsPage) | Retrieves a list of funds and their compliance reports. Currently only covers US-based ETFs. |
| Arguments `input` - [`BasicFundsInput`](https://developer.zoya.finance/docs#definition-BasicFundsInput) Optional input for pagination and filtering options when listing funds. Currently, it is recommended to omit this. It is for forward-compatibility of additional filtering capabilities and fund types. |  |

### Example

```json
{
  "report": BasicComplianceReport,
  "reports": BasicComplianceReportsPage,
  "funds": BasicFundReportsPage
}
```

## BasicComplianceReport

### Description

The Shariah compliance report available for a given security.

### Fields

| Field Name | Description |
| --- | --- |
| `symbol` - [`String!`](https://developer.zoya.finance/docs#definition-String) | The symbol/ticker used to identify the stock on exchanges. |
| `name` - [`String!`](https://developer.zoya.finance/docs#definition-String) | The name of the company tied to the security. |
| `exchange` - [`String!`](https://developer.zoya.finance/docs#definition-String) | The exchange on which the stock is traded. |
| `status` - [`ComplianceStatus!`](https://developer.zoya.finance/docs#definition-ComplianceStatus) | The Shariah compliance status of the security. |
| `purificationRatio` - [`Float!`](https://developer.zoya.finance/docs#definition-Float) | The portion of profits to be donated to charity for purification. Multiply this number by dividends received or capital gains realized to determine the amount to donate. |
| `reportDate` - [`AWSDateTime!`](https://developer.zoya.finance/docs#definition-AWSDateTime) | The date the compliance report was generated. Different companies publish financial reports at different times of the year, but for any given security, this will usually update once a quarter. |

### Example

```json
{
  "symbol": "xyz789",
  "name": "xyz789",
  "exchange": "xyz789",
  "status": "COMPLIANT",
  "purificationRatio": 123.45,
  "reportDate": "2023-12-10:08:03.420Z"
}
```

## BasicComplianceReportsPage

### Description

A page of Shariah compliance reports. Use the `nextToken` field to retrieve the next page of results via subsequent API calls.

### Fields

| Field Name | Description |
| --- | --- |
| `items` - [`[BasicComplianceReport!]!`](https://developer.zoya.finance/docs#definition-BasicComplianceReport) | List of Shariah compliance reports. |
| `nextToken` - [`String`](https://developer.zoya.finance/docs#definition-String) | The token to use to retrieve the next page of paginated results. This will be `null` if the last page has been reached and there are no more results. |

### Example

```json
{
  "items": [BasicComplianceReport],
  "nextToken": "abc123"
}
```

## BasicFundReport

### Fields

| Field Name | Description |
| --- | --- |
| `symbol` - [`String!`](https://developer.zoya.finance/docs#definition-String) | The symbol/ticker used to identify the fund on exchanges. |
| `name` - [`String!`](https://developer.zoya.finance/docs#definition-String) | The name of the fund. |
| `exchange` - [`String`](https://developer.zoya.finance/docs#definition-String) | The exchange on which the fund is traded. Nullable, as some funds may not have a specific exchange associated with them (e.g., some mutual funds). |
| `status` - [`ComplianceStatus!`](https://developer.zoya.finance/docs#definition-ComplianceStatus) | The Shariah compliance status of the fund. |
| `holdingsAsOfDate` - [`AWSDateTime!`](https://developer.zoya.finance/docs#definition-AWSDateTime) | The latest date where fund holding information was available for the fund. Different funds publish updates at varying frequencies. Note that compliance report changes can occur even with no holdings information available due to compliance status changes of individual holdings. |
| `purificationRatio` - [`Float`](https://developer.zoya.finance/docs#definition-Float) | The portion of profits to be donated to charity for purification. Multiply this number by dividends received or capital gains realized to determine the amount to donate. For a COMPLIANT fund, this is the share of its holdings' revenue that's non-compliant, each holding weighted by its share of the fund, or null in the rare case that none of its holdings could be rated. It is 1 for a NON_COMPLIANT fund, and null for a fund with any other status. |
| `reportDate` - [`AWSDateTime!`](https://developer.zoya.finance/docs#definition-AWSDateTime) | The date the compliance report was generated. |

### Example

```json
{
  "symbol": "xyz789",
  "name": "xyz789",
  "exchange": "abc123",
  "status": "COMPLIANT",
  "holdingsAsOfDate": "2023-12-10:08:03.420Z",
  "purificationRatio": 987.65,
  "reportDate": "2023-12-10:08:03.420Z"
}
```

## BasicFundReportsPage

### Description

A page of Shariah compliance reports for funds. The nextToken field can be used to retrieve the next page of results via subsequent API calls.

### Fields

| Field Name | Description |
| --- | --- |
| `items` - [`[BasicFundReport!]!`](https://developer.zoya.finance/docs#definition-BasicFundReport) | List of Shariah compliance reports of funds. |
| `nextToken` - [`String`](https://developer.zoya.finance/docs#definition-String) | The token to use to retrieve the next page of paginated results. This will be `null` if the last page has been reached and there are no more results. |

### Example

```json
{
  "items": [BasicFundReport],
  "nextToken": "xyz789"
}
```

## BasicFundsInput

### Description

Input for query/basicCompliance/funds field path. Currently, the API only returns ETFs, so this input can be omitted and all funds will be returned. The interface is structured for forward-compatibility with mutual funds and filter additions in the future.

### Fields

| Input Field | Description |
| --- | --- |
| `nextToken` - [`String`](https://developer.zoya.finance/docs#definition-String) | To retrieve the next page of results, pass the `nextToken` value from the previous API response as the `nextToken` parameter in the next API call. This field is optional. |
| `limit` - [`Int`](https://developer.zoya.finance/docs#definition-Int) | The maximum number of results to return per page. The default is 2000 and the maximum is 4000. This field is optional. |

### Example

```json
{"nextToken": "xyz789", "limit": 987}
```

## BasicReportFilters

### Description

Filters for limiting the list of Shariah compliance reports returned by the `basicCompliance/reports` query.

### Fields

| Input Field | Description |
| --- | --- |
| `status` - [`ComplianceStatus`](https://developer.zoya.finance/docs#definition-ComplianceStatus) | Set to a compliance status to only return reports with that status. |

### Example

```json
{"status": "COMPLIANT"}
```

## BasicReportsInput

### Description

Input for query/basicCompliance/reports field path. Supports filtering and pagination.

### Fields

| Input Field | Description |
| --- | --- |
| `filters` - [`BasicReportFilters`](https://developer.zoya.finance/docs#definition-BasicReportFilters) | Filters will be applied to the list of reports returned by this API. Currently, you can use this to only fetch reports with a specific shariah compliance status. This field is optional. |
| `nextToken` - [`String`](https://developer.zoya.finance/docs#definition-String) | To retrieve the next page of results, pass the `nextToken` value from the previous API response as the `nextToken` parameter in the next API call. This field is optional. |
| `limit` - [`Int`](https://developer.zoya.finance/docs#definition-Int) | The maximum number of results to return per page. The default is 100 and the maximum limit is 1000. This field is optional. |

### Example

```json
{
  "filters": BasicReportFilters,
  "nextToken": "thisIsMyNextToken",
  "limit": 100
}
```

## Boolean

### Description

The `Boolean` scalar type represents `true` or `false`.

## ComplianceStatus

### Description

Possible Shariah compliance status for a given security or screen. Note that financial screens will never have a result of `QUESTIONABLE`.

### Values

| Enum Value | Description |
| --- | --- |
| `COMPLIANT` | The security is shariah compliant with a given screening methodology. |
| `NON_COMPLIANT` | The security is not shariah compliant with a given screening methodology. |
| `QUESTIONABLE` | The revenue sources of the associated entity are either from an area where there is a great deal of difference of opinion among scholars as to their permissibility or the financial reports do not contain enough information to be able to make a definitive judgement. |
| `UNRATED` | The security has no rating for the given screening methodology. |

### Example

```graphql
"COMPLIANT"
```

## Float

### Description

The `Float` scalar type represents signed double-precision fractional values as specified by [IEEE 754](https://en.wikipedia.org/wiki/IEEE_floating_point).

### Example

```json
123.45
```

## Int

### Description

The `Int` scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

### Example

```json
987
```

## MENAScreens

### Fields

| Field Name | Description |
| --- | --- |
| `rawSymbol` - [`String!`](https://developer.zoya.finance/docs#definition-String) | The symbol for the ticker without any exchange suffix included. Note that multiple distinct stocks may have identical symbols, but a pair of symbol and exchange will uniquely identify a listing. |
| `name` - [`String!`](https://developer.zoya.finance/docs#definition-String) | The name of the company tied to the security. |
| `exchange` - [`String!`](https://developer.zoya.finance/docs#definition-String) | The exchange on which the stock is traded. |
| `region` - [`String!`](https://developer.zoya.finance/docs#definition-String) | The region in which the stock is traded. Will always be an ISO 3166-1 alpha-2 country code (e.g. "KW" for Kuwait). |
| `status` - [`ComplianceStatus!`](https://developer.zoya.finance/docs#definition-ComplianceStatus) | The compliance status of the stock. Stocks in the MENA screened list will always be compliant. |
| `reportDate` - [`AWSDateTime!`](https://developer.zoya.finance/docs#definition-AWSDateTime) | The date the compliance report was last updated. Reports are updated based on company reports which are published at different times of the year. |

### Example

```json
{
  "rawSymbol": "xyz789",
  "name": "xyz789",
  "exchange": "abc123",
  "region": "abc123",
  "status": "COMPLIANT",
  "reportDate": "2023-12-10:08:03.420Z"
}
```

## ScreeningMethodology

### Description

Possible screening methodologies for evaluating Shariah compliance. While all methodologies evaluate stocks based on impermissible income and exposure to interest, the specific forumulas to calculate results vary. Currently, only the AAOIFI methodology is supported, but we plan to add support for other methodologies in the future.

### Values

| Enum Value | Description |
| --- | --- |
| `AAOIFI` | The methodology currently used today in the Zoya Mobile App. |

### Example

```graphql
"AAOIFI"
```

## String

### Description

The `String` scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

### Example

```graphql
"xyz789"
```

## ZakatCalculation

### Description

The result of a zakat calculation for a set of holdings.

### Fields

| Field Name | Description |
| --- | --- |
| `zakatLiableAmount` - [`Float!`](https://developer.zoya.finance/docs#definition-Float) | The sum of the calculated zakat liable amount for all holdings. The zakat due will be 2.5% of this number. |
| `zakatDue` - [`Float!`](https://developer.zoya.finance/docs#definition-Float) | The total zakat due for all given holdings. |
| `currency` - [`String!`](https://developer.zoya.finance/docs#definition-String) | The ISO 4217 currency code for the zakat due amount. If holdings with mixed currencies were given as input, the results will be in USD. |
| `holdings` - [`[ZakatHoldingCalculation!]!`](https://developer.zoya.finance/docs#definition-ZakatHoldingCalculation) | The individual zakat calculations for each holding given as input. |

### Example

```json
{
  "zakatLiableAmount": 987.65,
  "zakatDue": 123.45,
  "currency": "abc123",
  "holdings": [ZakatHoldingCalculation]
}
```

## ZakatCalculationMethod

### Description

Method used to calculate the zakatable amount and zakat due

### Values

| Enum Value | Description |
| --- | --- |
| `TREAT_AS_CASH` | Treat holding as cash. The zakat due is 2.5% of the asset market value. |
| `PASSIVE_INVESTMENT` | The zakat liable amount is determined using a formula that considers the asset outstanding shares and total assets The zakat due is 2.5% of ((sharesHeld / outstandingShares) * currentAssets) |
| `FALLBACK_30` | Fallback of calculating the zakat on 30% of the asset market value The zakat due is 2.5% of 30% of the asset market value. |

### Example

```graphql
"TREAT_AS_CASH"
```

## ZakatHolding

### Description

Input for zakat calculation of a holding

### Fields

| Input Field | Description |
| --- | --- |
| `symbol` - [`String`](https://developer.zoya.finance/docs#definition-String) | The symbol of the asset to calculate zakat for (e.g., "AAPL" or "AMD"). |
| `strategy` - [`ZakatHoldingStrategy!`](https://developer.zoya.finance/docs#definition-ZakatHoldingStrategy) | The strategy to use for calculating zakat on this holding. ACTIVE should be used for holdings that are intended to be actively traded and held for less than 1 year. PASSIVE should be used for holdings that are intended to be held for more than 1 year. |
| `quantity` - [`Float!`](https://developer.zoya.finance/docs#definition-Float) | The number of shares or units of the asset held. |
| `unitPrice` - [`Float!`](https://developer.zoya.finance/docs#definition-Float) | The unit price of the asset in the currency it is denominated in. |

### Example

```json
{
  "symbol": "xyz789",
  "strategy": "ACTIVE",
  "quantity": 123.45,
  "unitPrice": 987.65
}
```

## ZakatHoldingCalculation

### Description

The result of a zakat calculation for a single holding.

### Fields

| Field Name | Description |
| --- | --- |
| `symbol` - [`String`](https://developer.zoya.finance/docs#definition-String) | The symbol of the asset that was used for the zakat calculation. |
| `strategy` - [`ZakatHoldingStrategy!`](https://developer.zoya.finance/docs#definition-ZakatHoldingStrategy) | The strategy used for calculating zakat on this holding. |
| `currency` - [`String!`](https://developer.zoya.finance/docs#definition-String) | The ISO 4217 currency code for the asset. |
| `marketValue` - [`Float!`](https://developer.zoya.finance/docs#definition-Float) | The market value of the holding (quantity * unitPrice) |
| `zakatLiableAmount` - [`Float!`](https://developer.zoya.finance/docs#definition-Float) | The zakat liable amount for this holding. This will differ based on the zakat calculation strategy used for the holding. |
| `zakatDue` - [`Float!`](https://developer.zoya.finance/docs#definition-Float) | The zakat due for this holding. This will be 2.5% of the zakat liable amount. |
| `calculationMethod` - [`ZakatCalculationMethod!`](https://developer.zoya.finance/docs#definition-ZakatCalculationMethod) | The zakat calculation method ultimately used for this holding. Some assets have special handling rules, such as how precious metals spot funds are treated as cash for zakat purposes. In cases where reliable data is not available for outstanding shares or current assets, a fallback method of taking 30% of the market value as the zakat liable amount is used. |

### Example

```json
{
  "symbol": "abc123",
  "strategy": "ACTIVE",
  "currency": "xyz789",
  "marketValue": 123.45,
  "zakatLiableAmount": 987.65,
  "zakatDue": 987.65,
  "calculationMethod": "TREAT_AS_CASH"
}
```

## ZakatHoldingStrategy

### Description

Enum of different strategies to use for calculating zakat on a holding. Actively traded holdings get treated as cash while passive investments factor in the percentage of shares owned relative to the current assets held by an entity as the basis for determining the zakat liable amount.

### Values

| Enum Value | Description |
| --- | --- |
| `ACTIVE` | Should be used for holdings that are intended to be actively traded and held for less than 1 year. Active investments will be treated as cash for purposes of zakat calculation. |
| `PASSIVE` | Should be used for holdings that are intended to be held for more than 1 year. This approach factors in what percentage of a company you own and then looks at the proportional amount of current assets held by the company to determine the zakat liable amount. For ETFs and mutual funds, the calculation strategy is applied recursively over the holdings of the fund based on their weighted holdings. |

### Example

```graphql
"ACTIVE"
```

## ZakatQuery

### Description

Queries available for users with the zakat subscription package. Users

### Fields

| Field Name | Description |
| --- | --- |
| `calculate` - [`ZakatCalculation!`](https://developer.zoya.finance/docs#definition-ZakatCalculation) |  |
| Arguments `holdings` - [`[ZakatHolding!]!`](https://developer.zoya.finance/docs#definition-ZakatHolding) |  |

### Example

```json
{"calculate": ZakatCalculation}
```

Ready to build

Start against the sandbox, read `reportDate` before you display any status, then switch the endpoint and key prefix to go live. The [API Explorer](https://developer.zoya.finance/explorer) is the quickest way to shape a query, and [support@zoya.finance](mailto:support@zoya.finance) is the quickest way to get unstuck.