Skip to main content
GET
/
api
/
agents
/
crm
/
leads
List / search leads
curl --request GET \
  --url https://app.gomega.ai/api/agents/crm/leads \
  --header 'Authorization: Bearer <token>' \
  --header 'x-customer-id: <x-customer-id>'
{
  "leads": [
    {
      "id": "<string>",
      "customer_id": "<string>",
      "source_platform": "<string>",
      "source_type": "<string>",
      "status": "<string>",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "contact_name": "<string>",
      "contact_phone": "<string>",
      "contact_email": "<string>",
      "score": 123,
      "qualified": true,
      "current_stage": {
        "id": "<string>",
        "slug": "<string>",
        "name": "<string>",
        "color": "<string>"
      },
      "owner": {
        "id": "<string>",
        "name": "<string>",
        "role_name": "<string>"
      },
      "last_interaction_at": "2023-11-07T05:31:56Z",
      "interaction_count": 123,
      "custom_fields": {}
    }
  ],
  "total": 123,
  "limit": 123,
  "offset": 123,
  "next_cursor": "<string>"
}

Authorizations

​
Authorization
string
header
required

Admin-issued Personal Access Token, e.g. Authorization: Bearer mega_<64 hex>. The key carries scopes (public_api:leads:read, public_api:leads:write, public_api:webhooks:manage) and is locked to one customer.

Headers

​
x-customer-id
string<uuid>
required

The customer this request acts on. Must match the customer your key is locked to.

Query Parameters

​
status
string

Filter by lead status (e.g. active, won, lost, nurture, archived).

​
stageId
string<uuid>

Filter by current pipeline stage id.

​
search
string

Free-text match on name / email / phone (phone-format-agnostic).

​
created_since
string<date-time>

Only leads created at/after this ISO-8601 timestamp.

​
updated_since
string<date-time>

Only leads updated at/after this ISO-8601 timestamp.

​
sort_by
enum<string>
default:updated_at
Available options:
created_at,
updated_at,
last_interaction_at
​
sort_dir
enum<string>
default:asc
Available options:
asc,
desc
​
lead_line
enum<string>

Filter by the reserved lead_line custom field.

Available options:
buyer,
seller
​
include_custom_fields
boolean
default:false

When true, include a custom_fields object on each lead.

​
cursor
string

Opaque keyset cursor from a previous response's next_cursor. Only valid with the same sort_by/sort_dir.

​
limit
integer
default:20
Required range: 1 <= x <= 100
​
offset
integer
default:0

Offset paging (back-compat). Prefer cursor for incremental polling.

Required range: x >= 0

Response

A page of leads.

​
leads
object[]
required
​
total
integer
required

Total matching the filter (ignores cursor/offset).

​
limit
integer
required
​
offset
integer
required
​
next_cursor
string | null
required

Pass as cursor to fetch the next page; null when there are no more pages.