Legacy API (v1)

Heffl REST API v1 — maintained for existing integrations

Legacy API (v1)

This is the legacy API (v1). For new integrations, use API v2 — it has clearer resource paths, a consistent response envelope, and structured errors.

The Heffl v1 API lets you programmatically access and manage your CRM, sales, and project data. Existing integrations continue to work without changes. v1 remains fully supported, but new features ship in v2 first.

Base URL

https://api.heffl.com/api/v1

All API endpoints are served over HTTPS. HTTP requests are not supported.

Authentication

Every request must include your API key in the x-api-key header:

curl https://api.heffl.com/api/v1/leads \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

See Authentication for how to create and manage API keys.

Request format

• All request bodies must be JSON with Content-Type: application/json
• Query parameters are used for filtering and pagination on list endpoints
• Resource IDs in URLs are string-based public IDs (e.g., ld_abc123) across business entities (leads, clients, deals, tasks, invoices, webhooks).

Example: Create a lead

curl -X POST https://api.heffl.com/api/v1/leads \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Smith",
    "email": "[e-mail]",
    "mobile": "[phone]",
    "title": "Product Demo Request"
  }'

Response format

All responses return JSON. Successful responses include the data directly:

Single resource:

{
  "id": "ld_abc123",
  "name": "Jane Smith",
  "email": "[e-mail]",
  "createdAt": "2025-01-15T10:30:00.000Z"
}

List of resources:

{
  "items": [...],
  "nextCursor": "cursor_value_or_null",
  "hasMore": true
}

Pagination

List endpoints support cursor pagination with these query parameters:

Parameter	Type	Default	Description
cursor	string	none	Cursor returned by the previous response
limit	number	20	Items per response (max 100)

curl "https://api.heffl.com/api/v1/leads?limit=25" \
  -H "x-api-key: YOUR_API_KEY"

Error handling

Error responses include a descriptive message:

{
  "code": "BAD_REQUEST",
  "message": "Invalid email address format"
}

Error codes

Code	HTTP Status	Description
UNAUTHORIZED	401	Missing or invalid API key
FORBIDDEN	403	API key valid but lacks permission
NOT_FOUND	404	Resource does not exist
BAD_REQUEST	400	Invalid request parameters
TOO_MANY_REQUESTS	429	Rate limit exceeded

Rate limiting

API requests are rate limited to 60 requests per minute per API key. If you exceed the limit, you’ll receive a 429 response with RateLimit-* headers indicating your current usage and reset time. Include retry logic with exponential backoff in your integration.

Custom fields

Entities that support custom fields (leads, deals, clients, invoices) accept them via the cf_ prefix in create and update requests:

{
  "name": "Jane Smith",
  "email": "[e-mail]",
  "cf_industry": "Technology",
  "cf_company_size": "50-100"
}

Custom field keys are derived from the field label (lowercased, spaces replaced with underscores, prefixed with cf_).

Available resources

CRM

Resource	Operations
Leads	Create, List, Get, Update, Delete
Clients	Create, List, Get, Update, Delete
Deals	Create, List, Get, Update, Delete
Tasks	Create, List, Get, Update, Delete

Reference data

Resource	Operations
Tags	List
Pipelines	List, Get
Products	List, Get
Lead Stages	List
Lead Sources	List

Webhooks

Resource	Description
Webhooks	Setup, security, delivery
Webhook Events	Event catalog with payloads

Browse the endpoint reference in the sidebar to see full request/response details with code examples in multiple languages.

SDKs and tools

The Heffl API follows REST conventions and works with any HTTP client. Use tools like:

• cURL for command-line testing
• Postman for interactive exploration
• Zapier / Make for no-code integrations
• Any HTTP library in your programming language of choice