API quick start

The full reference is at /api-docs. This is enough to make your first successful call.

Get a token

Settings → API tokens → Issue token.

Choose only the abilities you need. A token narrows its membership's permissions and can never exceed them, so a token issued for a read-only integration really is read-only.

The token is shown once. It cannot be recovered — issue a new one if you lose it.

Authenticate

Bearer token in the header. On a shared domain you also send your workspace slug:

curl https://api.nexuscrm.com/api/v1/leads \
  -H "Authorization: Bearer nxs_xxxx_yyyyyyyy" \
  -H "X-Tenant-Slug: your-workspace" \
  -H "Accept: application/json"

Create a lead

curl -X POST https://api.nexuscrm.com/api/v1/leads \
  -H "Authorization: Bearer nxs_xxxx_yyyyyyyy" \
  -H "X-Tenant-Slug: your-workspace" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Aarav",
    "last_name": "Patel",
    "phone": "9812300045",
    "email": "aarav@example.com",
    "source": "01H8XGJWBWBAQ4S1PT7C2N3M4K"
  }'

Distribution rules apply to leads created this way, exactly as they do to leads from a form.

Responses

Every successful response uses the same envelope:

{
  "data": { "object": "lead", "public_id": "01H8...", "reference_number": "L-260729-04821" }
}

Records are always identified by public_id — a ULID. Sequential internal ids are never exposed, so an id you hold cannot be incremented to reach someone else's record.

Errors

RFC 9457 problem documents:

{
  "type": "https://docs.nexuscrm.com/api/problems/validation_failed",
  "title": "The request was invalid.",
  "status": 422,
  "code": "validation_failed",
  "request_id": "01KYM97KCJK416C465Y2A8AN3N"
}

Branch on code, never on title — the human string may change, the code will not. Quote request_id when contacting support and we can find the exact request.

Pagination

Cursor-based, not page numbers:

GET /api/v1/leads?page[size]=50

{
  "data": [],
  "links": { "next": "/api/v1/leads?page[size]=50&page[after]=01H8..." },
  "meta": { "has_more": true }
}

Follow links.next until it is null. Page 500 costs the same as page 1, and rows arriving mid-iteration cannot cause you to see a duplicate.

Rate limits

Per token, returned on every response:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 594

A 429 includes Retry-After. Back off and retry — do not spin.

Webhooks

Rather than polling, subscribe to events. See Integrations.