API Reference

Welcome to the Islamic Open Finance™ API Reference. This documentation covers all available endpoints across our 144 specialized rails with 900+ endpoints.

Base URL

All API requests should be made to:

Environment	Base URL
Production	`https://api.islamicopenfinance.com/api/v1`
Sandbox	`https://sandbox.islamicopenfinance.com/api/v1`
UAT	`https://uat.islamicopenfinance.com/api/v1`

Authentication

All API requests require authentication using an API key:

curl https://api.islamicopenfinance.com/api/v1/contracts \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: tenant_123" \
  -H "X-Workspace-ID: ws_456"

See Authentication for more details including OAuth 2.0 and SAML flows.

Request Format

All requests must use HTTPS
Request bodies should be JSON encoded
Include Content-Type: application/json header
Include tenant and workspace headers for multi-tenant operations

Required Headers

Header	Description	Required
`Authorization`	Bearer token or API key	Yes
`Content-Type`	`application/json`	Yes
`X-Tenant-ID`	Tenant identifier	Yes
`X-Workspace-ID`	Workspace identifier	Context-dependent
`X-Idempotency-Key`	Idempotency key for writes	Recommended
`X-Request-ID`	Request tracking ID	Optional

Response Format

All responses are JSON encoded with consistent structure:

{
  "data": { ... },
  "meta": {
    "requestId": "req_abc123def456",
    "timestamp": "2025-01-15T10:30:00Z",
    "rail": "contracts",
    "version": "v1"
  }
}

For list endpoints with pagination:

{
  "data": [ ... ],
  "meta": {
    "requestId": "req_abc123def456",
    "timestamp": "2025-01-15T10:30:00Z"
  },
  "pagination": {
    "page": 1,
    "perPage": 20,
    "total": 150,
    "totalPages": 8,
    "hasMore": true
  }
}

Available Rails

Core Business Rails

Rail	Description	Endpoints	Status
Contracts	Islamic financial contracts lifecycle	25+	Stable
KYC	Customer verification & identity	18+	Stable
Compliance	Regulatory compliance & policy enforcement	15+	Stable
AML	Anti-money laundering & sanctions screening	12+	Stable
Zakat	Zakat calculation & distribution	10+	Stable

Financial Rails

Rail	Description	Endpoints	Status
Treasury	Position & liquidity management	20+	Stable
Clearing	Settlement & clearing operations	15+	Stable
Portfolio	Portfolio management & NAV	14+	Stable
Risk	Risk assessment & management	12+	Stable
Limits	Financial limits & transaction controls	10+	Stable
Underwriting	Risk underwriting & evaluation	12+	Stable

Payments & Routing Rails

Rail	Description	Endpoints	Status
Routing	Payment routing & rules	10+	Stable
Messages	ISO 20022, SWIFT messaging	15+	Stable
Reconciliation	Transaction reconciliation	12+	Stable

Governance & Legal Rails

Rail	Description	Endpoints	Status
Governance	Shariah board & governance	12+	Stable
Legal	Legal document management	10+	Stable
Disputes	Dispute resolution	10+	Stable
Cases	Case management & workflows	12+	Stable

Identity & Access Rails

Rail	Description	Endpoints	Status
Auth	Authentication & sessions	15+	Stable
OAuth2	OAuth 2.0 / OpenID Connect	12+	Stable
SAML	Enterprise SAML 2.0 SSO	8+	Stable
Consent	Privacy & consent management	10+	Stable
API Keys	API key management	8+	Stable

Integration & Events Rails

Rail	Description	Endpoints	Status
Webhooks	Event notifications & delivery	10+	Stable
Events	Event distribution & replay	8+	Stable
Notifications	Multi-channel notifications	10+	Stable
Integrations	External connectors & sync	12+	Stable

Infrastructure Rails

Rail	Description	Endpoints	Status
Analytics	Real-time analytics & dashboards	12+	Stable
Reporting	Regulatory & custom reports	10+	Stable
Search	Full-text search	6+	Stable
Billing	Usage metering & invoicing	12+	Stable
Audit	Audit trails & compliance logs	8+	Stable
Observability	SLO tracking & monitoring	10+	Stable

SKU Tiers

Islamic Open Finance™ offers seven pricing tiers for different organizational needs. See SKU Tiers for complete comparison and features.

Tier	Monthly	Annual	API Calls	Users	SLA
Starter	$499	$4,990	10K	10	99.5%
Analytics Only	$799	$7,990	25K	15	99.5%
Fintech	$999	$9,990	50K	25	99.9%
Growth	$1,999	$19,990	100K	50	99.9%
Compliance Plus	$2,999	$29,990	75K	30	99.9%
Enterprise	$9,999	$99,990	Unlimited	Unlimited	99.99%
Core Banking	$24,999	$249,990	Unlimited	Unlimited	99.999%

Rate Limits

API requests are rate limited based on your SKU:

SKU	Requests/minute	Requests/month	Burst
Starter	167	10,000	500
Fintech	834	50,000	1,000
Growth	1,667	100,000	2,500
Compliance Plus	1,250	75,000	1,875
Enterprise	10,000	Unlimited	20,000
Core Banking	20,000	Unlimited	50,000

Rate limit headers are included in every response:

X-RateLimit-Limit: 1200
X-RateLimit-Remaining: 1198
X-RateLimit-Reset: 1705312800
X-RateLimit-Policy: growth

Errors

All errors follow a consistent format:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "details": [
      {
        "field": "amount",
        "message": "Amount must be positive",
        "code": "INVALID_VALUE"
      }
    ],
    "rail": "contracts",
    "requestId": "req_abc123"
  },
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2025-01-15T10:30:00Z"
  }
}

Common Error Codes

Code	HTTP Status	Description
`VALIDATION_ERROR`	400	Invalid request parameters
`AUTHENTICATION_ERROR`	401	Invalid or missing credentials
`AUTHORIZATION_ERROR`	403	Insufficient permissions
`NOT_FOUND`	404	Resource not found
`CONFLICT`	409	Resource conflict
`RATE_LIMITED`	429	Too many requests
`INTERNAL_ERROR`	500	Server error
`SHARIAH_VIOLATION`	422	Shariah compliance check failed

See Errors for the complete error code reference.

Versioning

The API is versioned via the URL path. The current version is v1:

https://api.islamicopenfinance.com/api/v1/contracts

API changes follow semantic versioning:

Breaking changes require new version (v2, v3)
New features are additive within version
Deprecations announced 6 months in advance

Idempotency

For POST/PUT/PATCH requests, include an idempotency key:

curl -X POST https://api.islamicopenfinance.com/api/v1/contracts \
  -H "Authorization: Bearer sk_live_..." \
  -H "X-Idempotency-Key: unique-request-id-123" \
  -d '{"type": "murabaha", ...}'

Idempotency keys are valid for 24 hours.

Webhooks

Subscribe to events via webhooks for real-time notifications:

// Event types available
contract.created;
contract.activated;
contract.terminated;
kyc.completed;
kyc.expired;
compliance.check.passed;
compliance.check.failed;
payment.completed;
payment.failed;

See Webhooks for setup and event catalog.

SDKs

Official SDKs are available for:

SDK	Version	Status
TypeScript/JavaScript	2.0.0	Stable
Python	2.0.0	Stable
Go	1.0.0	Preview

OpenAPI Specification & Interactive Documentation

The complete OpenAPI 3.1 specification is served directly from the Rail API:

Environment	OpenAPI Spec URL	Swagger UI
Production	`GET /api/v1/docs/openapi.json`	`/api/v1/docs/`
Sandbox	`GET /api/v1/docs/openapi.json`	`/api/v1/docs/`

Interactive API Tools

For interactive API exploration and testing, use our dedicated tools:

API Explorer - Full-featured API testing with code snippets (curl, JavaScript, Python)
Developer Portal - SDKs, quickstarts, and authentication setup
Sandbox Environment - Safe testing environment with test data

::: tip API Explorer Features The API Explorer provides environment switching (sandbox/UAT/production), request history, rate limit monitoring, and automatic code generation for all 800+ endpoints across 80 rails. :::

Next Steps

Getting Started - Quick start guide
Authentication - Auth setup
SKU Tiers - Pricing and feature comparison
Registries - Platform registries and metadata
Entitlements - Feature entitlements and usage tracking
Environments - Deployment environments
Rails & SKUs - Understanding rails
Webhooks - Event notifications