Agent workflows

These sequences show how to chain API v2 calls for typical automation tasks. All requests require the x-api-key header. See ID prefixes for ID formats.

Create a deal in a pipeline

List pipelines — get dpl_ and dps_ IDs:

curl "https://api.heffl.com/api/v2/pipelines" \
  -H "x-api-key: YOUR_API_KEY"

Pick a pipeline id and an ACTIVE stage id from stages (check type is ACTIVE).

Resolve the client — search contacts or companies, or create one:

curl "https://api.heffl.com/api/v2/contacts?search=acme&pageSize=5" \
  -H "x-api-key: YOUR_API_KEY"

Optional: custom fields — discover valid cf_* keys:

curl "https://api.heffl.com/api/v2/custom-fields?entity=deals&pipelineId=dpl_abc123" \
  -H "x-api-key: YOUR_API_KEY"

Create the deal:

curl -X POST "https://api.heffl.com/api/v2/deals" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Enterprise license",
    "clientId": "clt_abc123",
    "pipelineId": "dpl_abc123",
    "stageId": "dps_abc123",
    "price": 25000,
    "expectedCloseDate": "2026-06-30T00:00:00.000Z"
  }'

stageId is optional; if omitted, the first ACTIVE stage in the pipeline is used.

Close a deal (won or lost)

Option A — update stage (recommended when matching your pipeline):

curl -X PATCH "https://api.heffl.com/api/v2/deals/dl_abc123" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "stageId": "dps_won_stage_id" }'

Use a stage with type WON or LOST from GET /pipelines. Option B — set status directly:

curl -X PATCH "https://api.heffl.com/api/v2/deals/dl_abc123" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "WON" }'

Create a follow-up task on a deal

curl -X POST "https://api.heffl.com/api/v2/tasks" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Follow up on proposal",
    "type": "call",
    "dueDate": "2026-06-01T10:00:00.000Z",
    "entity": "deals",
    "entityId": "dl_abc123",
    "assigneeIds": ["usr_xyz789"]
  }'

entity and entityId must be sent together. List users with GET /users for assignee IDs.

Create a quotation

List quotation document templates (layout presets for quotations, not project templates) — get a tpl_ ID:

curl "https://api.heffl.com/api/v2/document-templates?type=quotations" \
  -H "x-api-key: YOUR_API_KEY"

Optional: template custom fields — GET /document-templates/{id} for customFields keys to send as cf_* on create.
Create the quotation — see Document templates and API v2 overview — Quotations.

List open deals in a pipeline

Pass filters as a JSON-encoded query string (recommended for agents and curl):

curl -G "https://api.heffl.com/api/v2/deals" \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'pageSize=25' \
  --data-urlencode 'filters={"pipelineId":{"operator":"is","values":["dpl_abc123"]},"status":{"operator":"is","values":["ACTIVE"]}}'

Paginate with cursor from meta.nextCursor. See Listing & filters.

Delete a contact

Deletion fails with 400 if the contact has linked deals, invoices, or quotations:

curl -X DELETE "https://api.heffl.com/api/v2/contacts/clt_abc123" \
  -H "x-api-key: YOUR_API_KEY"

Error handling

All errors use { "error": { "code", "message", "details?" } }. Validation failures include details.issues with field and message. See Errors. Retry 429 after the rate limit window; do not retry 400 without changing the request.

Overview

Objects

Reference

Agent workflows

Agent workflows

Create a deal in a pipeline

Close a deal (won or lost)

Create a follow-up task on a deal

Create a quotation

List open deals in a pipeline

Delete a contact

Error handling

​Agent workflows

​Create a deal in a pipeline

​Close a deal (won or lost)

​Create a follow-up task on a deal

​Create a quotation

​List open deals in a pipeline

​Delete a contact

​Error handling

Agent workflows

Create a deal in a pipeline

Close a deal (won or lost)

Create a follow-up task on a deal

Create a quotation

List open deals in a pipeline

Delete a contact

Error handling