Developer Platform

Stocks

List screened NGX and NASD securities.

Portfolio scoring

Analyze holdings and purification amounts.

Reports

Retrieve compliance reports for equities.

Usage

Monitor daily quota and API key activity.

Getting started

Authenticate with X-API-Key

Every external API request requires an API key in the X-API-Key header. Sandbox keys use sk_test_ and production keys use sk_live_.

Key formats

sk_test_

Sandbox key for development and testing.

sk_live_

Production key for live data access.

Never expose API keys in browser code, public repositories, or client-side requests. Keep requests on your server.

cURL

curl "https://api.toyyib.app/api/v1/securities/compliance?exchange=NGX&page_size=50" \
  -H "X-API-Key: sk_test_your_key_here"

Traffic controls

Rate limits are enforced per API key

Responses include rate-limit headers so your application can display remaining quota and back off gracefully.

X-RateLimit-Limit

Maximum requests in the current window

X-RateLimit-Remaining

Requests remaining in the window

X-RateLimit-Reset

UTC timestamp when the window resets

Retry-After

Seconds to wait after a 429 response

Error handling

Predictable JSON errors

The API uses standard HTTP status codes and wraps validation, authentication, authorization, and server errors in a consistent shape.

400VALIDATION_ERRORInvalid request parameters

401INVALID_API_KEYMissing or invalid API key

409AMBIGUOUS_IDENTIFIERQualify the symbol with exchange or EXCHANGE:TICKER

403FEATURE_UNAVAILABLEFeature unavailable for this key

404NOT_FOUNDResource does not exist

429RATE_LIMIT_EXCEEDEDToo many requests

500INTERNAL_ERRORUnexpected server error

Error format

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The API key provided is invalid or has been revoked.",
    "details": {}
  }
}

GET/api/v1/securities/{symbol}/complianceLive

Securities

Single Security Compliance

Retrieve the headline Shariah compliance status for one screened security. Use the exchange query or an EXCHANGE:TICKER symbol when a ticker exists on more than one market.

Parameters

symbol

path string

Ticker, UUID, or exchange-qualified symbol, for example DANGCEM or NGX:DANGCEM.

exchange

query string

Optional exchange code such as NGX or NASD. Used to disambiguate bare tickers.

curl

curl "https://api.toyyib.app/api/v1/securities/DANGCEM/compliance?exchange=NGX" \
  -H "X-API-Key: sk_test_your_key_here"

Response

{
  "success": true,
  "data": {
    "symbol": "DANGCEM",
    "name": "Dangote Cement Plc",
    "exchange": "NGX",
    "status": "COMPLIANT",
    "report_date": "2026-05-31T00:00:00Z"
  },
  "message": "Security compliance retrieved successfully"
}

GET/api/v1/securities/compliantLive

Securities

List Compliant Securities

Retrieve screened securities whose status is COMPLIANT. This is a convenience endpoint over the main compliance list.

Parameters

exchange

query string

Optional exchange code. Omit to include all active markets.

sector

query string

Filter by sector name, case-insensitive.

page_size

query integer

Items per page. Defaults to 50; maximum is 200.

next_token

query string

Opaque cursor returned by the previous page.

curl

curl "https://api.toyyib.app/api/v1/securities/compliant?exchange=NGX&page_size=50" \
  -H "X-API-Key: sk_test_your_key_here"

Response

{
  "success": true,
  "data": {
    "items": [
      {
        "symbol": "DANGCEM",
        "name": "Dangote Cement Plc",
        "exchange": "NGX",
        "status": "COMPLIANT",
        "report_date": "2026-05-31T00:00:00Z",
        "purification_ratio": 0.19
      }
    ],
    "next_token": "cD0yMDI2LTA1LTMx..."
  },
  "message": "Securities retrieved successfully"
}

GET/api/v1/securities/complianceLive

Securities

List Securities Compliance

Retrieve paginated basic compliance reports for all screened securities across NGX, NASD, or every active exchange.

Parameters

exchange

query string

Filter by exchange code such as NGX or NASD. Omit for all.

status

query string

Filter by COMPLIANT, NON_COMPLIANT, or QUESTIONABLE.

sector

query string

Filter by sector name, case-insensitive.

page_size

query integer

Items per page. Defaults to 50; maximum is 200.

next_token

query string

Opaque cursor returned by the previous page.

curl

curl "https://api.toyyib.app/api/v1/securities/compliance?exchange=NGX&status=COMPLIANT&page_size=50" \
  -H "X-API-Key: sk_test_your_key_here"

Response

{
  "success": true,
  "data": {
    "items": [
      {
        "symbol": "DANGCEM",
        "name": "Dangote Cement Plc",
        "exchange": "NGX",
        "status": "COMPLIANT",
        "report_date": "2026-05-31T00:00:00Z",
        "purification_ratio": 0.19
      },
      {
        "symbol": "TRANSCORP",
        "name": "Transnational Corporation Plc",
        "exchange": "NGX",
        "status": "QUESTIONABLE",
        "report_date": "2026-05-31T00:00:00Z",
        "purification_ratio": 2.74
      }
    ],
    "next_token": null
  },
  "message": "Securities retrieved successfully"
}

GET/api/v1/securities/{symbol}/reportLivePro and Enterprise

Securities

Full Shariah Compliance Report

Retrieve the advanced compliance report for one screened security, including business and financial screens, revenue breakdown, and AAOIFI screening ratios.

Parameters

symbol

path string

Ticker, UUID, or exchange-qualified symbol, for example DANGCEM or NGX:DANGCEM.

exchange

query string

Optional exchange code such as NGX or NASD. Used to disambiguate bare tickers.

curl

curl "https://api.toyyib.app/api/v1/securities/DANGCEM/report?exchange=NGX" \
  -H "X-API-Key: sk_live_your_pro_key"

Response

{
  "success": true,
  "data": {
    "symbol": "DANGCEM",
    "raw_symbol": "DANGCEM",
    "name": "Dangote Cement Plc",
    "exchange": "NGX",
    "sector": "Industrial Goods",
    "currency": "NGN",
    "status": "COMPLIANT",
    "business_screen": "COMPLIANT",
    "financial_screen": "COMPLIANT",
    "screening_standard": "AAOIFI",
    "report_date": "2026-05-31T00:00:00Z",
    "compliant_revenue": 99.81,
    "non_compliant_revenue": 0.19,
    "questionable_revenue": 0,
    "securities_to_market_cap_ratio": 0.041,
    "debt_to_market_cap_ratio": 0.0721
  },
  "message": "Compliance report retrieved successfully"
}

GET/api/v1/etfs/complianceComing soon

ETFs

List ETF Compliance Reports

Planned endpoint for ETF-level Shariah compliance derived from underlying holdings. This route is documented for integration planning but is not implemented in the backend yet.

Parameters

exchange

query string

Filter by exchange code such as NGX.

status

query string

Filter by COMPLIANT, NON_COMPLIANT, or QUESTIONABLE.

page_size

query integer

Planned items per page. Default 50; maximum 200.

next_token

query string

Planned opaque cursor returned by the previous page.

curl

curl "https://api.toyyib.app/api/v1/etfs/compliance?exchange=NGX&page_size=50" \
  -H "X-API-Key: sk_test_your_key_here"

Response

{
  "success": true,
  "data": {
    "items": [
      {
        "symbol": "LOTUSHAL15",
        "name": "Lotus Halal Equity ETF",
        "exchange": "NGX",
        "status": "COMPLIANT",
        "compliant_holdings": 100,
        "non_compliant_holdings": 0,
        "questionable_holdings": 0,
        "report_date": "2026-05-31T00:00:00Z"
      }
    ],
    "next_token": null
  },
  "message": "ETF compliance reports retrieved successfully"
}

GET/api/v1/exchangesLive

Markets

List Exchanges

Retrieve the active exchanges and OTC markets supported by Toyyib. This replaces the original /regions design in the PDF.

Parameters

This endpoint takes no parameters.

curl

curl "https://api.toyyib.app/api/v1/exchanges" \
  -H "X-API-Key: sk_test_your_key_here"

Response

{
  "success": true,
  "data": {
    "items": [
      {
        "code": "NGX",
        "name": "Nigerian Exchange",
        "type": "EXCHANGE"
      },
      {
        "code": "NASD",
        "name": "NASD OTC Securities Exchange",
        "type": "OTC"
      }
    ]
  },
  "message": "Exchanges retrieved successfully"
}

POST/api/v1/portfolio/analyzeLive

Portfolio

Analyze Portfolio

Submit holdings and receive portfolio-level compliance scoring, value breakdowns, and purification amounts.

Parameters

holdings

array

One to fifty holdings, with no duplicate tickers.

holdings[].ticker

string

Ticker symbol, case-insensitive.

holdings[].shares

number

Number of shares held. Minimum 1.

curl

curl -X POST "https://api.toyyib.app/api/v1/portfolio/analyze" \
  -H "X-API-Key: sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "holdings": [
      {"ticker": "DANGCEM", "shares": 500},
      {"ticker": "BUACEMENT", "shares": 200}
    ]
  }'

Response

{
  "success": true,
  "data": {
    "summary": {
      "total_value": 1250000.0,
      "compliance_score": 72,
      "compliance_status": "doubtful",
      "total_purification_amount": 1523.45,
      "holdings_count": 2,
      "analyzed_at": "2026-04-12T10:30:00Z"
    },
    "holdings": [
      {
        "ticker": "DANGCEM",
        "value": 125000.0,
        "weight": 10.0,
        "compliance_status": "compliant",
        "purification_amount": 0.0
      }
    ]
  },
  "message": "Portfolio analysis completed successfully"
}

GET/api/v1/reportsLivePro and Enterprise

Reports

List Reports

Retrieve paginated compliance reports.

Parameters

type

string

Filter by monthly, quarterly, or special.

page

integer

Page number.

curl

curl "https://api.toyyib.app/api/v1/reports?type=quarterly&page=1" \
  -H "X-API-Key: sk_live_your_pro_key"

Response

{
  "success": true,
  "data": {
    "reports": [
      {
        "id": "019432b2-...",
        "title": "Q1 2026 Compliance Report",
        "type": "quarterly",
        "created_at": "2026-01-15T00:00:00Z"
      }
    ]
  },
  "message": "Reports retrieved successfully"
}

GET/api/v1/reports/statsLivePro and Enterprise

Reports

Report Statistics

Get report generation and download statistics, including upcoming report schedules.

Parameters

This endpoint takes no parameters.

curl

curl "https://api.toyyib.app/api/v1/reports/stats" \
  -H "X-API-Key: sk_live_your_pro_key"

Response

{
  "success": true,
  "data": {
    "total_reports_generated": 24,
    "total_downloads": 156,
    "report_schedule": [
      {
        "type": "monthly",
        "description": "Generated on the 15th of each month",
        "next_report_date": "2026-03-15T00:00:00"
      }
    ]
  },
  "message": "Report statistics retrieved successfully"
}

GET/api/v1/reports/{report_id}/downloadLiveEnterprise

Reports

Download Report

Get a download URL for a specific compliance report.

Parameters

report_id

uuid

The report unique identifier.

curl

curl "https://api.toyyib.app/api/v1/reports/019432b2-.../download" \
  -H "X-API-Key: sk_live_your_enterprise_key"

Response

{
  "success": true,
  "data": {
    "download_url": "https://api.toyyib.app/media/reports/q1-2026.pdf",
    "file_name": "Q1 2026 Compliance Report.pdf",
    "file_size": 245760
  },
  "message": "Download URL generated successfully"
}

GET/api/v1/usageLive

Account

API Usage

Check current API key usage and rate-limit status.

Parameters

This endpoint takes no parameters.

curl

curl "https://api.toyyib.app/api/v1/usage" \
  -H "X-API-Key: sk_test_your_key_here"

Response

{
  "success": true,
  "data": {
    "key": {
      "prefix": "sk_test_abc12345",
      "name": "My Dev Key",
      "mode": "sandbox",
      "is_active": true,
      "last_used_at": "2026-04-12T10:29:31Z"
    },
    "plan": {
      "name": "Pro",
      "tier": "pro",
      "allows_reports_access": true,
      "allows_export": false
    },
    "usage": {
      "daily_limit": 1000,
      "daily_used": 142,
      "daily_remaining": 858,
      "per_minute_limit": 30
    }
  },
  "message": "Usage data retrieved successfully"
}

Ready to add Shariah compliance to your platform?

Talk to the Halcore team about API keys, sandbox access, and business onboarding.

Schedule a demo Back to Toyyib

Add Shariah security screening to your product.

Stocks

Portfolio scoring

Reports

Usage

Authenticate with X-API-Key

Key formats

Rate limits are enforced per API key

Predictable JSON errors

Single Security Compliance

Parameters

List Compliant Securities

Parameters

List Securities Compliance

Parameters

Full Shariah Compliance Report

Parameters

List ETF Compliance Reports

Parameters

List Exchanges

Parameters

Analyze Portfolio

Parameters

List Reports

Parameters

Report Statistics

Parameters

Download Report

Parameters

API Usage

Parameters

Ready to add Shariah compliance to your platform?