API Reference
The reference below covers every endpoint in the Deals API. Code examples are generated automatically; the live playground is disabled to prevent accidental writes to production from the docs site.
/api/v1/dealsAuthorization
BearerAuth Pass an API key issued from the agentlyleads workspace settings.
Example: Authorization: Bearer alk_live_xxxxxxxxxxxx
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/api/v1/deals" \ -H "Content-Type: application/json" \ -d '{ "deals": [ { "name": "Acme Corp — Annual Contract", "value": 12000, "stage": "QUALIFIED", "expectedCloseDate": "2026-09-30", "externalId": "hs_deal_789" } ] }'{ "created": 1, "updated": 1, "errors": 0, "results": [ { "index": 0, "status": "created", "id": "018e2a4b-0000-7000-8000-aabbccddeeff" }, { "index": 1, "status": "updated", "id": "018e2a4b-1111-7000-8000-aabbccddeeff" } ]}{ "created": 1, "updated": 0, "errors": 1, "results": [ { "index": 0, "status": "created", "id": "018e2a4b-0000-7000-8000-aabbccddeeff" }, { "index": 1, "status": "error", "error": "name: Required" } ]}{ "error": "deals must not be empty."}{ "error": "Invalid or missing API key."}{ "error": "API key missing required scope: write:products."}{ "error": "Rate limit exceeded."}/api/v1/dealsAuthorization
BearerAuth Pass an API key issued from the agentlyleads workspace settings.
Example: Authorization: Bearer alk_live_xxxxxxxxxxxx
In: header
Query Parameters
Filter to deals in this pipeline stage.
Value in
- "NEW"
- "QUALIFIED"
- "PROPOSAL"
- "NEGOTIATION"
- "WON"
- "LOST"
Filter to deals linked to the contact with this external ID.
Filter to deals linked to the company with this external ID.
Filter to deals linked to the product/offering with this external ID.
Only deals updated at or after this ISO 8601 datetime.
date-timePage size.
1 <= value <= 1000100The nextCursor value from the previous page.
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/api/v1/deals?stage=NEW&updatedSince=2026-07-01T00%3A00%3A00Z"{ "deals": [ { "id": "cmq3deal0alk34567890", "name": "Acme Corp — Annual Contract", "value": 12000, "stage": "NEW", "expectedCloseDate": "2019-08-24T14:15:22Z", "notes": "string", "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": "string" }, "customFields": {}, "createdAt": "2019-08-24T14:15:22Z", "updatedAt": "2019-08-24T14:15:22Z" } ], "nextCursor": "string"}{ "error": "stage must be one of: NEW, QUALIFIED, PROPOSAL, NEGOTIATION, WON, LOST."}{ "error": "Invalid or missing API key."}{ "error": "API key missing required scope: read:deals."}{ "error": "Rate limit exceeded."}