# List Leads

`GET /v1/leads`

Returns the Organization's patient enquiries and referrals. Results include leads in a lost stage, including a lead discarded when it was marked lost. A discarded lead that is not in a lost stage is omitted. Use `is_lost` to return only one group, and `stage_id` to return leads in one stage. Carebit Pro is required.

**Required API scopes:** `leads.read`

## Parameters

- `clinician_id` (query, `string`) - Filter by the identifier of the assigned clinician.
- `email` (query, `string`) - Filter by exact email address.
- `is_lost` (query, `boolean`) - When `true`, only leads whose current stage is a lost stage are returned. When `false`, only leads in any other stage are returned. Omit to return both. A lost stage has the `mark_lead_lost` action, or the title Lost or Rejected.
- `service_id` (query, `string`) - Filter by the Service the Lead is enquiring about.
- `stage_id` (query, `string`) - Filter by the identifier of the lead's current pipeline stage. The stage must belong to one of the Organization's lead pipelines.
- `updated_since` (query, `string`) - Return Leads updated at or after this ISO 8601 timestamp.
- `limit` (query, `integer`) - The maximum number of items to return. Defaults to `25`; the maximum is `100`.
- `starting_after` (query, `string`) - Return items after this resource ID. You cannot use this with `cursor`.
- `cursor` (query, `string`) - The `next_cursor` value from the previous page. You cannot use this with `starting_after`.

## Response `200`

Paginated list of `Lead` objects.

- `any`

### Example

```json
{
  "object": "list",
  "data": [
    {
      "id": "00000000-0000-4000-8000-00000000000c",
      "object": "lead",
      "address_line_1": "10 Harley Street",
      "address_line_2": "Marylebone",
      "attachments": [
        {
          "id": "f631636b-32e2-41be-8e4f-0a34ee0d5d59",
          "download_url": "https://files.example.invalid/document.pdf?signature=test",
          "filename": "referral-letter.pdf"
        }
      ],
      "city": "London",
      "clinician": {
        "id": "00000000-0000-4000-8000-000000000002",
        "object": "clinician",
        "created_at": "2026-01-01T09:00:00Z",
        "display_name": "Dr Alex Morgan",
        "email": "alex.morgan@example.com",
        "first_name": "Alex",
        "last_name": "Morgan",
        "links": {
          "bookings": "https://api.carebit.co/v1/bookings?clinician_id=00000000-0000-4000-8000-000000000002"
        },
        "medical_specialty": "Cardiology",
        "title": "Dr",
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "country_code": "GB",
      "county": "Greater London",
      "created_at": "2026-01-01T09:00:00Z",
      "creation_source": "api",
      "date_of_birth": "1990-01-01",
      "display_name": "Dr Alex Morgan",
      "email": "alex.morgan@example.com",
      "first_name": "Alex",
      "form_responses": [
        {
          "id": "adf881b8-4eed-42c0-8903-515f6cc8a134",
          "form_name": "New patient inquiry",
          "form_type": "inquiry_form",
          "submitted_at": "2026-01-01T09:00:00Z",
          "url": "https://files.example.invalid/document.pdf?signature=test"
        }
      ],
      "gdpr_consent_granted_at": "2026-01-01T09:00:00Z",
      "gdpr_consent_withdrawn_at": "2026-01-01T09:00:00Z",
      "internal_notes": "Asked about evening appointments with Dr Smith.",
      "is_converted_to_patient": true,
      "is_lost": false,
      "is_opted_out_of_sms": false,
      "is_signed_up_to_newsletters": true,
      "last_name": "Morgan",
      "lead_type": "inquiry",
      "links": {
        "clinician": "https://api.carebit.co/v1/clinicians/00000000-0000-4000-8000-000000000002",
        "remote_file_import_batch": "https://api.carebit.co/v1/remote_file_import_batches/00000000-0000-4000-8000-00000000000a",
        "self": "https://api.carebit.co/v1/leads/00000000-0000-4000-8000-00000000000c",
        "service": "https://api.carebit.co/v1/services/00000000-0000-4000-8000-000000000005"
      },
      "mobile": "7700900123",
      "mobile_country_dial_code": "GB",
      "organization_privacy_policy_consent_granted_at": "2026-01-01T09:00:00Z",
      "patient_id": "00000000-0000-4000-8000-000000000004",
      "phone": "2071234567",
      "phone_country_dial_code": "GB",
      "postcode": "W1G 9PF",
      "presenting_problem": "Persistent right knee pain",
      "referral_notes": "Referred by Dr Patel at Riverside Medical.",
      "referral_source": "consultant",
      "referred_by_clinician_id": "b5ac896f-f746-4df1-899a-c12d33b84b2d",
      "referred_by_organization_id": "8cda84a9-bf46-4f81-8f3c-66dd352e95db",
      "remote_file_import_batch_id": "00000000-0000-4000-8000-00000000000a",
      "service": {
        "id": "00000000-0000-4000-8000-000000000005",
        "object": "service",
        "created_at": "2026-01-01T09:00:00Z",
        "description": "An initial consultation at the Harley Street Clinic.",
        "duration_minutes": 30,
        "is_bookable_online": true,
        "name": "Initial consultation",
        "service_variants": [
          {
            "id": "00000000-0000-4000-8000-000000000006",
            "clinician_id": "00000000-0000-4000-8000-000000000002",
            "currency": "GBP",
            "description": "An initial consultation at the Harley Street Clinic.",
            "links": {
              "clinician": "https://api.carebit.co/v1/clinicians/00000000-0000-4000-8000-000000000002",
              "location": "https://api.carebit.co/v1/locations/00000000-0000-4000-8000-000000000003"
            },
            "location_id": "00000000-0000-4000-8000-000000000003",
            "net_price": 1,
            "permits_remote_bookings": true
          }
        ],
        "tax_rate": {
          "id": "00000000-0000-4000-8000-000000000029",
          "description": "An initial consultation at the Harley Street Clinic.",
          "percentage": 20,
          "title": "VAT"
        },
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "sex": "female",
      "stage": {
        "id": "00000000-0000-4000-8000-00000000000d",
        "object": "lead_stage",
        "created_at": "2026-01-01T09:00:00Z",
        "is_conversion_stage": true,
        "is_lost_stage": true,
        "name": "Initial consultation",
        "position": 1,
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "title": "Dr",
      "updated_at": "2026-01-01T09:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": "eyJzdGFydF90aW1lIjoiMjAyNi0wMS0wMVQwOTowMDowMFoifQ",
  "url": "/v1/leads"
}
```

## Response `400`

A filter or pagination parameter is invalid.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, the project is disabled, or the Organization does not have Carebit Pro.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `404`

The `stage_id` was not found on a lead pipeline in the Organization.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X GET "https://api.carebit.co/v1/leads" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"
```

```javascript
const response = await fetch("https://api.carebit.co/v1/leads", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
  },
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests

response = requests.get(
    "https://api.carebit.co/v1/leads",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"

response = HTTParty.get(
  "https://api.carebit.co/v1/leads",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}"
  }
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->get("https://api.carebit.co/v1/leads", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```