Authentication & Required Headers
Every API call must provide the target workspace identifier in the request headers.
| Header | Type | Example Value | Description |
|---|---|---|---|
x-workspace-id |
String (Required) | ws_acme |
Selects the client workspace tenant context. |
Authorization |
String (Required in prod) | Bearer os_live_xxxxxx |
Workspace API key or user session JWT. |
Content-Type |
String | application/json |
JSON request format. |
1. Workspaces Endpoint
Retrieve all accessible workspaces under the user's agency organization.
GET /api/workspaces
Example Request (cURL)
curl -X GET http://localhost:3000/api/workspaces \
-H "Authorization: Bearer os_live_xxxxxx"
Example Response (200 OK)
{
"workspaces": [
{
"id": "ws_acme",
"name": "Acme Growth Corp",
"slug": "acme-growth",
"role": "AGENCY_ADMIN",
"mailbox_count": 8,
"active_campaigns": 3,
"health_score": 98.4
},
{
"id": "ws_globex",
"name": "Globex International",
"slug": "globex-intl",
"role": "ACCOUNT_MANAGER",
"mailbox_count": 5,
"active_campaigns": 2,
"health_score": 96.1
}
]
}2. Leads Management Endpoints
Query, filter, create, and bulk-import prospects with waterfall enrichment status.
GET /api/leads
Returns paginated leads scoped to the header workspace.
Example Request
curl -X GET "http://localhost:3000/api/leads?status=verified&limit=50" \
-H "x-workspace-id: ws_acme"POST /api/leads/import
Bulk imports prospects with deduplication against existing workspace contacts.
JSON Body Payload
{
"leads": [
{
"first_name": "Elena",
"last_name": "Rostova",
"email": "elena.rostova@vertexdata.io",
"company": "Vertex Data Systems",
"title": "VP of Revenue Operations",
"domain": "vertexdata.io",
"linkedin_url": "https://linkedin.com/in/elena-rostova",
"signal_trigger": "Hiring 4 SDRs in Q4"
}
],
"auto_enrich": true,
"campaign_id": "cmp_q4_outbound"
}3. AI Copilot & Reply Generation
Generate contextual, grounded reply drafts using OpenRouter multi-tiered LLM routing.
POST /api/inbox/reply
JSON Body Payload
{
"lead_id": "lead_9812",
"incoming_message": "Thanks for reaching out! We are currently evaluating alternatives to ZoomInfo. What is your pricing structure?",
"lead_name": "Marcus Vance",
"company_name": "Nova Cloud Solutions",
"tone": "consultative_professional"
}
Response (200 OK)
{
"draft": "Hi Marcus,\n\nThanks for your note. Our pricing scales directly with verified contact volume rather than annual platform seat fees, which typically cuts outbound data costs by 40% compared to legacy enterprise databases.\n\nAre you free for a 15-minute screen share this Thursday at 2:00 PM EST to review a tailored pricing breakdown for Nova Cloud?\n\nBest,\nAlex",
"classification": "interested",
"requires_review": false,
"confidence": 0.94,
"model_used": "openai/gpt-4o-mini"
}4. Human Review Queue Actions
Approve, reject, or edit drafts held in the Human-In-The-Loop safety gate.
PATCH /api/review-queue
JSON Body Payload (Approve or Reject)
{
"review_id": "rev_5401",
"action": "APPROVE",
"edited_content": null,
"rejection_reason": null
}5. Outbound Webhook Subscriptions
Subscribe your CRM (HubSpot, Salesforce) or internal Slack channel to real-time events.
| Event Type | Trigger Moment | Payload Highlight |
|---|---|---|
lead.discovered |
Lead passes ICP precision score (≥ 0.85) | lead_id, company, icp_score, signals |
email.sent |
Email clears 7-Point Gate and dispatches via SMTP | campaign_id, mailbox_id, message_id |
email.bounced |
SMTP bounce notification received | bounce_type (hard|soft), error_code |
reply.classified |
Prospect reply categorized by AI | category (interested|objection|etc), sentiment |
meeting.booked |
Prospect confirms meeting slot via calendar link | booking_time, meeting_brief_url |