Leads

List Leads

GET /api/v1/leads

Scope: leads:read

Query Parameters

Parameter	Type	Default	Description
`page`	integer	1	Page number
`limit`	integer	50	Results per page (1-100)
`status`	string	—	Filter by status
`temperature`	string	—	Filter: `cold`, `warm`, or `hot`
`search`	string	—	Search by name, email, or phone
`created_after`	ISO 8601	—	Filter by creation date
`created_before`	ISO 8601	—	Filter by creation date
`sort_by`	string	`created_at`	Sort: `created_at`, `updated_at`, `first_name`, `last_name`, `lead_score`
`sort_dir`	string	`desc`	Direction: `asc` or `desc`

Example

curl "https://api.brightlyai.app/api/v1/leads?temperature=hot&limit=10" \
  -H "Authorization: Bearer brk_your_key"

Response

{
  "data": [
    {
      "id": "a1b2c3d4-...",
      "first_name": "Jane",
      "last_name": "Smith",
      "phone": "+15551234567",
      "email": "jane@example.com",
      "status": "new",
      "temperature": "hot",
      "lead_score": 85,
      "company": "Smith Roofing",
      "created_at": "2026-05-10T14:30:00Z",
      "updated_at": "2026-05-10T14:30:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 10,
    "total": 47,
    "total_pages": 5
  }
}

Get Lead

GET /api/v1/leads/:id

Scope: leads:read

curl "https://api.brightlyai.app/api/v1/leads/a1b2c3d4-..." \
  -H "Authorization: Bearer brk_your_key"

Create Lead

POST /api/v1/leads

Scope: leads:write

Request Body

Field	Type	Required	Description
`first_name`	string	Yes	Max 100 chars
`last_name`	string	No	Max 100 chars
`phone`	string	No	Phone number
`email`	string	No	Valid email
`company`	string	No	Max 200 chars
`address_street`	string	No	Max 200 chars
`city`	string	No	—
`state`	string	No	Max 2 chars
`zip`	string	No	Max 10 chars
`status`	string	No	Max 50 chars
`temperature`	string	No	`cold`, `warm`, or `hot`
`source`	string	No	Default: `api`. Options: `manual`, `api`, `website`, `referral`, `import`, `other`
`notes`	string	No	Max 5000 chars
`tags`	string[]	No	Array of tag strings
`custom_fields`	object	No	Key-value custom fields

Example

curl -X POST "https://api.brightlyai.app/api/v1/leads" \
  -H "Authorization: Bearer brk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Jane",
    "last_name": "Smith",
    "phone": "+15551234567",
    "email": "jane@example.com",
    "company": "Smith Roofing"
  }'

Update Lead

PUT /api/v1/leads/:id

Scope: leads:write

All create fields are accepted, all optional. Only provided fields are updated.

Delete Lead

DELETE /api/v1/leads/:id

Scope: leads:write

{
  "data": {
    "id": "a1b2c3d4-...",
    "deleted": true
  }
}