API overview
Base URL pattern, authentication, and what endpoints exist.
The HREF CRM exposes a single public endpoint per tenant: a lead intake API. HREF developers call it from lead-capture forms on client websites and from any other integration that needs to push leads into a tenant's CRM.
Base URL pattern
https://<tenant>.hrefcreative.co/api/...Replace <tenant> with the tenant's slug. For example, Acme Family Law (slug acme) is at https://acme.hrefcreative.co. The slug is set at provisioning time and is stable for the life of the tenant.
In local development, the pattern is:
http://<tenant>.localtest.me:3001/api/...*.localtest.me resolves to 127.0.0.1 automatically, so no /etc/hosts edits are needed.
Authentication
Every request to a tenant's API requires that tenant's API key in the X-API-Key header:
X-API-Key: hcrm_<random>API keys are tenant-scoped. A key for Acme cannot post leads to BigFirm. Keys are generated when a tenant is provisioned, displayed once at the terminal, and stored as a SHA-256 hash in the database. There is no way to retrieve the original. If a key is lost, rotate it from the tenant's settings (Phase 7).
Endpoints
| Method | Path | Purpose |
|---|---|---|
POST | /api/leads/intake | Create a new lead in the tenant. See the full spec. |
Versioning
There is no version prefix in the URL today. v1 will hold for the foreseeable future. If a breaking change ever lands, we will introduce /api/v2/... and keep /api/... working as a v1 alias.
Rate limiting
None in v1. HREF controls every form posting in, so there is no abuse model to defend against. If a runaway form ever floods a tenant, we will see it and add per-key throttling at that point.
Errors
All errors return JSON with at least an error code and a human-readable message:
{ "error": "invalid_api_key", "message": "API key is missing or does not match." }Common codes:
| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_request | The body did not pass validation. details array contains field-level errors. |
| 401 | invalid_api_key | Missing or wrong X-API-Key. |
| 404 | tenant_not_found | The subdomain does not match a known tenant. |
| 5xx | internal_error | Something on our end. Retry safely. |
Idempotency
Not yet supported. v1 treats each POST as a fresh insert. If you POST the same lead twice, you get two leads. We will add an optional Idempotency-Key header in a future phase if double-submits become a real problem.