API Reference

Complete reference for the Orwel API

Base URL

All API requests should be made to:

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

Authentication

Include your API key in every request using the Authorization header:

Authorization: Bearer YOUR_API_KEY

See the Authentication guide for more details.

Available Resources

Leads

Manage and track leads in your workspace

Users

Access workspace members and their information

Identities

Manage visitor identities and their traits

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

200 · OK

Request succeeded

201 · Created

Resource created successfully

400 · Bad Request

Invalid request parameters

401 · Unauthorized

Invalid or missing API key

403 · Forbidden

Access denied to resource

404 · Not Found

Resource not found

429 · Too Many Requests

Rate limit exceeded

500 · Internal Server Error

Server error

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=[e-mail]&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

JavaScript/TypeScript

Coming soon

Python

Coming soon

PHP

Coming soon

Ruby

Coming soon

Need Help?

Support

Email our support team

Community

Join our Slack community