GET /api/v1/leads

Returns the workspace's leads, sorted by createdAt descending (newest first). Each lead includes its assigned owner (name + email) and interested offering (name, SKU, external ID) when set. Requires the read:leads scope (or * for full access).

Request

GET /api/v1/leads HTTP/1.1
Host: agentlyleads.com
Authorization: Bearer alk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Query parameters

Parameter	Description
`email`	Return only the lead with this exact email address (case-insensitive)
`externalId`	Return only the lead with this external ID
`status`	Return only leads with this status — one of `NEW`, `WORKING`, `QUALIFIED`, `UNQUALIFIED`, `CONVERTED`
`lifecycleStage`	Return only leads at this lifecycle stage — one of `SUBSCRIBER`, `LEAD`, `MARKETING_QUALIFIED_LEAD`, `SALES_QUALIFIED_LEAD`, `OPPORTUNITY`, `CUSTOMER`, `EVANGELIST`, `OTHER`
`updatedSince`	ISO 8601 datetime — only leads updated at or after this moment (useful for incremental sync)
`limit`	Page size, 1–1000 (default `100`)
`cursor`	The `nextCursor` value from the previous page

All parameters are optional and can be combined. Filters that match nothing return an empty list, not a 404.

Look up a lead by email:

GET /api/v1/leads?email=jane@acme.com HTTP/1.1
Authorization: Bearer alk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

New leads changed since July 1:

GET /api/v1/leads?status=NEW&updatedSince=2026-07-01T00:00:00Z HTTP/1.1
Authorization: Bearer alk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Response — 200

{
  "leads": [
    {
      "id": "cmq5lead0alk34567890",
      "name": "Jane Buyer",
      "title": "Head of Procurement",
      "company": "Acme Inc.",
      "email": "jane@acme.com",
      "phone": "+1 555 0100",
      "source": "Landing page",
      "category": null,
      "buyerType": null,
      "website": null,
      "linkedinUrl": null,
      "city": null,
      "state": null,
      "country": null,
      "lifecycleStage": "LEAD",
      "status": "NEW",
      "estimatedInterest": "MEDIUM",
      "notes": "Source detail: https://acme.com/pricing",
      "externalId": "hs_lead_123",
      "owner": { "name": "Sam Rep", "email": "sam@yourcompany.com" },
      "interestedOffering": { "name": "Starter Plan", "sku": "STARTER-1", "externalId": "hs_product_9" },
      "customFields": null,
      "createdAt": "2026-07-22T09:30:00.000Z",
      "updatedAt": "2026-07-22T09:30:00.000Z"
    }
  ],
  "nextCursor": null
}

owner is null until a workflow (e.g. round-robin assignment) or a human assigns the lead. interestedOffering is null unless the lead is linked to a specific offering.

Pagination

Responses are cursor-paginated. When more rows exist beyond the requested limit, nextCursor holds the ID of the last returned record — pass it back as cursor to fetch the next page. On the last page, nextCursor is null.

GET /api/v1/leads?limit=100&cursor=cmq5lead0alk34567890 HTTP/1.1
Authorization: Bearer alk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Errors

Status	Meaning
`400`	Invalid query parameter — e.g. `{"error": "status must be one of: NEW, WORKING, QUALIFIED, UNQUALIFIED, CONVERTED."}`.
`401`	Missing, invalid, or expired API key.
`403`	Key lacks the `read:leads` scope.
`429`	Rate limited (per-key limit). Retry after the `Retry-After` header value in seconds.

Example: cURL

curl -G https://agentlyleads.com/api/v1/leads \
  -H "Authorization: Bearer $AGENTLYLEADS_API_KEY" \
  -d status=NEW \
  -d limit=50