# lead.stage_changed

A Lead moved between pipeline stages.

## Payload schema

- `object`
  - `api_version` (`any`)
  - `context` (`object`) - Present only when `source` is `api`. Identifies the acting project and API key.
    - `developer_platform_api_key_id` (`string | null`) - format: `uuid`
    - `developer_platform_project_id` (`string | null`) - format: `uuid`
  - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `data` (`object`)
    - `object` (`object`)
      - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
      - `current_stage` (`object`)
        - `created_at` (`string`) - 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.
        - `is_conversion_stage` (`boolean`) - Whether moving a Lead into this stage can start the Organization's Lead conversion workflow.
        - `is_lost_stage` (`boolean`) - Whether moving a lead into this stage marks it as lost or rejected.
        - `name` (`string`) - The display name of the stage.
        - `object` (`any`) - Discriminator value emitted at `object`.
        - `position` (`integer | null`) - The stage's display order within its pipeline.
        - `updated_at` (`string`) - 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.
      - `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`.
      - `links` (`object`) - URLs to related resources.
        - `lead` (`string`) - format: `uri`; The full URL of a related resource.
      - `object` (`any`) - Discriminator value emitted at `object`.
      - `previous_stage` (`any`) - The stage the lead moved from.
      - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `developer_platform_project_id` (`string | null`) - format: `uuid`; The project ID whose credential caused the change. Null for `dashboard` events.
  - `id` (`string`) - Event identifier prefixed with `evt_`.
  - `livemode` (`boolean`) - `false` for test-event deliveries.
  - `object` (`any`)
  - `source` (`string`) - enum: `api`, `dashboard`; Origin of the change. `api` means a Developer Platform mutation; `dashboard` means a Carebit-initiated change.
  - `type` (`any`)

### Example payload

```json
{
  "id": "evt_00000000-0000-4000-8000-000000000012",
  "object": "event",
  "api_version": "v1",
  "created_at": "2026-01-01T09:00:00Z",
  "data": {
    "object": {
      "id": "00000000-0000-4000-8000-000000000016",
      "object": "lead_stage_transition",
      "created_at": "2026-01-01T09:00:00Z",
      "current_stage": {
        "id": "00000000-0000-4000-8000-000000000015",
        "object": "lead_stage",
        "created_at": "2026-01-01T09:00:00Z",
        "is_conversion_stage": false,
        "is_lost_stage": false,
        "name": "Contact made",
        "position": 5,
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "lead": {
        "id": "00000000-0000-4000-8000-000000000013",
        "object": "lead",
        "address_line_1": "1 Test Street",
        "address_line_2": null,
        "attachments": [],
        "city": "Test City",
        "clinician": {
          "id": "00000000-0000-4000-8000-000000000002",
          "object": "clinician",
          "created_at": "2026-01-01T09:00:00Z",
          "display_name": "Dr Ada Lovelace",
          "email": "ada.lovelace@example.invalid",
          "first_name": "Ada",
          "last_name": "Lovelace",
          "links": {
            "bookings": "https://api.carebit.co/v1/bookings?clinician_id=00000000-0000-4000-8000-000000000002"
          },
          "medical_specialty": "General Medicine",
          "title": "Dr",
          "updated_at": "2026-01-01T09:00:00Z"
        },
        "country_code": "GB",
        "county": "Testshire",
        "created_at": "2026-01-01T09:00:00Z",
        "creation_source": "api",
        "date_of_birth": "1990-01-01",
        "display_name": "Ms Test Lead",
        "email": "test.lead@example.invalid",
        "first_name": "Test",
        "gdpr_consent_granted_at": "2026-01-01T09:00:00Z",
        "gdpr_consent_withdrawn_at": null,
        "internal_notes": "Asked about evening appointments with Dr Smith.",
        "is_converted_to_patient": false,
        "is_lost": false,
        "is_opted_out_of_sms": false,
        "is_signed_up_to_newsletters": false,
        "last_name": "Lead",
        "lead_type": "inquiry",
        "links": {
          "clinician": "https://api.carebit.co/v1/clinicians/00000000-0000-4000-8000-000000000002",
          "self": "https://api.carebit.co/v1/leads/00000000-0000-4000-8000-000000000013",
          "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": null,
        "phone": null,
        "phone_country_dial_code": null,
        "postcode": "TE1 1ST",
        "presenting_problem": "Persistent knee pain",
        "referral_notes": "Referred by Dr Patel at Riverside Medical.",
        "referral_source": "gp_practice",
        "service": {
          "id": "00000000-0000-4000-8000-000000000005",
          "object": "service",
          "created_at": "2026-01-01T09:00:00Z",
          "description": "Test consultation service.",
          "duration_minutes": 30,
          "is_bookable_online": true,
          "name": "Test consultation",
          "service_variants": [
            {
              "id": "00000000-0000-4000-8000-000000000006",
              "clinician_id": "00000000-0000-4000-8000-000000000002",
              "currency": "GBP",
              "description": "Standard consultation variant.",
              "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": 6200,
              "permits_remote_bookings": false
            }
          ],
          "tax_rate": null,
          "updated_at": "2026-01-01T09:00:00Z"
        },
        "sex": "female",
        "stage": {
          "id": "00000000-0000-4000-8000-000000000015",
          "object": "lead_stage",
          "created_at": "2026-01-01T09:00:00Z",
          "is_conversion_stage": false,
          "is_lost_stage": false,
          "name": "Contact made",
          "position": 5,
          "updated_at": "2026-01-01T09:00:00Z"
        },
        "title": "Ms",
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "links": {
        "lead": "https://api.carebit.co/v1/leads/00000000-0000-4000-8000-000000000013"
      },
      "previous_stage": {
        "id": "00000000-0000-4000-8000-000000000014",
        "object": "lead_stage",
        "created_at": "2026-01-01T09:00:00Z",
        "is_conversion_stage": false,
        "is_lost_stage": false,
        "name": "Enquiry",
        "position": 0,
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "updated_at": "2026-01-01T09:00:00Z"
    }
  },
  "developer_platform_project_id": null,
  "livemode": false,
  "source": "dashboard",
  "type": "lead.stage_changed"
}
```