# Get a Lead

`GET /v1/leads/:id`

Returns a patient inquiry or referral from the Organization. Carebit Pro is required.

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

## Parameters

- `id` (path, `string`) (required)

## Response `200`

The requested `Lead`.

- `object`
  - `address_line_1` (`string | null`) - The primary address line of the lead.
  - `address_line_2` (`string | null`) - The secondary address line of the lead.
  - `attachments` (`array`) - The files attached to the lead.
    - `items` (`object`)
      - `download_url` (`string | null`) - format: `uri`; The short-lived signed download URL for the attachment. Null while the malware scan is not complete.
      - `filename` (`string | null`) - The original filename of the attachment.
      - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - `city` (`string | null`) - The city in the lead's postal address.
  - `clinician` (`any`) - The clinician the lead is assigned to, when recorded.
  - `country_code` (`string | null`) - The ISO 3166-1 alpha-2 country code for the postal address, such as `GB` for the United Kingdom.
  - `county` (`string | null`) - The county or region in the lead's postal address.
  - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `creation_source` (`string | null`) - How the Lead was created. `api` means the record was created through the Developer Platform. Read-only.
  - `date_of_birth` (`string | null`) - format: `date`; The date of birth of the lead, in ISO 8601 format (YYYY-MM-DD).
  - `display_name` (`string | null`) - The formatted display name of the lead, including their title when recorded.
  - `email` (`string | null`) - format: `email`; The contact email address of the lead.
  - `first_name` (`string`) - The first name of the lead.
  - `gdpr_consent_granted_at` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `gdpr_consent_withdrawn_at` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - `internal_notes` (`string | null`) - Internal notes shown in the Notes box next to presenting problem on the Carebit lead enquiry screen. Distinct from `referral_notes`.
  - `is_converted_to_patient` (`boolean`) - Whether the lead has been converted to a patient. Read-only.
  - `is_lost` (`boolean`) - Whether the lead has been marked as lost. Read-only.
  - `is_opted_out_of_sms` (`boolean`) - Whether the lead has opted out of SMS communication.
  - `is_signed_up_to_newsletters` (`boolean`) - Whether the lead has signed up to receive newsletters.
  - `last_name` (`string`) - The last name of the lead.
  - `lead_type` (`string`) - enum: `inquiry`, `referral`; Whether the record is a patient inquiry or a referral.
  - `links` (`object`) - URLs to related resources. `remote_file_import_batch` is present on create responses when at least one attachment was submitted.
    - `clinician` (`string | null`) - format: `uri`; The full URL of a related resource.
    - `remote_file_import_batch` (`string`) - format: `uri`; The full URL of a related resource.
    - `self` (`string`) - format: `uri`; The full URL of a related resource.
    - `service` (`string | null`) - format: `uri`; The full URL of a related resource.
  - `mobile` (`string | null`) - The mobile phone number of the lead, without the country dial code.
  - `mobile_country_dial_code` (`string | null`) - The ISO 3166-1 alpha-2 country code that selects the international dial code for `mobile`, for example `GB` selects `+44`.
  - `object` (`any`) - Discriminator value emitted at `object`.
  - `organization_privacy_policy_consent_granted_at` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `patient_id` (`string | null`) - format: `uuid`; The identifier of the Patient this Lead was converted to. Null until conversion. Read-only.
  - `phone` (`string | null`) - The landline phone number of the lead, without the country dial code.
  - `phone_country_dial_code` (`string | null`) - The ISO 3166-1 alpha-2 country code that selects the international dial code for `phone`, for example `GB` selects `+44`.
  - `postcode` (`string | null`) - The postal code in the lead's postal address.
  - `presenting_problem` (`string | null`) - The presenting problem the lead described. Shown next to Notes on the Carebit lead enquiry screen.
  - `referral_notes` (`string | null`) - The referral notes shown on the Carebit lead enquiry screen.
  - `referral_source` (`string | null`) - enum: `consultant`, `embassy`, `family_or_friend`, `gp_practice`, `hospital`, `insurance_company`, `physiotherapist`, `presentation_talk`, `previous_patient`, `private_practice`, `search_engine`, `self_referral`, `social_media`, `website`, `other`, `null`; The referral source shown on the Carebit lead enquiry screen.
  - `remote_file_import_batch_id` (`string`) - format: `uuid`; The identifier of the remote file import batch created for the submitted attachments. Present on create responses when at least one attachment was submitted.
  - `service` (`any`) - The Service the Lead is inquiring about, when recorded.
  - `sex` (`string | null`) - The sex of the Lead as supplied on the inquiry.
  - `stage` (`any`) - The current pipeline stage of the lead. Read-only; use `stage_id` when updating the lead.
  - `title` (`string | null`) - The personal title of the lead, when recorded.
  - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.

### Example

```json
{
  "id": "c0b9e949-67e8-4a50-8038-6168ab7f1d70",
  "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": "2b3c4d5e-6f70-489a-9bcd-ef0123456789",
    "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=2b3c4d5e-6f70-489a-9bcd-ef0123456789"
    },
    "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",
  "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/2b3c4d5e-6f70-489a-9bcd-ef0123456789",
    "remote_file_import_batch": "https://api.carebit.co/v1/remote_file_import_batches/ebc38802-f219-4c7b-8136-8e963a0c69e0",
    "self": "https://api.carebit.co/v1/leads/c0b9e949-67e8-4a50-8038-6168ab7f1d70",
    "service": "https://api.carebit.co/v1/services/5e6f7081-92a3-4bcd-8ef0-123456789abc"
  },
  "mobile": "7700900123",
  "mobile_country_dial_code": "GB",
  "organization_privacy_policy_consent_granted_at": "2026-01-01T09:00:00Z",
  "patient_id": "1a2b3c4d-5e6f-4789-8abc-def012345678",
  "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",
  "remote_file_import_batch_id": "ebc38802-f219-4c7b-8136-8e963a0c69e0",
  "service": {
    "id": "5e6f7081-92a3-4bcd-8ef0-123456789abc",
    "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": "6f708192-a3b4-4cde-9f01-23456789abcd",
        "clinician_id": "2b3c4d5e-6f70-489a-9bcd-ef0123456789",
        "currency": "GBP",
        "description": "An initial consultation at the Harley Street Clinic.",
        "links": {
          "clinician": "https://api.carebit.co/v1/clinicians/2b3c4d5e-6f70-489a-9bcd-ef0123456789",
          "location": "https://api.carebit.co/v1/locations/3c4d5e6f-7081-49ab-acde-f0123456789a"
        },
        "location_id": "3c4d5e6f-7081-49ab-acde-f0123456789a",
        "net_price": 1,
        "permits_remote_bookings": true
      }
    ],
    "tax_rate": {
      "id": "211b60c7-ec1b-41b4-8a29-e855209bc694",
      "description": "An initial consultation at the Harley Street Clinic.",
      "percentage": 20,
      "title": "VAT"
    },
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "sex": "female",
  "stage": {
    "id": "306f78be-ffcc-472b-812e-a63d99e76e61",
    "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"
}
```

## 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`

Error response.

- `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/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"
```

```javascript
const response = await fetch("https://api.carebit.co/v1/leads/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", {
  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/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c",
    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/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c",
  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/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```