GET /api/v1/deals
Returns the workspace's deals, sorted by createdAt descending (newest first) — the pipeline view for API consumers. Each deal embeds its linked contact (name, email, external ID), company, and product/offering when set. Requires the read:deals scope (or * for full access).
Request
GET /api/v1/deals HTTP/1.1
Host: agentlyleads.com
Authorization: Bearer alk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxQuery parameters
| Parameter | Description |
|---|---|
stage | One of NEW, QUALIFIED, PROPOSAL, NEGOTIATION, WON, LOST |
contactExternalId | Return only deals linked to the contact with this external ID |
companyExternalId | Return only deals linked to the company with this external ID |
offeringExternalId | Return only deals linked to the product/offering with this external ID |
updatedSince | ISO 8601 datetime — only deals updated at or after this moment |
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. An unknown stage value returns a 400.
Open pipeline for a company:
GET /api/v1/deals?stage=NEW&companyExternalId=hs_company_42 HTTP/1.1
Authorization: Bearer alk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxResponse — 200
{
"deals": [
{
"id": "cmq3deal0alk34567890",
"name": "Acme Corp — Annual Contract",
"value": 12000,
"stage": "QUALIFIED",
"expectedCloseDate": "2026-09-30T00:00:00.000Z",
"notes": null,
"externalId": "hs_deal_789",
"contact": { "name": "Jane Buyer", "email": "jane@acme.com", "externalId": "hs_contact_123" },
"company": { "name": "Acme Corp", "externalId": "hs_company_42" },
"offering": { "name": "Pro Plan — Monthly", "sku": "PLAN-PRO-MO", "externalId": null },
"customFields": null,
"createdAt": "2026-06-01T12:00:00.000Z",
"updatedAt": "2026-07-20T14:03:00.000Z"
}
],
"nextCursor": null
}value is returned as a JSON number (never a string). contact, company, and offering are null when the deal has no such link.
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.