> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heffl.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Legacy API (v1)

> Heffl REST API v1 — maintained for existing integrations

# Legacy API (v1)

<Warning>
  This is the legacy API (v1). For new integrations, use [API v2](/api-v2/introduction) — it has clearer resource paths, a consistent response envelope, and structured errors.
</Warning>

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:

```bash theme={null}
curl https://api.heffl.com/api/v1/leads \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

See [Authentication](/api-reference/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

```bash theme={null}
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": "jane@example.com",
    "mobile": "+1234567890",
    "title": "Product Demo Request"
  }'
```

## Response format

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

**Single resource:**

```json theme={null}
{
  "id": "ld_abc123",
  "name": "Jane Smith",
  "email": "jane@example.com",
  "createdAt": "2025-01-15T10:30:00.000Z"
}
```

**List of resources:**

```json theme={null}
{
  "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)             |

```bash theme={null}
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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "name": "Jane Smith",
  "email": "jane@example.com",
  "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](/api-reference/webhooks)             | Setup, security, delivery   |
| [Webhook Events](/api-reference/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