Skip to main content

​
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

  1. 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).
  1. 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"
  1. 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"
  1. 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

  1. 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"
  1. Optional: template custom fields — GET /document-templates/{id} for customFields keys to send as cf_* on create.
  2. 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.