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

# Leads API

> REST endpoints for creating, reading, updating, and deleting lead records in ParsaLink.

<div
  style={{ 
display: "inline-flex",
alignItems: "center",
gap: "8px",
background: "linear-gradient(90deg, #143D4E 0%, #1C758A 100%)",
color: "#FFFFFF",
fontSize: "12px",
fontWeight: "700",
marginBottom: "10px",
padding: "8px 14px",
letterSpacing: "0.08em",
textTransform: "uppercase",
borderRadius: "999px",
boxShadow: "0 8px 24px rgba(20, 61, 78, 0.18)"
}}
>
  Leads
</div>

## Endpoints

<div
  style={{

border: "1px solid rgba(48, 200, 202, 0.22)",
borderRadius: "16px",
padding: "16px 18px",
marginBottom: "20px",
color: "#2C768D",
boxShadow: "0 10px 26px rgba(28, 117, 138, 0.08)"
}}
  className="dark:!bg-[#0B0B0B] dark:!border-gray-800 dark:!text-cyan-300 dark:shadow-none"
>
  Available endpoints for managing leads.
</div>

<div
  style={{
background: "linear-gradient(135deg, rgba(20, 61, 78, 0.04) 0%, rgba(28, 117, 138, 0.08) 100%)",
border: "1px solid #CDD1D3",
borderRadius: "18px",
padding: "8px 12px 2px 12px",
marginBottom: "22px",
boxShadow: "0 10px 30px rgba(20, 61, 78, 0.06)"
}}
>
  | Method   | Path                       | Description             |
  | -------- | -------------------------- | ----------------------- |
  | `GET`    | `/api/leads/`              | List leads              |
  | `POST`   | `/api/leads/`              | Create a lead           |
  | `GET`    | `/api/leads/{id}/`         | Get a lead              |
  | `PATCH`  | `/api/leads/{id}/`         | Update a lead           |
  | `DELETE` | `/api/leads/{id}/`         | Delete a lead           |
  | `POST`   | `/api/leads/{id}/convert/` | Convert lead to contact |
</div>

***

<div
  style={{ 
display: "inline-flex",
alignItems: "center",
gap: "8px",
background: "rgba(48, 200, 202, 0.12)",
color: "#1C758A",
fontSize: "12px",
fontWeight: "700",
marginBottom: "10px",
padding: "8px 14px",
letterSpacing: "0.08em",
textTransform: "uppercase",
borderRadius: "999px",
border: "1px solid rgba(48, 200, 202, 0.28)"
}}
>
  Leads
</div>

## List Leads

```http theme={null}
GET /api/leads/
Authorization: Bearer <token>
```

<div
  style={{

border: "1px solid rgba(48, 200, 202, 0.22)",
borderRadius: "16px",
padding: "16px 18px",
marginBottom: "20px",
color: "#2C768D",
boxShadow: "0 10px 26px rgba(28, 117, 138, 0.08)"
}}
  className="dark:!bg-[#0B0B0B] dark:!border-gray-800 dark:!text-cyan-300 dark:shadow-none"
>
  Retrieve a paginated list of leads with optional filters.
</div>

**Query Parameters:**

<div
  style={{

border: "1px solid #CDD1D3",
borderRadius: "18px",
padding: "8px 12px 2px 12px",
marginBottom: "22px",
boxShadow: "0 10px 30px rgba(20, 61, 78, 0.05)"
}}
  className="dark:!bg-black dark:!border-gray-800 dark:shadow-none"
>
  | Parameter      | Type    | Description                       |
  | -------------- | ------- | --------------------------------- |
  | `page`         | integer | Page number                       |
  | `limit`        | integer | Results per page (max: 100)       |
  | `status`       | string  | Filter by status                  |
  | `source`       | string  | Filter by lead source             |
  | `assignedTo`   | string  | Filter by assigned user ID        |
  | `search`       | string  | Search by name, email, or company |
  | `createdAfter` | ISO8601 | Filter by creation date           |
</div>

**Response:**

```json theme={null}
{
  "count": 88,
  "next": "https://api.parsalink.io/api/leads/?page=2",
  "previous": null,
  "results": [
    {
      "id": "ld_01HX...",
      "firstName": "Marcus",
      "lastName": "Rodriguez",
      "email": "marcus@growthco.com",
      "phone": "+15551112222",
      "company": "GrowthCo",
      "status": "contacted",
      "source": "website_form",
      "assignedTo": "usr_01HX...",
      "leadScore": 7,
      "createdAt": "2025-03-10T08:00:00Z",
      "updatedAt": "2025-03-12T11:30:00Z"
    }
  ]
}
```

***

<div
  style={{ 
display: "inline-flex",
alignItems: "center",
gap: "8px",
background: "linear-gradient(90deg, #143D4E 0%, #1C758A 100%)",
color: "#FFFFFF",
fontSize: "12px",
fontWeight: "700",
marginBottom: "10px",
padding: "8px 14px",
letterSpacing: "0.08em",
textTransform: "uppercase",
borderRadius: "999px",
boxShadow: "0 8px 24px rgba(20, 61, 78, 0.18)"
}}
>
  Creation
</div>

## Create a Lead

```http theme={null}
POST /api/leads/
Authorization: Bearer <token>
Content-Type: application/json
```

<div
  style={{

border: "1px solid rgba(48, 200, 202, 0.22)",
borderRadius: "16px",
padding: "16px 18px",
marginBottom: "20px",
color: "#2C768D",
boxShadow: "0 10px 26px rgba(28, 117, 138, 0.08)"
}}
  className="dark:!bg-[#0B0B0B] dark:!border-gray-800 dark:!text-cyan-300 dark:shadow-none"
>
  Create a new lead with contact and qualification details.
</div>

**Request body:**

```json theme={null}
{
  "firstName": "Dana",
  "lastName": "Lee",
  "email": "dana@startup.io",
  "phone": "+15553334444",
  "company": "Startup IO",
  "status": "new",
  "source": "referral",
  "assignedTo": "usr_01HX...",
  "leadScore": 5,
  "notes": "Referred by Marcus at GrowthCo"
}
```

**Required fields:** `firstName` or `lastName`, `email`

**Response:** `201 Created`

***

<div
  style={{ 
display: "inline-flex",
alignItems: "center",
gap: "8px",
background: "rgba(255, 111, 97, 0.12)",
color: "#FF6F61",
fontSize: "12px",
fontWeight: "700",
marginBottom: "10px",
padding: "8px 14px",
letterSpacing: "0.08em",
textTransform: "uppercase",
borderRadius: "999px",
border: "1px solid rgba(255, 111, 97, 0.24)"
}}
>
  Lead Details
</div>

## Get a Lead

```http theme={null}
GET /api/leads/{id}/
Authorization: Bearer <token>
```

<div
  style={{

border: "1px solid rgba(48, 200, 202, 0.22)",
borderRadius: "16px",
padding: "16px 18px",
marginBottom: "20px",
color: "#2C768D",
boxShadow: "0 10px 26px rgba(28, 117, 138, 0.08)"
}}
  className="dark:!bg-[#0B0B0B] dark:!border-gray-800 dark:!text-cyan-300 dark:shadow-none"
>
  Retrieve full lead details including status and conversion data.
</div>

**Response:**

```json theme={null}
{
  "id": "ld_01HX...",
  "firstName": "Dana",
  "lastName": "Lee",
  "email": "dana@startup.io",
  "phone": "+15553334444",
  "company": "Startup IO",
  "status": "new",
  "source": "referral",
  "assignedTo": "usr_01HX...",
  "assignedToName": "Alex Johnson",
  "leadScore": 5,
  "emailOptOut": false,
  "emailBounced": false,
  "convertedAt": null,
  "convertedContactId": null,
  "notes": "Referred by Marcus at GrowthCo",
  "createdAt": "2025-03-15T14:00:00Z",
  "updatedAt": "2025-03-15T14:00:00Z"
}
```

***

<div
  style={{ 
display: "inline-flex",
alignItems: "center",
gap: "8px",
background: "rgba(48, 200, 202, 0.12)",
color: "#1C758A",
fontSize: "12px",
fontWeight: "700",
marginBottom: "10px",
padding: "8px 14px",
letterSpacing: "0.08em",
textTransform: "uppercase",
borderRadius: "999px",
border: "1px solid rgba(48, 200, 202, 0.28)"
}}
>
  Updates
</div>

## Update a Lead

```http theme={null}
PATCH /api/leads/{id}/
Authorization: Bearer <token>
Content-Type: application/json
```

<div
  style={{

border: "1px solid rgba(48, 200, 202, 0.22)",
borderRadius: "16px",
padding: "16px 18px",
marginBottom: "20px",
color: "#2C768D",
boxShadow: "0 10px 26px rgba(28, 117, 138, 0.08)"
}}
  className="dark:!bg-[#0B0B0B] dark:!border-gray-800 dark:!text-cyan-300 dark:shadow-none"
>
  Update lead status, score, or other attributes.
</div>

**Example — update status:**

```json theme={null}
{
  "status": "qualified",
  "leadScore": 9
}
```

**Response:** `200 OK` with the updated lead object.

***

<div
  style={{ 
display: "inline-flex",
alignItems: "center",
gap: "8px",
background: "linear-gradient(90deg, #143D4E 0%, #1C758A 100%)",
color: "#FFFFFF",
fontSize: "12px",
fontWeight: "700",
marginBottom: "10px",
padding: "8px 14px",
letterSpacing: "0.08em",
textTransform: "uppercase",
borderRadius: "999px",
boxShadow: "0 8px 24px rgba(20, 61, 78, 0.18)"
}}
>
  Conversion
</div>

## Convert a Lead

Convert a lead to a contact, optionally creating a linked account and opportunity.

```http theme={null}
POST /api/leads/{id}/convert/
Authorization: Bearer <token>
Content-Type: application/json
```

<div
  style={{

border: "1px solid rgba(48, 200, 202, 0.22)",
borderRadius: "16px",
padding: "16px 18px",
marginBottom: "20px",
color: "#2C768D",
boxShadow: "0 10px 26px rgba(28, 117, 138, 0.08)"
}}
  className="dark:!bg-[#0B0B0B] dark:!border-gray-800 dark:!text-cyan-300 dark:shadow-none"
>
  Convert a lead into CRM records including contact, account, and opportunity.
</div>

**Request body:**

```json theme={null}
{
  "createAccount": true,
  "accountName": "Startup IO",
  "createOpportunity": true,
  "opportunityName": "Startup IO — Enterprise",
  "opportunityValue": 12000,
  "opportunityStage": "qualification"
}
```

**Response:**

```json theme={null}
{
  "lead": { "id": "ld_01HX...", "status": "converted", "convertedAt": "2025-03-20T10:00:00Z" },
  "contact": { "id": "cnt_02HX...", "firstName": "Dana", "lastName": "Lee" },
  "account": { "id": "acc_03HX...", "name": "Startup IO" },
  "opportunity": { "id": "opp_04HX...", "name": "Startup IO — Enterprise", "value": 12000 }
}
```

***

<div
  style={{ 
display: "inline-flex",
alignItems: "center",
gap: "8px",
background: "rgba(255, 111, 97, 0.12)",
color: "#FF6F61",
fontSize: "12px",
fontWeight: "700",
marginBottom: "10px",
padding: "8px 14px",
letterSpacing: "0.08em",
textTransform: "uppercase",
borderRadius: "999px",
border: "1px solid rgba(255, 111, 97, 0.24)"
}}
>
  Deletion
</div>

## Delete a Lead

```http theme={null}
DELETE /api/leads/{id}/
Authorization: Bearer <token>
```

<div
  style={{

border: "1px solid rgba(48, 200, 202, 0.22)",
borderRadius: "16px",
padding: "16px 18px",
marginBottom: "20px",
color: "#2C768D",
boxShadow: "0 10px 26px rgba(28, 117, 138, 0.08)"
}}
  className="dark:!bg-[#0B0B0B] dark:!border-gray-800 dark:!text-cyan-300 dark:shadow-none"
>
  Permanently remove a lead.
</div>

**Response:** `204 No Content`

***

<div
  style={{ 
display: "inline-flex",
alignItems: "center",
gap: "8px",
background: "rgba(48, 200, 202, 0.12)",
color: "#1C758A",
fontSize: "12px",
fontWeight: "700",
marginBottom: "10px",
padding: "8px 14px",
letterSpacing: "0.08em",
textTransform: "uppercase",
borderRadius: "999px",
border: "1px solid rgba(48, 200, 202, 0.28)"
}}
>
  Status
</div>

## Lead Status Values

<div
  style={{
 border: "1px solid #CDD1D3",
borderRadius: "18px",
padding: "8px 12px 2px 12px",
marginBottom: "22px",
boxShadow: "0 10px 30px rgba(20, 61, 78, 0.05)"
}}
  className="dark:!bg-black dark:!border-gray-800 dark:shadow-none"
>
  | Value         | Label       |
  | ------------- | ----------- |
  | `new`         | New         |
  | `contacted`   | Contacted   |
  | `qualified`   | Qualified   |
  | `nurturing`   | Nurturing   |
  | `unqualified` | Unqualified |
  | `converted`   | Converted   |
  | `lost`        | Lost        |
</div>