REST API (API keys)

This is the complete REST API surface. Every endpoint lives under /api/v1 (plus a friendly unversioned alias for lead CRUD), authenticates with an API key, and enforces one scope per route.

All requests need:

Authorization: Bearer lh_yourKeyHere
Accept: application/json

List responses use the pagination envelope (data + meta + links); single-record responses are {"data": {...}}; errors follow Error codes & handling.

Who this is for#

• Developer — integrating a system, no-code tool or script against the CRM.
• Admin — checking which scope a key needs before creating it.

Prerequisites: an API key with the relevant scopes (Authentication).

Health#

Leads#

Scopes: read:leads, write:leads, delete:leads.

List filters (query string): source, status, pipeline_id, stage_id, assigned_user_id, tag (name), search (matches first/last name, email, phone), created_after, created_before, starred=1, sort (one of created_at, updated_at, lead_score, first_name, last_name, email; default created_at), direction (asc/desc, default desc), per_page (default 15, max 100).

Create body (real fields):

{
  "first_name": "Aarav",
  "last_name": "Shah",
  "email": "aarav@example.com",
  "phone": "+91 98xxxxxx21",
  "source": "api",
  "status": "new",
  "pipeline_id": 1,
  "pipeline_stage_id": 4,
  "assigned_user_id": 7,
  "notes": "Interested in the 3BHK project",
  "custom_fields": { "budget": "80L" },
  "tags": ["website", "hot"]
}

first_name is required; email max 255, phone max 50, source/status max 80/50. pipeline_id, pipeline_stage_id and assigned_user_id are validated to belong to this workspace (cross-tenant ids fail 422).

Tag attach body: {"tags": ["hot", "mumbai"]} → {"data": [...], "message": "2 tag(s) attached."}. Tag detach accepts an id or a name in the URL segment.

Unversioned aliases#

The same lead CRUD is also exposed without the version prefix for tools that mishandle 308 redirects: GET/POST /api/leads, GET/PUT/PATCH/DELETE /api/leads/{id}, POST /api/leads/{id}/tags, DELETE /api/leads/{id}/tags/{tag}. Same scopes, same behaviour.

Pipelines & stages#

Scopes: read:pipelines, write:pipelines (stage routes are covered by the pipelines scope).

Tags#

Scopes: read:tags, write:tags.

Users#

Scopes: read:users, write:users, delete:users.

Forms#

Scopes: read:forms, write:forms, delete:forms.

Automations#

Scopes: read:automations, write:automations, delete:automations.

Integrations#

Scopes: read:integrations, write:integrations (write covers create, update and delete).

Documentation endpoints (no auth)#

Public (token/anon) endpoints — outside /api/v1#

Most authenticate by URL token or provider signature; inbound lead intake instead uses a Bearer tenant API key. They are documented in full on Webhook endpoints.

Inbound lead intake: authenticate with the workspace's tenant API key as a Bearer token and name the same workspace in ?tenant={slug} — a missing key returns 401, an unknown or inactive tenant slug 404, and a key that does not match that tenant 401. email is required; accepted fields: first_name, last_name, phone, company, source, notes, tags[], custom_fields. A new lead returns 201 {"status":"created","lead_id":...}; an email that already exists returns 200 {"status":"duplicate","lead_id":...}.

Version fallback behaviour#

Any other /api/<path> request is 308-redirected to /api/v1/<path> (method and body preserved). Paths whose first segment is already a root surface (v1, docs, documentation, swagger, leads, inbound, webhook, webhooks, forms, messaging, voice) are excluded and return JSON 404 {"status":"error","message":"Endpoint not found.","code":"NOT_FOUND"}.

Common mistakes#

• Requesting /api/v1/leads/{id} with a lead id from another workspace — returns 404 by design.
• Sending status as an array — it is a string filter here.
• Using PUT with partial data — PUT validates like PATCH (sometimes rules), but send the full object when in doubt.
• Forgetting Accept: application/json — Laravel then renders HTML error pages that break JSON parsers (message parsing still works, but use the header).

Troubleshooting#

Technical details#

• Routes: routes/api.php; controllers: App\Http\Controllers\Api\V1\*.
• Resources: App\Http\Resources\Api\{LeadResource, TagResource, ApiResource}.
• Scope middleware: api.key:<scope> → App\Http\Middleware\ApiKeyAuthentication.
• Exact validation rules live in each controller (LeadController, PipelineController, StageController, TagController, UserController, FormController, AutomationController, IntegrationController).

Related guides#

• API overview
• Authentication
• Error codes & handling
• Mobile API (device tokens)
• Webhook endpoints