API Reference

Welcome to the Islamic Open Finance™ API Reference. This documentation covers all available endpoints across our 89 specialized rails powered by 178 engine packages with 150 API routes.

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

Rate Limits

All API requests are rate-limited. Exact limits depend on your plan — see Rate Limits for technical details.

Rate limit headers are included in every response:

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

Note: For pricing and plan features, see https://islamicopenfinance.com/pricing. API reference documentation covers endpoints and technical behaviour only.

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 150 API routes across 89 rails. :::

Next Steps

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