API v2 Overview

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 early preview. Endpoints will expand over time. 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": "[email protected]",
      "phone": "+971501234567",
      "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

Documentation Index

​API v2 Overview

​Base URL

​What’s new in v2

​Contacts

​Companies

​Deals

​Quotations

​Document templates

​Tasks

​Quick start

​Authentication

​Response shape

​Next steps

API v2 Overview

Base URL

What’s new in v2

Contacts

Companies

Deals

Quotations

Document templates

Tasks

Quick start

Authentication

Response shape

Next steps