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": "[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

Overview

Objects

Reference

API v2 Overview

API v2 Overview Beta

Base URL

What’s new in v2

Contacts

Companies

Deals

Quotations

Document templates

Tasks

Quick start

Authentication

Response shape

Next steps

​API v2 Overview Beta

​Base URL

​What’s new in v2

​Contacts

​Companies

​Deals

​Quotations

​Document templates

​Tasks

​Quick start

​Authentication

​Response shape

​Next steps

API v2 Overview Beta

Base URL

What’s new in v2

Contacts

Companies

Deals

Quotations

Document templates

Tasks

Quick start

Authentication

Response shape

Next steps