Base URL
All API requests are made to your project's Supabase Edge Functions base URL:
https://your-project.supabase.co/functions/v1/
Replace your-project with your actual Supabase project reference. You can find this in Settings → Project Info.
Authentication
All API endpoints require authentication via an API key in the Authorization header:
Authorization: Bearer YOUR_API_KEY
Getting an API Key
Generate API keys from Settings → API Keys. See the API Keys & Authentication page for detailed instructions.
Key Scoping
API keys are scoped to a specific client account. All data returned by the API is automatically filtered to the client associated with the key. You cannot access data from other client accounts.
Lead Endpoints
Create Lead
POST /lead-webhook
Create a new lead. See Lead Ingestion Webhook for full payload details.
List Leads
GET /leads
Retrieve leads with optional filters:
| Parameter | Type | Description |
|---|---|---|
page | integer | Page number (default: 1) |
per_page | integer | Results per page (default: 50, max: 200) |
source | string | Filter by lead source |
disposition | string | Filter by current disposition |
created_after | ISO 8601 | Filter leads created after this date |
created_before | ISO 8601 | Filter leads created before this date |
search | string | Search by name, email, or phone |
Update Lead
PATCH /leads/:id
Update a lead's fields. Send only the fields you want to change:
{
"disposition": "qualified",
"custom_fields": {
"notes": "Spoke with lead, interested in premium plan"
}
}
Delete Lead
DELETE /leads/:id
Permanently delete a lead and all associated data. This action cannot be undone.
Conversion Endpoints
Send Conversion
POST /conversions/send
Manually trigger a conversion event for a lead, sending it to all connected ad platforms:
{
"lead_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"event_name": "Purchase",
"value": 499.99,
"currency": "USD"
}
| Field | Required | Description |
|---|---|---|
lead_id | Yes | The ID of the lead |
event_name | Yes | Conversion event name (must match platform event mapping) |
value | No | Monetary value of the conversion |
currency | No | Currency code (default: USD) |
Conversion History
GET /conversions/history
View all conversion events sent for a client account:
| Parameter | Type | Description |
|---|---|---|
lead_id | UUID | Filter by specific lead |
platform | string | Filter by platform (facebook, google, tiktok) |
status | string | Filter by status (sent, failed, pending) |
created_after | ISO 8601 | Filter by date |
Account Endpoints
Account Info
GET /account
Returns basic account information:
{
"id": "client-uuid",
"name": "Acme Corp",
"plan": "agency",
"created_at": "2026-01-15T00:00:00Z"
}
Usage Stats
GET /account/usage
Returns current billing period usage and plan limits:
{
"period_start": "2026-03-01",
"period_end": "2026-03-31",
"leads_received": 1250,
"leads_limit": 5000,
"conversions_sent": 340,
"conversions_limit": 2000,
"api_calls": 8500,
"api_calls_limit": 50000
}
Rate Limits
API requests are rate-limited to ensure fair usage and platform stability.
Limits
| Resource | Limit |
|---|---|
| All endpoints | 100 requests per minute per API key |
| Lead creation | 50 requests per minute per API key |
| Conversion sending | 30 requests per minute per API key |
Rate Limit Response
When you exceed the rate limit, the API returns:
HTTP 429 Too Many Requests
{
"error": "Rate limit exceeded",
"retry_after": 32
}
The Retry-After header and retry_after field indicate how many seconds to wait before retrying.
Best Practices
- Batch operations — When importing many leads, space requests at least 1 second apart
- Implement exponential backoff — On 429 responses, wait and retry with increasing delays
- Cache responses — Avoid redundant API calls by caching data locally when possible