API Reference

Complete reference documentation for the Ledly REST API.

Base URL

https://api.ledly.io/api

For vendor lead ingestion:

https://api.ledly.io/api/v1

Authentication

Ledly supports two authentication methods:

Bearer Token (User API)

For user-facing APIs, use a Bearer token:

curl -H "Authorization: Bearer your_jwt_token" \
  https://api.ledly.io/api/leads

Get tokens by logging in via /api/auth/login.

API Key (Vendor API)

For vendor integrations, use an API key:

curl -H "Authorization: Bearer your_api_key" \
  https://api.ledly.io/api/leads/inbound

Generate API keys in Settings → API Keys.

⚠️

Never expose API keys or tokens in client-side code, URLs, or version control.

API Sections

Authentication

Create, read, update, delete leads

Leads

Vendor API for submitting leads

Lead Ingestion

Manage lead source vendors

Vendors

Enrichment rules and custom fields

Enrichment

Validation rules configuration

Validation

Webhook configuration and delivery

Webhooks

CRM integration management

CRM Connections

User management and permissions

Users

Organization settings and configuration

Organizations

Reporting and analytics endpoints

Analytics

Rate limiting information

Rate Limits

Error codes and troubleshooting

Error Codes

Quick Reference

Leads

Method	Endpoint	Description
GET	`/leads`	List leads with filtering
GET	`/leads/:id`	Get lead details
GET	`/leads/:id/activity`	Get lead activity log
POST	`/leads`	Create a new lead
PATCH	`/leads/:id`	Update a lead
DELETE	`/leads/:id`	Soft delete a lead
POST	`/leads/bulk-update`	Bulk update leads
POST	`/leads/bulk-delete`	Bulk delete leads

Lead Ingestion (Vendor API)

Method	Endpoint	Description
POST	`/v1/leads/ingest`	Submit a single lead
POST	`/v1/leads/bulk-ingest`	Submit multiple leads

Vendors

Method	Endpoint	Description
GET	`/vendors`	List vendors
GET	`/vendors/:id`	Get vendor details
POST	`/vendors`	Create vendor
PUT	`/vendors/:id`	Update vendor
DELETE	`/vendors/:id`	Delete vendor
POST	`/vendors/:id/enable`	Enable vendor
POST	`/vendors/:id/disable`	Disable vendor

Enrichment

Method	Endpoint	Description
GET	`/enrichment/rules`	List enrichment rules
POST	`/enrichment/rules`	Create rule
PATCH	`/enrichment/rules/:id`	Update rule
DELETE	`/enrichment/rules/:id`	Delete rule
POST	`/enrichment/test`	Test rules
GET	`/enrichment/custom-fields`	List custom fields
POST	`/enrichment/custom-fields`	Create custom field

Webhooks

Method	Endpoint	Description
GET	`/webhooks`	List webhooks
POST	`/webhooks`	Create webhook
PATCH	`/webhooks/:id`	Update webhook
DELETE	`/webhooks/:id`	Delete webhook
POST	`/webhooks/:id/test`	Test webhook

CRM

Method	Endpoint	Description
GET	`/crm/connections`	List CRM connections
POST	`/crm/connections`	Create connection
POST	`/crm/connections/:id/test`	Test connection
DELETE	`/crm/connections/:id`	Remove connection
POST	`/crm/:id/sync/:leadId`	Sync lead to CRM

Users

Method	Endpoint	Description
GET	`/users`	List users
POST	`/users`	Create user
GET	`/users/:id`	Get user
PATCH	`/users/:id`	Update user
DELETE	`/users/:id`	Delete user
POST	`/users/invite`	Invite user

Analytics

Method	Endpoint	Description
GET	`/analytics`	Dashboard overview
GET	`/analytics/executive-summary`	Executive summary
GET	`/analytics/source-performance`	Source performance
GET	`/analytics/conversion-funnel`	Conversion funnel
GET	`/analytics/lead-volume-trend`	Volume trends
GET	`/analytics/vendor-roi`	Vendor ROI

Request Format

Headers

Content-Type: application/json
Authorization: Bearer <token>

Request Body (JSON)

{
  "email": "[email protected]",
  "first_name": "John",
  "last_name": "Doe"
}

Query Parameters

Filtering and pagination:

GET /api/leads?page=1&limit=20&status=active&source=web

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`limit`	integer	Items per page (default: 20, max: 100)
`sortBy`	string	Sort field
`sortOrder`	string	`asc` or `desc`

Response Format

Success Response

{
  "data": {
    "id": "lead_abc123",
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe",
    "created_at": "2024-12-25T10:30:00Z"
  }
}

List Response (with pagination)

{
  "data": [
    { "id": "lead_1", "email": "[email protected]" },
    { "id": "lead_2", "email": "[email protected]" }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  }
}

Error Response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input",
    "details": [
      { "field": "email", "message": "Invalid email format" }
    ]
  }
}

HTTP Status Codes

Code	Meaning
200	OK - Request succeeded
201	Created - Resource created
204	No Content - Deleted successfully
400	Bad Request - Invalid input
401	Unauthorized - Invalid/missing auth
403	Forbidden - Insufficient permissions
404	Not Found - Resource doesn’t exist
409	Conflict - Duplicate resource
422	Unprocessable - Business logic error
429	Too Many Requests - Rate limited
500	Internal Server Error

Rate Limits

Endpoint	Limit	Window
Authentication	10 requests	1 minute
Lead Ingestion	500 requests	1 minute
General API	100 requests	1 minute
Export	10 requests	1 minute
Bulk Operations	20 requests	1 minute

Rate limit headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1703505600

SDKs and Libraries

Official SDKs coming soon. In the meantime, use standard HTTP clients:

Language	Recommended Library
JavaScript	`fetch` or `axios`
Python	`requests`
PHP	`GuzzleHttp`
Ruby	`HTTParty`
Go	`net/http`

Changelog

2024-12-25

Added bulk lead ingestion endpoint
Added analytics API

2024-11-15

Added webhook delivery logs
Improved error messages

2024-10-01

Initial API release

Lead Funnel Authentication