Skip to main content

​
API Reference

The Heffl API lets you programmatically access and manage your CRM, sales, and project data. Use it to build custom integrations, sync data with external systems, or automate workflows.

​
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) for leads, clients, and deals. Task IDs are numeric.

​
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": "[email protected]",
    "mobile": "+1234567890",
    "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": "[email protected]",
  "createdAt": "2025-01-15T10:30:00.000Z"
}
List of resources: 
{
  "items": [...],
  "meta": {
    "count": 20,
    "total": 150,
    "pageNo": 1,
    "pageSize": 20
  }
}

​
Pagination

List endpoints support pagination with these query parameters:
ParameterTypeDefaultDescription
pageNonumber1Page number (1-indexed)
pageSizenumber20Items per page (max 100)
curl "https://api.heffl.com/api/v1/leads?pageNo=2&pageSize=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

CodeHTTP StatusDescription
UNAUTHORIZED401Missing or invalid API key
FORBIDDEN403API key valid but lacks permission
NOT_FOUND404Resource does not exist
BAD_REQUEST400Invalid request parameters
TOO_MANY_REQUESTS429Rate 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) accept them via the cf_ prefix in create and update requests: 
{
  "name": "Jane Smith",
  "email": "[email protected]",
  "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

ResourceOperations
LeadsCreate, List, Get, Update, Delete
ClientsCreate, List, Get, Update, Delete
DealsCreate, List, Get, Update, Delete
TasksCreate, List, Get, Update, Delete

​
Reference data

ResourceOperations
TagsList
PipelinesList, Get
ProductsList, Get
Lead StagesList
Lead SourcesList

​
Webhooks

ResourceDescription
WebhooksSetup, security, delivery
Webhook EventsEvent 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