API overview

Zodiac Tech CRM exposes two separate HTTP APIs:

They share the same Laravel application but have different auth, different response envelopes and different rate limits. Pick the one that matches your client:

• A server syncing leads in and out → REST API (REST API (API keys)).
• The Android app installed on a sales agent's phone → Mobile API (Mobile API (device tokens)).
• External platforms calling you (Meta, WhatsApp, Razorpay, Twilio) → webhooks (Webhook endpoints).

Who this is for#

• Developer — building an integration against the REST API or debugging the mobile app's traffic.
• Admin — creating and scoping API keys for your workspace.
• Super-admin — monitoring API health and platform-level rate limits.

Prerequisites: a working install (see Go-live checklist) reachable over HTTP(S).

Base URLs#

The exact base URL depends on how the install is deployed. When the domain's document root points at the public/ folder (the recommended setup on cPanel), there is no subfolder in the URLs:

Production:   https://crm.zodiactechsoft.in/api/v1          (REST)
              https://crm.zodiactechsoft.in/api/v1/mobile/  (Mobile)

If the app runs inside a subfolder — for example the XAMPP development install at http://localhost/Lead%20Hub/, where the root .htaccess bridge forwards requests into public/ — the subfolder is part of the path:

Local dev:    http://localhost/Lead%20Hub/api/v1
              http://localhost/Lead%20Hub/api/v1/mobile/

Versions#

The API version is read from config('leadhub.api_version'), set by the LEADHUB_API_VERSION environment variable (default v1). The canonical surface is /api/v1/*.

Two compatibility behaviours exist for convenience:

1. Unversioned lead aliases — GET/POST /api/leads (plus /api/leads/{id}) work exactly like /api/v1/leads. These exist because some no-code platforms (Pabbly Connect, older Zapier connectors, n8n HTTP nodes) do not follow 308 redirects on POST.
2. Automatic 308 redirect — any other path under /api/ that does not match an explicit route is redirected to its /api/v1/ equivalent, preserving the HTTP method and body. Unknown paths return a JSON 404 ({"status":"error","message":"Endpoint not found.","code":"NOT_FOUND"}).

Interactive documentation#

The full OpenAPI 3.1.0 specification renders as Swagger UI — no login required:

• /api/docs (canonical)
• /api/documentation and /api/swagger (aliases)
• /api/v1/docs (versioned alias)

The spec documents API-key scopes, the pagination envelope, and the outbound webhook events (plus a virtual x-webhooks endpoint).

Authentication at a glance#

Detailed flows: Authentication. Error handling for both: Error codes & handling.

Rate limits#

Rate limiting is enforced by middleware, per API key and per workspace:

The multiplier comes from config('leadhub.api.tenant_rate_limit_multiplier') (LH_API_TENANT_RL_MULTIPLIER). Both are fixed hourly windows — the counter resets on the hour boundary.

Successful responses carry the per-key headers:

X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset

When the per-key limit is exceeded the API returns 429 with those same headers plus Retry-After and Rate limit exceeded. Limit: N requests/hour. A workspace-level 429 instead carries the tenant-suffixed headers — X-RateLimit-Limit-Tenant / X-RateLimit-Remaining-Tenant / X-RateLimit-Reset-Tenant — plus Retry-After and Tenant rate limit exceeded. Limit: N requests/hour.

Other endpoints have their own, separate limiter:

Health check#

GET /api/v1/health is public and never requires a key. It round-trips the database, cache and storage — each reported as a boolean in checks — and reports the configured queue connection name in queue:

{
  "status": "ok",
  "checks": { "db": true, "cache": true, "storage": true },
  "queue": "database",
  "version": "2.0.12",
  "timestamp": "2026-10-06T09:00:00+05:30"
}

status is ok or degraded; a degraded install returns HTTP 503. Failures are also written to the Laravel log (healthcheck.db.failed, and equivalents). The admin panel exposes the same probe at /up. Point your uptime monitor at this URL — see Monitoring & alerts.

Response shapes#

• REST API success: {"data": ...}, wrapped with meta (pagination: current_page, last_page, per_page, total, from, to) and links (first/last/prev/next/self) for lists. Errors: {"status":"error","message":"...","code":"..."}.
• Mobile API success: {"data": ...} (plus meta for paginated lists). Errors: {"error":{"message":"...","code":"..."}}.

Common mistakes#

• Using an API key against /api/v1/mobile/* — device tokens and API keys are not interchangeable (and vice versa).
• Forgetting the subfolder when the install is not document-rooted at public/ — the request 404s at the web-server level before Laravel sees it.
• Letting a key's expires_at pass silently — revoked/expired keys return 401 Invalid or expired API key.

Troubleshooting#

Technical details#

• Routes: routes/api.php (REST, mobile, public webhook endpoints).
• REST middleware: App\Http\Middleware\ApiKeyAuthentication.
• Mobile middleware: App\Http\Middleware\DeviceAuthenticate.
• Error payloads: App\Http\Responses\ApiErrorResponse.
• Pagination resource: App\Http\Resources\Api\ApiResource.
• Health: App\Http\Controllers\Api\HealthController.
• OpenAPI viewer: App\Http\Controllers\Api\ApiDocsController.

Related guides#

• Authentication
• Error codes & handling
• REST API (API keys)
• Mobile API (device tokens)
• Webhook endpoints
• Outbound webhooks & API keys