Zoya API Reference

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.

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 } } }"}'

{
  "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.

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. 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.

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.

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

https://api.zoya.finance/graphql

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. 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. 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.

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.

Current pricing for both packages is listed on your dashboard at developer.zoya.finance.

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.

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 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.

Example:

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

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

The API is modeled after the GraphQL 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.

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.

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".

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

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. On fund reports this field is restricted and returns null unless it has been enabled for your account — contact support if you need it.

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.

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

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.

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.

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.

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:

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.

{
  "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.

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.