API v2 Overview

Heffl REST API v2 — resource-oriented endpoints with consistent envelopes

API v2 Overview Beta

Heffl API v2 is the current REST API for programmatic access to your workspace. System and custom object records are exposed at resource paths such as /contacts, /companies, /deals, /quotations, and /tasks with a consistent response envelope and structured errors.

API v2 is in beta. Endpoints, schemas, and behavior may change as we expand coverage. Prefer it for new integrations, but expect breaking changes until GA. Legacy API v1 remains fully supported for existing integrations.

Base URL

https://api.heffl.com/api/v2

All endpoints are served over HTTPS.

What’s new in v2

Feature	v1 (legacy)	v2
Response shape	Flat resource object	List: { data, meta } envelope; create/update/delete return the resource directly
Error shape	{ code, message }	{ error: { code, message, details? } }
Resource paths	Flat (/clients)	Resource-based (/contacts, /companies)
Contacts	POST /clients with type: "contact"	GET /contacts, POST /contacts, PATCH /contacts/{id}, DELETE /contacts/{id}
Companies	POST /clients with type: "company"	GET /companies, POST /companies, PATCH /companies/{id}, DELETE /companies/{id}
Deals	GET /deals, POST /deals, GET /deals/{id}, PATCH /deals/{id}, DELETE /deals/{id}	GET /deals, POST /deals, GET /deals/{id}, PATCH /deals/{id}, DELETE /deals/{id}
Quotations	—	GET /quotations, POST /quotations, GET /quotations/{id}, PATCH /quotations/{id}, DELETE /quotations/{id}
Tasks	GET /tasks, POST /tasks, GET /tasks/{id}, PATCH /tasks/{id}, DELETE /tasks/{id}	GET /tasks, POST /tasks, PATCH /tasks/{id}, DELETE /tasks/{id}

Contacts

Method	Path	Description
GET	/contacts	List contacts (paginated, filterable)
POST	/contacts	Create a contact
PATCH	/contacts/{id}	Update a contact
DELETE	/contacts/{id}	Delete a contact

Companies

Method	Path	Description
GET	/companies	List companies (paginated, filterable)
POST	/companies	Create a company
PATCH	/companies/{id}	Update a company
DELETE	/companies/{id}	Delete a company

Deals

Method	Path	Description
GET	/deals	List deals (paginated, filterable)
GET	/deals/{id}	Get a deal
POST	/deals	Create a deal
PATCH	/deals/{id}	Update a deal
DELETE	/deals/{id}	Delete a deal

List active deals in a pipeline:

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"]}}'

Create a deal by linking a client, pipeline, and stage:

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"
  }'

Quotations

Method	Path	Description
GET	/quotations	List quotations (paginated, filterable)
GET	/quotations/{id}	Get a quotation with line items and totals
POST	/quotations	Create a quotation
PATCH	/quotations/{id}	Update a quotation
DELETE	/quotations/{id}	Delete a quotation

Create a quotation for a client with line items:

curl -X POST "https://api.heffl.com/api/v2/quotations" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "clt_abc123",
    "templateId": "tpl_abc123",
    "date": "2026-05-31T00:00:00.000Z",
    "subject": "Website redesign proposal",
    "quotationProducts": [
      {
        "name": "Discovery workshop",
        "quantity": 1,
        "price": 2500,
        "taxRateId": "txr_abc123"
      }
    ]
  }'

clientId is a contact or company ID (clt_ prefix) — use the id from GET /contacts or GET /companies. Optional contactId (clt_) sets the contact person when the client is a company.

templateId is required (tpl_ prefix). List quotation templates with GET /document-templates?type=quotations — see Document templates. Pass dealId (dl_ prefix) to link the quote to a deal, and tags with tag_ IDs. Custom fields use cf_* keys — see Custom fields.

Document templates

Templates used for documents in Heffl — quotations, invoices, proforma invoices, purchase orders, and similar (not project or email templates). List by type to get the templateId for API creates.

Method	Path	Description
GET	/document-templates	List document templates (filter by type, search by name)
GET	/document-templates/{id}	Get a template with template-scoped custom fields

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

Tasks

Method	Path	Description
GET	/tasks	List tasks (paginated, filterable)
POST	/tasks	Create a task
PATCH	/tasks/{id}	Update a task
DELETE	/tasks/{id}	Delete a task

Link a task to a deal, lead, or project using entity and entityId:

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"
  }'

Quick start

List contacts with your API key:

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

Response:

{
  "data": [
    {
      "id": "clt_abc123",
      "number": "CON001",
      "firstName": "Jane",
      "lastName": "Smith",
      "email": "[e-mail]",
      "phone": "[phone]",
      "createdAt": "2025-01-15T10:30:00.000Z",
      "cf_industry": "Technology"
    }
  ],
  "meta": {
    "nextCursor": null,
    "hasMore": false
  }
}

Update a contact (partial update — only send fields you want to change):

curl -X PATCH "https://api.heffl.com/api/v2/contacts/clt_abc123" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jobTitle": "Head of Sales",
    "companyId": "clt_company456"
  }'

Response:

{
  "id": "clt_abc123",
  "number": "CON001",
  "firstName": "Jane",
  "lastName": "Smith",
  "jobTitle": "Head of Sales",
  "companyId": "clt_company456",
  "createdAt": "2025-01-15T10:30:00.000Z"
}

Delete a contact:

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

Response:

{
  "id": "clt_abc123",
  "deleted": true
}

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

Authentication

Same as v1 — include your API key in the x-api-key header on every request. See Authentication.

Response shape

List endpoints return a paginated envelope:

{
  "data": [ ... ],
  "meta": {
    "nextCursor": null,
    "hasMore": false
  }
}

Create, update, and delete return the resource (or delete result) directly — not wrapped in data:

{
  "id": "clt_abc123",
  "firstName": "Jane",
  "lastName": "Smith"
}

Custom fields are returned as top-level cf_* keys on each resource (for example cf_industry), not in a customFields object. See Custom fields.

Next steps

• Agent workflows — multi-step sequences (create deal, close deal, tasks)
• ID prefixes — clt_, dpl_, dps_, dl_, and other ID formats
• Authentication — API keys and permissions
• Errors — error codes and validation details
• Pagination — cursor-based paging with pageSize
• Listing & filters — search, sort, and structured filters
• Custom fields — cf_* field conventions; discover keys via GET /custom-fields
• Document templates — templates for quotations, invoices, proforma invoices, and other documents
• Browse endpoint reference in the sidebar