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

# Lead Management

> Create, retrieve, update, assign, and delete leads using the Lofty API.

This guide shows how to perform common lead operations. All examples assume you have a valid access token — see [Authentication](/authentication/overview).

## Create a lead

```bash theme={null}
curl -X POST https://api.lofty.com/v1.0/leads \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Jane",
    "lastName": "Smith",
    "emails": ["jane.smith@example.com"],
    "phones": ["5551234567"],
    "leadTypes": [2],
    "source": "Website"
  }'
```

Response:

```json theme={null}
{
  "leadId": 651095960136641
}
```

<Note>
  The `leadId` is returned as a JSON number. In JavaScript, parse the response as text and handle the ID as a string or `BigInt` to avoid precision loss.
</Note>

Omit `assignedUserId` to let Lofty's routing rules automatically assign the lead. Include it to skip routing and assign directly.

## Retrieve a lead

```bash theme={null}
curl https://api.lofty.com/v1.0/leads/563172647619608 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

## List and filter leads

Use query parameters to paginate and filter:

```bash theme={null}
curl "https://api.lofty.com/v1.0/leads?limit=20&offset=0&stage=New+Lead&sort=LastActivity&desc=true" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

Key filters: `assignedUserId`, `stage`, `source`, `email`, `phone`, `key` (fuzzy search), `anyTags`, `allTags`, `contacted`.

Use `scrollId` from the response for efficient cursor-based pagination over large result sets.

## Update a lead

Send only the fields you want to change:

```bash theme={null}
curl -X PUT https://api.lofty.com/v1.0/leads/563172647619608 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "stage": "Contacted",
    "tags": [{"tagName": "follow-up"}]
  }'
```

Note that `tags` replaces the lead's entire tag set. To add tags without touching existing ones use `tagsAdd`; to remove specific tags by name use `tagsRemove`; to remove every tag set `clearAllTags: true` (takes precedence over the other tag fields).

## Assign a lead

```bash theme={null}
curl -X POST https://api.lofty.com/v1.0/leads/563172647619608/assignment \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "assignees": [{"userId": 10000000514}]
  }'
```

To preview which agent routing would select without creating a lead, use the [Preview Routing](/api-reference/leads/resolve-assignees-by-lead-info) endpoint.

## Delete a lead

`DELETE /v1.0/leads/{leadId}` moves the lead to the trash — it is **not permanently deleted**. A `reason` parameter is required and stored for audit purposes.

```bash theme={null}
curl -X DELETE "https://api.lofty.com/v1.0/leads/563172647619608?reason=Duplicate+record" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

<Note>
  Trashed leads may be recoverable from the Lofty CRM interface. The API does not provide a restore endpoint.
</Note>

## Monitor lead changes

Subscribe to [Lead Info webhooks](/concepts/webhooks#2-lead-info) (listId: 2) to receive real-time notifications when leads are created, updated, or deleted.

## Next steps

* [Leads concept](/concepts/leads) — understand the data model and lifecycle
* [Leads API reference](/api-reference/leads/overview) — full endpoint documentation
* [Communication guide](/guides/communication) — log calls, emails, and texts for leads