API Reference

Base URL

All API requests should be made to:

https://api.orwel.io/api/v1

Authentication

Call the API with an API key (orwel_sk_...) created in Settings, API keys, sent as a Bearer token:

Authorization: Bearer orwel_sk_YOUR_KEY

Each key carries scopes (leads:read, visitors:read, companies:read, campaigns:read, conversions:read, leads:write, lists:write, mcp) and either a list of allowed origins or server only access. The production API key that the SDK uses (orwel_pk_...) and the development key (orwel_dev_...) only send data and are rejected here. See API keys and authentication.

Available Resources

Request Format

All POST and PATCH requests should include a Content-Type: application/json header and a JSON body.

curl -X POST "https://api.orwel.io/api/v1/leads" \
  -H "Authorization: Bearer orwel_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code": "lead_001", "source": "website"}'

Response Format

All responses are returned in JSON format with the following structure:

Success Response

{
  "data": { ... },
  "pagination": { ... }  // Only for list endpoints
}

Error Response

{
  "error": "error_code",
  "message": "Human readable error message",
  "details": { ... }  // Optional additional context
}

HTTP Status Codes

Pagination

List endpoints support pagination using limit and offset parameters:

GET /api/v1/leads?limit=50&offset=100

Response includes pagination metadata:

{
  "data": [...],
  "pagination": {
    "limit": 50,
    "offset": 100,
    "total": 500
  }
}

Limits:

• Default: 50 items
• Maximum: 100 items per request

Filtering

Many endpoints support filtering via query parameters:

# Filter leads by source
GET /api/v1/leads?source=website

# Filter by date range
GET /api/v1/leads?created_after=2025-01-01T00:00:00Z&created_before=2025-01-31T23:59:59Z

# Combine filters
GET /api/v1/identities?email=user@example.com&is_favorite=true

Rate Limiting

All requests are subject to rate limiting. Check the response headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1642252800

See Rate Limiting for details.

Timestamps

All timestamps are in ISO 8601 format with UTC timezone:

2025-01-15T10:30:00Z

UUIDs

All resource IDs are UUIDs in the format:

550e8400-e29b-41d4-a716-446655440000

JSONB Fields

Some fields accept arbitrary JSON objects (properties, traits, etc.):

{
  "properties": {
    "custom_field": "value",
    "nested": {
      "data": true
    }
  }
}

Workspace Scoping

All API requests are automatically scoped to your workspace. You can only access data that belongs to your organization.

The workspace ID is included in response headers:

X-Workspace-Id: 770e8400-e29b-41d4-a716-446655440002

SDKs and Libraries

Need Help?