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_...) and the development key (orwel_dev_...) only send data and are rejected here. See API keys and authentication.

Available Resources

Leads

Manage and track leads in your workspace

Users

Access workspace members and their information

Identities

Manage visitor identities and their traits

Companies

Companies enriched from your leads

Visitor Lists

Segments of visitors

Conversions

Every conversion with its lead, to sync without duplicates

Campaigns

Ad campaigns with cost, clicks and conversions

Reports

Metrics and a written analysis for a date range

Scopes per endpoint

Endpoint	Scope
`GET /leads`, `GET /leads/{id}`	`leads:read`
`POST /leads`, `PATCH /leads/{id}`	`leads:write`
`GET /users`, `GET /users/{id}`	`leads:read`
`GET /identities`, `GET /identities/{id}`, `/activity`, `/personalities`	`visitors:read`
`POST /identities`, `PATCH /identities/{id}`	`leads:write`
`GET /companies`, `GET /companies/{id}`	`companies:read`
`GET /lists`	`visitors:read`
`GET /conversions`, `GET /conversions/{id}`	`conversions:read`
`GET /campaigns`	`campaigns:read`
`POST /reports`	`leads:read` + `visitors:read` + `conversions:read`

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

Request succeeded

Created

Resource created successfully

Bad Request

Invalid request parameters

Unauthorized

Invalid or missing API key

Forbidden

The key lacks the scope (insufficient_scope), the browser origin is not allowed (origin_not_allowed), or the plan does not include the feature (plan_not_allowed). See Errors.

Not Found

Resource not found

Too Many Requests

Rate limit exceeded

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

JavaScript/TypeScript

Coming soon

Python

Coming soon

PHP

Coming soon

Ruby

Coming soon

Need Help?

Support

Email the Orwel team

Book a session

30 minutes to review your setup

​Base URL

​Authentication

​Available Resources

Leads

Users

Identities

Companies

Visitor Lists

Conversions

Campaigns

Reports

​Scopes per endpoint

​Request Format

​Response Format

​Success Response

​Error Response

​HTTP Status Codes

​Pagination

​Filtering

​Rate Limiting

​Timestamps

​UUIDs

​JSONB Fields

​Workspace Scoping

​SDKs and Libraries

JavaScript/TypeScript

Python

PHP

Ruby

​Need Help?

Support

Book a session

Base URL

Authentication

Available Resources

Scopes per endpoint

Request Format

Response Format

Success Response

Error Response

HTTP Status Codes

Pagination

Filtering

Rate Limiting

Timestamps

UUIDs

JSONB Fields

Workspace Scoping

SDKs and Libraries

Need Help?