API Reference v1

Leadron API Documentation

The Leadron API is organized around REST. It accepts JSON-encoded request bodies, returns JSON responses, and uses standard HTTP response codes, authentication, and verbs.

REST API

Resource-based routes with JSON payloads

API Keys

External access with X-API-Key header

JWT Auth

Platform UI with Bearer tokens

Base URL

Base URLs

bash

# Production
https://api.leadron.io/v1

# Development
http://localhost:8000/v1

Authentication

External integrations authenticate using API keys sent via the X-API-Key header. All requests are routed through the API Gateway — direct calls to backend services are not permitted.

API Key Authentication

Generate API keys from the Settings → Integrations page in the dashboard, or via the POST /v1/api-keys endpoint. Keys follow the format ldr_<environment>_sk_<random>.

API Key request

http

GET /v1/leads
X-API-Key: ldr_live_sk_a1b2c3d4e5f6g7h8i9j0
Content-Type: application/json

Key Environments

Live

ldr_live_sk_...

Production data — real operations

Sandbox

ldr_sandbox_sk_...

Test data — safe for development

Keep keys secret

API keys carry full permissions for their scope. Never expose them in client-side code, Git repositories, or logs. Rotate keys immediately if compromised.

Acting on Behalf of Users

By default, API key requests act as the user who created the key. To perform actions on behalf of another user in the same tenant, include the X-On-Behalf-Of header with the target user's ID.

Impersonation request

http

POST /v1/leads
X-API-Key: ldr_live_sk_a1b2c3d4e5f6g7h8i9j0
X-On-Behalf-Of: 2fGh8kLmNpQrStUv
Content-Type: application/json

Audit trail

When impersonating, both the API key owner and the acting user are recorded in the audit log. The target user must belong to the same tenant as the API key.

Encoded IDs

All resource IDs in API responses are encoded as alphanumeric strings (16-17 characters). You can use these encoded IDs directly in path parameters, query parameters, and request bodies — the API automatically decodes them.

Using encoded IDs

http

# Encoded ID in path
GET /v1/leads/2fGh8kLmNpQrStUv

# Encoded ID in request body
{
  "assignedTo": "3xYz9aBcDeFgHiJk"
}

Tip

IDs returned by the API are always encoded. Use them as-is — no manual encoding or decoding is required.

Response Format

All endpoints return a consistent envelope. Successful responses include a data field; errors include a message and optional errors array.

{
  "success": true,
  "status": 200,
  "message": "Success",
  "data": {
    "id": "6789abcd...",
    "email": "jane@acme.com",
    "firstName": "Jane",
    "lastName": "Doe"
  },
  "meta": {
    "timestamp": "2026-02-08T12:00:00.000Z",
    "version": "v1"
  }
}

Leads API

Create, manage, and track leads through the sales pipeline. Leads support custom fields, scoring, assignment, and full lifecycle management.

Creates a new lead record with the given data. The lead is automatically assigned a score of 0 unless explicitly provided. Duplicate detection runs asynchronously after creation.

Body Parameters

Parameter	Type	Default	Description
`email`req	`string`	—	Contact email address
`firstName`req	`string`	—	First name of the lead
`lastName`req	`string`	—	Last name of the lead
`phone`	`string`	—	Phone number with country code
`source`	`string` webreferralapiimportmanual	—	Lead source identifier
`status`	`string` newcontactedqualifiedunqualified	new	Initial status
`score`	`number`	0	Initial lead score (0-100)
`customFields`	`object`	—	Key-value pairs for custom field values

Request

HTTP

http

POST https://api.leadron.io/v1/leads
X-API-Key: ldr_live_sk_a1b2c3d4e5f6g7h8i9j0
Content-Type: application/json

Body

json

{
  "email": "jane.doe@example.com",
  "firstName": "Jane",
  "lastName": "Doe",
  "phone": "+1-555-0199",
  "source": "web",
  "customFields": {
    "company": "Acme Inc",
    "role": "VP Sales"
  }
}

Response201Created

201 Response

json

{
  "success": true,
  "status": 201,
  "message": "Resource created successfully",
  "data": {
    "id": "6789abcdef012345",
    "tenantId": "acme-corp",
    "email": "jane.doe@example.com",
    "firstName": "Jane",
    "lastName": "Doe",
    "phone": "+1-555-0199",
    "source": "web",
    "status": "new",
    "score": 0,
    "assignedTo": null,
    "customFields": {
      "company": "Acme Inc",
      "role": "VP Sales"
    },
    "createdAt": "2026-02-08T14:30:00.000Z",
    "updatedAt": "2026-02-08T14:30:00.000Z"
  },
  "meta": {
    "timestamp": "2026-02-08T14:30:00.000Z",
    "version": "v1"
  }
}

Response422Validation Error

422 Response

json

{
  "success": false,
  "status": 422,
  "message": "Validation failed",
  "errors": [
    {
      "field": "email",
      "message": "Invalid email format"
    }
  ],
  "meta": {
    "timestamp": "2026-02-08T14:30:00.000Z",
    "version": "v1"
  }
}

Component Showcase

Every component available in this documentation system, displayed with realistic data.

Method Badges

GETPOSTPUTPATCHDELETE

Status Badges

200OK201Created204No Content301Moved400Bad Request401Unauthorized403Forbidden404Not Found422Validation429Rate Limited500Server Error

Callouts

Info

This is an informational callout for general guidance and context.

Tip

Use the Stripe test mode keys during development. No real charges are made.

Warning

Rate limits apply to all authenticated endpoints. See the Rate Limits section below.

Success

Your API key has been verified. You can now make authenticated requests.

Error

This endpoint has been deprecated and will be removed in v2. Migrate to the new endpoint.

Tabbed Blocks

$ curl -X POST https://api.leadron.io/v1/leads \
  -H "X-API-Key: ldr_live_sk_a1b2c3d4e5f6g7h8i9j0" \
  -H "Content-Type: application/json" \
  -d '{"email":"jane@acme.com","firstName":"Jane","lastName":"Doe"}'

Collapsible Code

Full lead object (click to expand)

json

Rate Limits

API rate limits are applied per tenant and per IP address. When you exceed the limit, the API returns429 Too Many Requests.

Plan	Rate Limit	Window	Burst
Free	60 req	1 minute	10
Starter	300 req	1 minute	30
Pro	1,000 req	1 minute	100
Team	5,000 req	1 minute	500
Enterprise	Custom	Custom	Custom

Rate limit headers

Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.