Carebit API

Leads

Patient inquiries and referrals received by the Organization.

Endpoints

Scroll this page to read every Leads endpoint, or jump to one below.

get/v1/lead_pipelinesList Lead pipelines and stages
get/v1/leadsList Leads
post/v1/leadsCreate a Lead
get/v1/leads/:idGet a Lead
patch/v1/leads/:idUpdate a Lead

get/v1/lead_pipelines

List Lead pipelines and stages

Returns the Organization's Lead and referral pipelines. When updating a Lead, use a stage from the pipeline for its lead_type. Carebit Pro is required.

Required API scopes: leads.read

Responses

200

Paginated list of LeadPipeline objects.

dataarrayrequired
- itemsobject
  - created_atstring · date-timerequired
    An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
  - idstring · uuidrequired
    The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - lead_typestringrequired
    Whether this pipeline manages patient inquiries or referrals.
    Allowed values: inquiry | referral
  - namestringrequired
    The display name of the pipeline.
  - objectanyrequired
    Discriminator value emitted at object.
  - stagesarrayrequired
    The ordered stages available in the pipeline.
    - itemsobject
      - created_atstring · date-timerequired
        An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
      - idstring · uuidrequired
        The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
      - is_conversion_stagebooleanrequired
        Whether moving a Lead into this stage can start the Organization's Lead conversion workflow.
      - is_lost_stagebooleanrequired
        Whether moving a lead into this stage marks it as lost or rejected.
      - namestringrequired
        The display name of the stage.
      - objectanyrequired
        Discriminator value emitted at object.
      - positioninteger | nullrequired
        The stage's display order within its pipeline.
      - updated_atstring · date-timerequired
        An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
  - updated_atstring · date-timerequired
    An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
has_morebooleanrequired
Whether another page is available after next_cursor.
next_cursorstring | nullrequired
The value to pass as cursor for the next page. Null on the last page.
objectanyrequired
Always list.
urlstringrequired
The API path that returned this list.

Example

{
  "object": "list",
  "data":  … ]
     … }
      "id": "5412a51a-d3f9-44d8-8291-939bc55c434e",
      "object": "lead_pipeline",
      "created_at": "2026-01-01T09:00:00Z",
      "lead_type": "inquiry",
      "name": "Initial consultation",
      "stages":  … ]
         … }
          "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"
        }
      ],
      "updated_at": "2026-01-01T09:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": "eyJzdGFydF90aW1lIjoiMjAyNi0wMS0wMVQwOTowMDowMFoifQ",
  "url": "/v1/lead_pipelines"
}

401

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

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "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"
  }
}

403

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

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "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"
  }
}

429

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

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "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"
  }
}

Request

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

200 response

{
  "object": "list",
  "data":  … ]
     … }
      "id": "5412a51a-d3f9-44d8-8291-939bc55c434e",
      "object": "lead_pipeline",
      "created_at": "2026-01-01T09:00:00Z",
      "lead_type": "inquiry",
      "name": "Initial consultation",
      "stages":  … ]
         … }
          "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"
        }
      ],
      "updated_at": "2026-01-01T09:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": "eyJzdGFydF90aW1lIjoiMjAyNi0wMS0wMVQwOTowMDowMFoifQ",
  "url": "/v1/lead_pipelines"
}

401 response

{
  "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"
  }
}

403 response

{
  "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"
  }
}

429 response

{
  "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"
  }
}

get/v1/leads

List Leads

Returns the Organization's patient inquiries and referrals. By default, results include active and lost Leads. Use is_lost to return only one group. 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 lost Leads are returned. When false, only active Leads are returned. Omit to return both.
service_id
query
string
Filter by the Service the Lead is inquiring about.
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.

Responses

200

Paginated list of Lead objects.

dataarrayrequired
- itemsobject
  - address_line_1string | nullrequired
    The primary address line of the lead.
  - address_line_2string | nullrequired
    The secondary address line of the lead.
  - attachmentsarrayrequired
    The files attached to the lead.
    - itemsobject
      - download_urlstring | null · urirequired
        The short-lived signed download URL for the attachment. Null while the malware scan is not complete.
      - filenamestring | nullrequired
        The original filename of the attachment.
      - idstring · uuidrequired
        The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - citystring | nullrequired
    The city in the lead's postal address.
  - clinicianobject | nullrequired
    The clinician the lead is assigned to, when recorded.
    - created_atstring · date-timerequired
      An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
    - display_namestringrequired
      The formatted name of the clinician, including title.
    - emailstring | null · emailrequired
      The practice contact email of the clinician within the organization.
    - first_namestring | nullrequired
      The first name of the clinician.
    - idstring · uuidrequired
      The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
    - last_namestring | nullrequired
      The last name of the clinician.
    - linksobjectrequired
      URLs to related resources.
      - bookingsstring · urirequired
        URL to list Bookings for this Clinician.
    - medical_specialtystring | nullrequired
      The medical specialty of the clinician, when recorded.
    - objectanyrequired
      Discriminator value emitted at object.
    - titlestring | nullrequired
      The professional or personal title of the clinician, when recorded, such as Dr.
    - updated_atstring · date-timerequired
      An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
  - country_codestring | nullrequired
    The ISO 3166-1 alpha-2 country code for the postal address, such as GB for the United Kingdom.
  - countystring | nullrequired
    The county or region in the lead's postal address.
  - created_atstring · date-timerequired
    An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
  - creation_sourcestring | nullrequired
    How the Lead was created. api means the record was created through the Developer Platform. Read-only.
  - date_of_birthstring | null · daterequired
    The date of birth of the lead, in ISO 8601 format (YYYY-MM-DD).
  - display_namestring | nullrequired
    The formatted display name of the lead, including their title when recorded.
  - emailstring | null · emailrequired
    The contact email address of the lead.
  - first_namestringrequired
    The first name of the lead.
  - gdpr_consent_granted_atstring | null · date-timerequired
    An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
  - gdpr_consent_withdrawn_atstring | null · date-timerequired
    An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
  - idstring · uuidrequired
    The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - internal_notesstring | nullrequired
    Internal notes shown in the Notes box next to presenting problem on the Carebit lead enquiry screen. Distinct from referral_notes.
  - is_converted_to_patientbooleanrequired
    Whether the lead has been converted to a patient. Read-only.
  - is_lostbooleanrequired
    Whether the lead has been marked as lost. Read-only.
  - is_opted_out_of_smsbooleanrequired
    Whether the lead has opted out of SMS communication.
  - is_signed_up_to_newslettersbooleanrequired
    Whether the lead has signed up to receive newsletters.
  - last_namestringrequired
    The last name of the lead.
  - lead_typestringrequired
    Whether the record is a patient inquiry or a referral.
    Allowed values: inquiry | referral
  - linksobjectrequired
    URLs to related resources. remote_file_import_batch is present on create responses when at least one attachment was submitted.
    - clinicianstring | null · urirequired
      The full URL of a related resource.
    - remote_file_import_batchstring · uri
      The full URL of a related resource.
    - selfstring · urirequired
      The full URL of a related resource.
    - servicestring | null · urirequired
      The full URL of a related resource.
  - mobilestring | nullrequired
    The mobile phone number of the lead, without the country dial code.
  - mobile_country_dial_codestring | nullrequired
    The ISO 3166-1 alpha-2 country code that selects the international dial code for mobile, for example GB selects +44.
  - objectanyrequired
    Discriminator value emitted at object.
  - organization_privacy_policy_consent_granted_atstring | null · date-timerequired
    An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
  - patient_idstring | null · uuidrequired
    The identifier of the Patient this Lead was converted to. Null until conversion. Read-only.
  - phonestring | nullrequired
    The landline phone number of the lead, without the country dial code.
  - phone_country_dial_codestring | nullrequired
    The ISO 3166-1 alpha-2 country code that selects the international dial code for phone, for example GB selects +44.
  - postcodestring | nullrequired
    The postal code in the lead's postal address.
  - presenting_problemstring | nullrequired
    The presenting problem the lead described. Shown next to Notes on the Carebit lead enquiry screen.
  - referral_notesstring | nullrequired
    The referral notes shown on the Carebit lead enquiry screen.
  - referral_sourcestring | nullrequired
    The referral source shown on the Carebit lead enquiry screen.
    Allowed values: 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
  - remote_file_import_batch_idstring · 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.
  - serviceobject | nullrequired
    The Service the Lead is inquiring about, when recorded.
    - created_atstring · date-timerequired
      An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
    - descriptionstring | nullrequired
      The description of the service shown to staff members and patients.
    - duration_minutesinteger | nullrequired
      The scheduled duration of the service, in minutes.
    - idstring · uuidrequired
      The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
    - is_bookable_onlinebooleanrequired
      Whether patients can book this service online in the Patient Portal.
    - namestringrequired
      The display name of the service.
    - objectanyrequired
      Discriminator value emitted at object.
    - service_variantsarrayrequired
      The bookable variants of this service.
      - itemsobject
        clinician_idstring | null · uuidrequired
        The identifier of the clinician assigned to this service variant, when the variant is clinician-specific.
        currencystring | nullrequired
        The ISO 4217 currency code used for this service variant. Must be one of chf, eur, gbp, or usd.
        descriptionstring | nullrequired
        The description of this service variant.
        idstring · uuidrequired
        The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
        linksobjectrequired
        URLs to related resources.
        clinicianstring | null · urirequired
        The full URL of a related resource.
        locationstring | null · urirequired
        The full URL of a related resource.
        location_idstring | null · uuidrequired
        The identifier of the location assigned to this service variant, when the variant is location-specific.
        net_priceinteger | nullrequired
        The net price of this service variant, before tax, in the currency's minor units.
        permits_remote_bookingsbooleanrequired
        Whether this service variant can be used for remote bookings.
    - tax_rateobject | nullrequired
      The tax rate applied to this service. Null when no tax rate is set.
      - descriptionstring | nullrequired
        The description of when the tax rate applies.
      - idstring · uuidrequired
        The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
      - percentagenumberrequired
        The tax rate as a percentage from 0 to 100.
      - titlestringrequired
        The display name of the tax rate, for example 20% VAT.
    - updated_atstring · date-timerequired
      An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
  - sexstring | nullrequired
    The sex of the Lead as supplied on the inquiry.
  - stageobject | nullrequired
    The current pipeline stage of the lead. Read-only; use stage_id when updating the lead.
    - created_atstring · date-timerequired
      An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
    - idstring · uuidrequired
      The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
    - is_conversion_stagebooleanrequired
      Whether moving a Lead into this stage can start the Organization's Lead conversion workflow.
    - is_lost_stagebooleanrequired
      Whether moving a lead into this stage marks it as lost or rejected.
    - namestringrequired
      The display name of the stage.
    - objectanyrequired
      Discriminator value emitted at object.
    - positioninteger | nullrequired
      The stage's display order within its pipeline.
    - updated_atstring · date-timerequired
      An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
  - titlestring | nullrequired
    The personal title of the lead, when recorded.
  - updated_atstring · date-timerequired
    An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
has_morebooleanrequired
Whether another page is available after next_cursor.
next_cursorstring | nullrequired
The value to pass as cursor for the next page. Null on the last page.
objectanyrequired
Always list.
urlstringrequired
The API path that returned this list.

Example

{
  "object": "list",
  "data":  … ]
     … }
      "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"
    }
  ],
  "has_more": false,
  "next_cursor": "eyJzdGFydF90aW1lIjoiMjAyNi0wMS0wMVQwOTowMDowMFoifQ",
  "url": "/v1/leads"
}

400

A filter or pagination parameter is invalid.

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "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"
  }
}

401

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

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "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"
  }
}

403

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

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "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"
  }
}

429

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

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "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"
  }
}

Request

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

200 response

{
  "object": "list",
  "data":  … ]
     … }
      "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"
    }
  ],
  "has_more": false,
  "next_cursor": "eyJzdGFydF90aW1lIjoiMjAyNi0wMS0wMVQwOTowMDowMFoifQ",
  "url": "/v1/leads"
}

400 response

{
  "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"
  }
}

401 response

{
  "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"
  }
}

403 response

{
  "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"
  }
}

429 response

{
  "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"
  }
}

post/v1/leads

Create a Lead

Creates a patient inquiry or referral in the Organization. Attachments can use a public HTTPS URL or Base64-encoded data. Carebit validates and scans them for malware in the background; poll the returned remote file import batch for their status. Each successful request creates a new Lead unless the response is an Idempotency-Key replay. Carebit Pro is required.

Required API scopes: leads.create

Parameters

Idempotency-Key
header · required
string
Client-generated idempotency key. Required for every POST/PATCH write. Replay of the same key with the same body returns the stored response with an Idempotency-Replayed: true header. Same key + different body returns 422 idempotency_key_reused. A duplicate that arrives while the first request is still in flight returns 409 idempotency_conflict with Retry-After: 1.

Request body

application/json

address_line_1string | null
The primary address line of the lead.
address_line_2string | null
The secondary address line of the lead.
attachmentsarray
The files to attach to the Lead in the background. Provide either url or file_base64 for each file. Carebit validates and scans every file for malware.
- itemsobject
  - file_base64string · byte
    The file bytes encoded as Base64. Provide this with filename instead of url. The decoded file can be at most 7 MB.
  - filenamestring | null
    The filename to use for the attachment. Required with file_base64; defaults to the remote file's filename for URL sources.
  - urlstring · uri
    The public HTTPS URL that Carebit can fetch.
citystring | null
The city in the lead's postal address.
clinician_idstring | null · uuid
The identifier of the clinician the lead is assigned to. Must be a clinician enabled in your Organization. Pass null to unassign.
country_codestring | null
The uppercase ISO 3166-1 alpha-2 country code for the lead's postal address.
countystring | null
The county or region in the lead's postal address.
date_of_birthstring | null · date
The date of birth of the lead, in ISO 8601 format (YYYY-MM-DD).
emailstring | null · email
The contact email address of the lead.
first_namestringrequired
The first name of the lead. Required on create.
gdpr_consent_granted_atstring | null · date-time
The ISO 8601 UTC timestamp at which the lead granted GDPR consent.
gdpr_consent_withdrawn_atstring | null · date-time
The ISO 8601 UTC timestamp at which the lead withdrew GDPR consent.
internal_notesstring | null
Internal notes shown in the Notes box next to presenting problem on the Carebit lead enquiry screen. Distinct from referral_notes.
is_opted_out_of_smsboolean
Whether the lead has opted out of SMS communication.
is_signed_up_to_newslettersboolean
Whether the lead has signed up to receive newsletters.
last_namestringrequired
The last name of the lead. Required on create.
lead_typestring
Whether to treat the record as a patient inquiry or a referral. Defaults to inquiry on create.
Allowed values: inquiry | referral
mobilestring | null
The mobile phone number of the lead, without the country dial code.
mobile_country_dial_codestring | null
The ISO 3166-1 alpha-2 country code that selects the international dial code for mobile, for example GB selects +44.
organization_privacy_policy_consent_granted_atstring | null · date-time
The ISO 8601 UTC timestamp at which the lead granted consent to the Organization's privacy policy.
phonestring | null
The landline phone number of the lead, without the country dial code.
phone_country_dial_codestring | null
The ISO 3166-1 alpha-2 country code that selects the international dial code for phone, for example GB selects +44.
postcodestring | null
The postal code in the lead's postal address.
presenting_problemstring | null
The presenting problem the lead described. Shown next to Notes on the Carebit lead enquiry screen.
referral_notesstring | null
The referral notes shown on the Carebit lead enquiry screen.
referral_sourcestring | null
The referral source shown on the Carebit lead enquiry screen.
Allowed values: 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
service_idstring | null · uuid
The Service the Lead is inquiring about. It must belong to your Organization. Pass null to clear.
sexstring | null
The sex of the Lead as supplied on the inquiry.
titlestring | null
The personal title of the lead, when recorded.

Responses

201

Lead created.

address_line_1string | nullrequired
The primary address line of the lead.
address_line_2string | nullrequired
The secondary address line of the lead.
attachmentsarrayrequired
The files attached to the lead.
- itemsobject
  - download_urlstring | null · urirequired
    The short-lived signed download URL for the attachment. Null while the malware scan is not complete.
  - filenamestring | nullrequired
    The original filename of the attachment.
  - idstring · uuidrequired
    The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
citystring | nullrequired
The city in the lead's postal address.
clinicianobject | nullrequired
The clinician the lead is assigned to, when recorded.
- created_atstring · date-timerequired
  An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
- display_namestringrequired
  The formatted name of the clinician, including title.
- emailstring | null · emailrequired
  The practice contact email of the clinician within the organization.
- first_namestring | nullrequired
  The first name of the clinician.
- idstring · uuidrequired
  The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
- last_namestring | nullrequired
  The last name of the clinician.
- linksobjectrequired
  URLs to related resources.
  - bookingsstring · urirequired
    URL to list Bookings for this Clinician.
- medical_specialtystring | nullrequired
  The medical specialty of the clinician, when recorded.
- objectanyrequired
  Discriminator value emitted at object.
- titlestring | nullrequired
  The professional or personal title of the clinician, when recorded, such as Dr.
- updated_atstring · date-timerequired
  An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
country_codestring | nullrequired
The ISO 3166-1 alpha-2 country code for the postal address, such as GB for the United Kingdom.
countystring | nullrequired
The county or region in the lead's postal address.
created_atstring · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
creation_sourcestring | nullrequired
How the Lead was created. api means the record was created through the Developer Platform. Read-only.
date_of_birthstring | null · daterequired
The date of birth of the lead, in ISO 8601 format (YYYY-MM-DD).
display_namestring | nullrequired
The formatted display name of the lead, including their title when recorded.
emailstring | null · emailrequired
The contact email address of the lead.
first_namestringrequired
The first name of the lead.
gdpr_consent_granted_atstring | null · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
gdpr_consent_withdrawn_atstring | null · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
idstring · uuidrequired
The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
internal_notesstring | nullrequired
Internal notes shown in the Notes box next to presenting problem on the Carebit lead enquiry screen. Distinct from referral_notes.
is_converted_to_patientbooleanrequired
Whether the lead has been converted to a patient. Read-only.
is_lostbooleanrequired
Whether the lead has been marked as lost. Read-only.
is_opted_out_of_smsbooleanrequired
Whether the lead has opted out of SMS communication.
is_signed_up_to_newslettersbooleanrequired
Whether the lead has signed up to receive newsletters.
last_namestringrequired
The last name of the lead.
lead_typestringrequired
Whether the record is a patient inquiry or a referral.
Allowed values: inquiry | referral
linksobjectrequired
URLs to related resources. remote_file_import_batch is present on create responses when at least one attachment was submitted.
- clinicianstring | null · urirequired
  The full URL of a related resource.
- remote_file_import_batchstring · uri
  The full URL of a related resource.
- selfstring · urirequired
  The full URL of a related resource.
- servicestring | null · urirequired
  The full URL of a related resource.
mobilestring | nullrequired
The mobile phone number of the lead, without the country dial code.
mobile_country_dial_codestring | nullrequired
The ISO 3166-1 alpha-2 country code that selects the international dial code for mobile, for example GB selects +44.
objectanyrequired
Discriminator value emitted at object.
organization_privacy_policy_consent_granted_atstring | null · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
patient_idstring | null · uuidrequired
The identifier of the Patient this Lead was converted to. Null until conversion. Read-only.
phonestring | nullrequired
The landline phone number of the lead, without the country dial code.
phone_country_dial_codestring | nullrequired
The ISO 3166-1 alpha-2 country code that selects the international dial code for phone, for example GB selects +44.
postcodestring | nullrequired
The postal code in the lead's postal address.
presenting_problemstring | nullrequired
The presenting problem the lead described. Shown next to Notes on the Carebit lead enquiry screen.
referral_notesstring | nullrequired
The referral notes shown on the Carebit lead enquiry screen.
referral_sourcestring | nullrequired
The referral source shown on the Carebit lead enquiry screen.
Allowed values: 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
remote_file_import_batch_idstring · 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.
serviceobject | nullrequired
The Service the Lead is inquiring about, when recorded.
- created_atstring · date-timerequired
  An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
- descriptionstring | nullrequired
  The description of the service shown to staff members and patients.
- duration_minutesinteger | nullrequired
  The scheduled duration of the service, in minutes.
- idstring · uuidrequired
  The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
- is_bookable_onlinebooleanrequired
  Whether patients can book this service online in the Patient Portal.
- namestringrequired
  The display name of the service.
- objectanyrequired
  Discriminator value emitted at object.
- service_variantsarrayrequired
  The bookable variants of this service.
  - itemsobject
    - clinician_idstring | null · uuidrequired
      The identifier of the clinician assigned to this service variant, when the variant is clinician-specific.
    - currencystring | nullrequired
      The ISO 4217 currency code used for this service variant. Must be one of chf, eur, gbp, or usd.
    - descriptionstring | nullrequired
      The description of this service variant.
    - idstring · uuidrequired
      The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
    - linksobjectrequired
      URLs to related resources.
      - clinicianstring | null · urirequired
        The full URL of a related resource.
      - locationstring | null · urirequired
        The full URL of a related resource.
    - location_idstring | null · uuidrequired
      The identifier of the location assigned to this service variant, when the variant is location-specific.
    - net_priceinteger | nullrequired
      The net price of this service variant, before tax, in the currency's minor units.
    - permits_remote_bookingsbooleanrequired
      Whether this service variant can be used for remote bookings.
- tax_rateobject | nullrequired
  The tax rate applied to this service. Null when no tax rate is set.
  - descriptionstring | nullrequired
    The description of when the tax rate applies.
  - idstring · uuidrequired
    The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - percentagenumberrequired
    The tax rate as a percentage from 0 to 100.
  - titlestringrequired
    The display name of the tax rate, for example 20% VAT.
- updated_atstring · date-timerequired
  An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
sexstring | nullrequired
The sex of the Lead as supplied on the inquiry.
stageobject | nullrequired
The current pipeline stage of the lead. Read-only; use stage_id when updating the lead.
- created_atstring · date-timerequired
  An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
- idstring · uuidrequired
  The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
- is_conversion_stagebooleanrequired
  Whether moving a Lead into this stage can start the Organization's Lead conversion workflow.
- is_lost_stagebooleanrequired
  Whether moving a lead into this stage marks it as lost or rejected.
- namestringrequired
  The display name of the stage.
- objectanyrequired
  Discriminator value emitted at object.
- positioninteger | nullrequired
  The stage's display order within its pipeline.
- updated_atstring · date-timerequired
  An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
titlestring | nullrequired
The personal title of the lead, when recorded.
updated_atstring · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.

Example

{
  "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"
}

400

The Idempotency-Key header is missing (idempotency_key_required) or exceeds 255 characters (idempotency_key_too_long).

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "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"
  }
}

401

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

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "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"
  }
}

403

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

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "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"
  }
}

404

A referenced resource was not found in your Organization.

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "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"
  }
}

409

A concurrent request holds the idempotency lease (idempotency_conflict). Retry after the delay indicated by Retry-After.

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "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"
  }
}

422

The Idempotency-Key was previously used with a different request body (idempotency_key_reused), or the request body failed validation.

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "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"
  }
}

429

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

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "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"
  }
}

Request

curl -X POST "https://api.carebit.co/v1/leads" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "attachments": [
    {
      "filename": "referral-letter.pdf",
      "url": "https://files.example.com/referral-letter.pdf"
    }
  ],
  "clinician_id": "00000000-0000-4000-8000-000000000002",
  "country_code": "GB",
  "email": "riley.cooper@example.invalid",
  "first_name": "Riley",
  "internal_notes": "Asked about evening appointments with Dr Smith.",
  "last_name": "Cooper",
  "lead_type": "inquiry",
  "mobile": "7700900123",
  "mobile_country_dial_code": "GB",
  "presenting_problem": "Right knee pain",
  "referral_notes": "Referred by Dr Patel at Riverside Medical.",
  "referral_source": "gp_practice",
  "service_id": "00000000-0000-4000-8000-000000000005"
}'

201 response

{
  "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"
}

400 response

{
  "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"
  }
}

401 response

{
  "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"
  }
}

403 response

{
  "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"
  }
}

404 response

{
  "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"
  }
}

409 response

{
  "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"
  }
}

422 response

{
  "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"
  }
}

429 response

{
  "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"
  }
}

get/v1/leads/:id

Get a Lead

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

Required API scopes: leads.read

Parameters

id
path · required
string
-

Responses

200

The requested Lead.

address_line_1string | nullrequired
The primary address line of the lead.
address_line_2string | nullrequired
The secondary address line of the lead.
attachmentsarrayrequired
The files attached to the lead.
- itemsobject
  - download_urlstring | null · urirequired
    The short-lived signed download URL for the attachment. Null while the malware scan is not complete.
  - filenamestring | nullrequired
    The original filename of the attachment.
  - idstring · uuidrequired
    The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
citystring | nullrequired
The city in the lead's postal address.
clinicianobject | nullrequired
The clinician the lead is assigned to, when recorded.
- created_atstring · date-timerequired
  An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
- display_namestringrequired
  The formatted name of the clinician, including title.
- emailstring | null · emailrequired
  The practice contact email of the clinician within the organization.
- first_namestring | nullrequired
  The first name of the clinician.
- idstring · uuidrequired
  The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
- last_namestring | nullrequired
  The last name of the clinician.
- linksobjectrequired
  URLs to related resources.
  - bookingsstring · urirequired
    URL to list Bookings for this Clinician.
- medical_specialtystring | nullrequired
  The medical specialty of the clinician, when recorded.
- objectanyrequired
  Discriminator value emitted at object.
- titlestring | nullrequired
  The professional or personal title of the clinician, when recorded, such as Dr.
- updated_atstring · date-timerequired
  An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
country_codestring | nullrequired
The ISO 3166-1 alpha-2 country code for the postal address, such as GB for the United Kingdom.
countystring | nullrequired
The county or region in the lead's postal address.
created_atstring · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
creation_sourcestring | nullrequired
How the Lead was created. api means the record was created through the Developer Platform. Read-only.
date_of_birthstring | null · daterequired
The date of birth of the lead, in ISO 8601 format (YYYY-MM-DD).
display_namestring | nullrequired
The formatted display name of the lead, including their title when recorded.
emailstring | null · emailrequired
The contact email address of the lead.
first_namestringrequired
The first name of the lead.
gdpr_consent_granted_atstring | null · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
gdpr_consent_withdrawn_atstring | null · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
idstring · uuidrequired
The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
internal_notesstring | nullrequired
Internal notes shown in the Notes box next to presenting problem on the Carebit lead enquiry screen. Distinct from referral_notes.
is_converted_to_patientbooleanrequired
Whether the lead has been converted to a patient. Read-only.
is_lostbooleanrequired
Whether the lead has been marked as lost. Read-only.
is_opted_out_of_smsbooleanrequired
Whether the lead has opted out of SMS communication.
is_signed_up_to_newslettersbooleanrequired
Whether the lead has signed up to receive newsletters.
last_namestringrequired
The last name of the lead.
lead_typestringrequired
Whether the record is a patient inquiry or a referral.
Allowed values: inquiry | referral
linksobjectrequired
URLs to related resources. remote_file_import_batch is present on create responses when at least one attachment was submitted.
- clinicianstring | null · urirequired
  The full URL of a related resource.
- remote_file_import_batchstring · uri
  The full URL of a related resource.
- selfstring · urirequired
  The full URL of a related resource.
- servicestring | null · urirequired
  The full URL of a related resource.
mobilestring | nullrequired
The mobile phone number of the lead, without the country dial code.
mobile_country_dial_codestring | nullrequired
The ISO 3166-1 alpha-2 country code that selects the international dial code for mobile, for example GB selects +44.
objectanyrequired
Discriminator value emitted at object.
organization_privacy_policy_consent_granted_atstring | null · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
patient_idstring | null · uuidrequired
The identifier of the Patient this Lead was converted to. Null until conversion. Read-only.
phonestring | nullrequired
The landline phone number of the lead, without the country dial code.
phone_country_dial_codestring | nullrequired
The ISO 3166-1 alpha-2 country code that selects the international dial code for phone, for example GB selects +44.
postcodestring | nullrequired
The postal code in the lead's postal address.
presenting_problemstring | nullrequired
The presenting problem the lead described. Shown next to Notes on the Carebit lead enquiry screen.
referral_notesstring | nullrequired
The referral notes shown on the Carebit lead enquiry screen.
referral_sourcestring | nullrequired
The referral source shown on the Carebit lead enquiry screen.
Allowed values: 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
remote_file_import_batch_idstring · 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.
serviceobject | nullrequired
The Service the Lead is inquiring about, when recorded.
- created_atstring · date-timerequired
  An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
- descriptionstring | nullrequired
  The description of the service shown to staff members and patients.
- duration_minutesinteger | nullrequired
  The scheduled duration of the service, in minutes.
- idstring · uuidrequired
  The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
- is_bookable_onlinebooleanrequired
  Whether patients can book this service online in the Patient Portal.
- namestringrequired
  The display name of the service.
- objectanyrequired
  Discriminator value emitted at object.
- service_variantsarrayrequired
  The bookable variants of this service.
  - itemsobject
    - clinician_idstring | null · uuidrequired
      The identifier of the clinician assigned to this service variant, when the variant is clinician-specific.
    - currencystring | nullrequired
      The ISO 4217 currency code used for this service variant. Must be one of chf, eur, gbp, or usd.
    - descriptionstring | nullrequired
      The description of this service variant.
    - idstring · uuidrequired
      The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
    - linksobjectrequired
      URLs to related resources.
      - clinicianstring | null · urirequired
        The full URL of a related resource.
      - locationstring | null · urirequired
        The full URL of a related resource.
    - location_idstring | null · uuidrequired
      The identifier of the location assigned to this service variant, when the variant is location-specific.
    - net_priceinteger | nullrequired
      The net price of this service variant, before tax, in the currency's minor units.
    - permits_remote_bookingsbooleanrequired
      Whether this service variant can be used for remote bookings.
- tax_rateobject | nullrequired
  The tax rate applied to this service. Null when no tax rate is set.
  - descriptionstring | nullrequired
    The description of when the tax rate applies.
  - idstring · uuidrequired
    The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - percentagenumberrequired
    The tax rate as a percentage from 0 to 100.
  - titlestringrequired
    The display name of the tax rate, for example 20% VAT.
- updated_atstring · date-timerequired
  An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
sexstring | nullrequired
The sex of the Lead as supplied on the inquiry.
stageobject | nullrequired
The current pipeline stage of the lead. Read-only; use stage_id when updating the lead.
- created_atstring · date-timerequired
  An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
- idstring · uuidrequired
  The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
- is_conversion_stagebooleanrequired
  Whether moving a Lead into this stage can start the Organization's Lead conversion workflow.
- is_lost_stagebooleanrequired
  Whether moving a lead into this stage marks it as lost or rejected.
- namestringrequired
  The display name of the stage.
- objectanyrequired
  Discriminator value emitted at object.
- positioninteger | nullrequired
  The stage's display order within its pipeline.
- updated_atstring · date-timerequired
  An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
titlestring | nullrequired
The personal title of the lead, when recorded.
updated_atstring · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.

Example

{
  "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"
}

401

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

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "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"
  }
}

403

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

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "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"
  }
}

404

Error response.

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "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"
  }
}

429

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

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "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"
  }
}

Request

curl -X GET "https://api.carebit.co/v1/leads/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"

200 response

{
  "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"
}

401 response

{
  "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"
  }
}

403 response

{
  "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"
  }
}

404 response

{
  "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"
  }
}

429 response

{
  "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"
  }
}

patch/v1/leads/:id

Update a Lead

Updates any patient inquiry or referral in the Organization, regardless of how it was created. Use stage_id to move the Lead within the pipeline for its resulting lead_type. Conversion and lost stages can start the Organization's configured workflows. Attribution and lifecycle fields are read-only. Carebit Pro is required.

Required API scopes: leads.update

Parameters

id
path · required
string
-
Idempotency-Key
header · required
string
Client-generated idempotency key. Required for every POST/PATCH write. Replay of the same key with the same body returns the stored response with an Idempotency-Replayed: true header. Same key + different body returns 422 idempotency_key_reused. A duplicate that arrives while the first request is still in flight returns 409 idempotency_conflict with Retry-After: 1.

Request body

application/json

address_line_1string | null
The primary address line of the lead.
address_line_2string | null
The secondary address line of the lead.
citystring | null
The city in the lead's postal address.
clinician_idstring | null · uuid
The identifier of the clinician the lead is assigned to. Must be a clinician enabled in your Organization. Pass null to unassign.
country_codestring | null
The uppercase ISO 3166-1 alpha-2 country code for the lead's postal address.
countystring | null
The county or region in the lead's postal address.
date_of_birthstring | null · date
The date of birth of the lead, in ISO 8601 format (YYYY-MM-DD).
emailstring | null · email
The contact email address of the lead.
first_namestring
The first name of the lead. Required on create.
gdpr_consent_granted_atstring | null · date-time
The ISO 8601 UTC timestamp at which the lead granted GDPR consent.
gdpr_consent_withdrawn_atstring | null · date-time
The ISO 8601 UTC timestamp at which the lead withdrew GDPR consent.
internal_notesstring | null
Internal notes shown in the Notes box next to presenting problem on the Carebit lead enquiry screen. Distinct from referral_notes.
is_opted_out_of_smsboolean
Whether the lead has opted out of SMS communication.
is_signed_up_to_newslettersboolean
Whether the lead has signed up to receive newsletters.
last_namestring
The last name of the lead. Required on create.
lead_typestring
Whether to treat the record as a patient inquiry or a referral. Defaults to inquiry on create.
Allowed values: inquiry | referral
mobilestring | null
The mobile phone number of the lead, without the country dial code.
mobile_country_dial_codestring | null
The ISO 3166-1 alpha-2 country code that selects the international dial code for mobile, for example GB selects +44.
organization_privacy_policy_consent_granted_atstring | null · date-time
The ISO 8601 UTC timestamp at which the lead granted consent to the Organization's privacy policy.
phonestring | null
The landline phone number of the lead, without the country dial code.
phone_country_dial_codestring | null
The ISO 3166-1 alpha-2 country code that selects the international dial code for phone, for example GB selects +44.
postcodestring | null
The postal code in the lead's postal address.
presenting_problemstring | null
The presenting problem the lead described. Shown next to Notes on the Carebit lead enquiry screen.
referral_notesstring | null
The referral notes shown on the Carebit lead enquiry screen.
referral_sourcestring | null
The referral source shown on the Carebit lead enquiry screen.
Allowed values: 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
service_idstring | null · uuid
The Service the Lead is inquiring about. It must belong to your Organization. Pass null to clear.
sexstring | null
The sex of the Lead as supplied on the inquiry.
stage_idstring · uuid
The identifier of a stage in the pipeline that matches the Lead's resulting lead_type.
titlestring | null
The personal title of the lead, when recorded.

Responses

200

The requested Lead.

address_line_1string | nullrequired
The primary address line of the lead.
address_line_2string | nullrequired
The secondary address line of the lead.
attachmentsarrayrequired
The files attached to the lead.
- itemsobject
  - download_urlstring | null · urirequired
    The short-lived signed download URL for the attachment. Null while the malware scan is not complete.
  - filenamestring | nullrequired
    The original filename of the attachment.
  - idstring · uuidrequired
    The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
citystring | nullrequired
The city in the lead's postal address.
clinicianobject | nullrequired
The clinician the lead is assigned to, when recorded.
- created_atstring · date-timerequired
  An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
- display_namestringrequired
  The formatted name of the clinician, including title.
- emailstring | null · emailrequired
  The practice contact email of the clinician within the organization.
- first_namestring | nullrequired
  The first name of the clinician.
- idstring · uuidrequired
  The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
- last_namestring | nullrequired
  The last name of the clinician.
- linksobjectrequired
  URLs to related resources.
  - bookingsstring · urirequired
    URL to list Bookings for this Clinician.
- medical_specialtystring | nullrequired
  The medical specialty of the clinician, when recorded.
- objectanyrequired
  Discriminator value emitted at object.
- titlestring | nullrequired
  The professional or personal title of the clinician, when recorded, such as Dr.
- updated_atstring · date-timerequired
  An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
country_codestring | nullrequired
The ISO 3166-1 alpha-2 country code for the postal address, such as GB for the United Kingdom.
countystring | nullrequired
The county or region in the lead's postal address.
created_atstring · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
creation_sourcestring | nullrequired
How the Lead was created. api means the record was created through the Developer Platform. Read-only.
date_of_birthstring | null · daterequired
The date of birth of the lead, in ISO 8601 format (YYYY-MM-DD).
display_namestring | nullrequired
The formatted display name of the lead, including their title when recorded.
emailstring | null · emailrequired
The contact email address of the lead.
first_namestringrequired
The first name of the lead.
gdpr_consent_granted_atstring | null · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
gdpr_consent_withdrawn_atstring | null · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
idstring · uuidrequired
The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
internal_notesstring | nullrequired
Internal notes shown in the Notes box next to presenting problem on the Carebit lead enquiry screen. Distinct from referral_notes.
is_converted_to_patientbooleanrequired
Whether the lead has been converted to a patient. Read-only.
is_lostbooleanrequired
Whether the lead has been marked as lost. Read-only.
is_opted_out_of_smsbooleanrequired
Whether the lead has opted out of SMS communication.
is_signed_up_to_newslettersbooleanrequired
Whether the lead has signed up to receive newsletters.
last_namestringrequired
The last name of the lead.
lead_typestringrequired
Whether the record is a patient inquiry or a referral.
Allowed values: inquiry | referral
linksobjectrequired
URLs to related resources. remote_file_import_batch is present on create responses when at least one attachment was submitted.
- clinicianstring | null · urirequired
  The full URL of a related resource.
- remote_file_import_batchstring · uri
  The full URL of a related resource.
- selfstring · urirequired
  The full URL of a related resource.
- servicestring | null · urirequired
  The full URL of a related resource.
mobilestring | nullrequired
The mobile phone number of the lead, without the country dial code.
mobile_country_dial_codestring | nullrequired
The ISO 3166-1 alpha-2 country code that selects the international dial code for mobile, for example GB selects +44.
objectanyrequired
Discriminator value emitted at object.
organization_privacy_policy_consent_granted_atstring | null · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
patient_idstring | null · uuidrequired
The identifier of the Patient this Lead was converted to. Null until conversion. Read-only.
phonestring | nullrequired
The landline phone number of the lead, without the country dial code.
phone_country_dial_codestring | nullrequired
The ISO 3166-1 alpha-2 country code that selects the international dial code for phone, for example GB selects +44.
postcodestring | nullrequired
The postal code in the lead's postal address.
presenting_problemstring | nullrequired
The presenting problem the lead described. Shown next to Notes on the Carebit lead enquiry screen.
referral_notesstring | nullrequired
The referral notes shown on the Carebit lead enquiry screen.
referral_sourcestring | nullrequired
The referral source shown on the Carebit lead enquiry screen.
Allowed values: 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
remote_file_import_batch_idstring · 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.
serviceobject | nullrequired
The Service the Lead is inquiring about, when recorded.
- created_atstring · date-timerequired
  An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
- descriptionstring | nullrequired
  The description of the service shown to staff members and patients.
- duration_minutesinteger | nullrequired
  The scheduled duration of the service, in minutes.
- idstring · uuidrequired
  The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
- is_bookable_onlinebooleanrequired
  Whether patients can book this service online in the Patient Portal.
- namestringrequired
  The display name of the service.
- objectanyrequired
  Discriminator value emitted at object.
- service_variantsarrayrequired
  The bookable variants of this service.
  - itemsobject
    - clinician_idstring | null · uuidrequired
      The identifier of the clinician assigned to this service variant, when the variant is clinician-specific.
    - currencystring | nullrequired
      The ISO 4217 currency code used for this service variant. Must be one of chf, eur, gbp, or usd.
    - descriptionstring | nullrequired
      The description of this service variant.
    - idstring · uuidrequired
      The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
    - linksobjectrequired
      URLs to related resources.
      - clinicianstring | null · urirequired
        The full URL of a related resource.
      - locationstring | null · urirequired
        The full URL of a related resource.
    - location_idstring | null · uuidrequired
      The identifier of the location assigned to this service variant, when the variant is location-specific.
    - net_priceinteger | nullrequired
      The net price of this service variant, before tax, in the currency's minor units.
    - permits_remote_bookingsbooleanrequired
      Whether this service variant can be used for remote bookings.
- tax_rateobject | nullrequired
  The tax rate applied to this service. Null when no tax rate is set.
  - descriptionstring | nullrequired
    The description of when the tax rate applies.
  - idstring · uuidrequired
    The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - percentagenumberrequired
    The tax rate as a percentage from 0 to 100.
  - titlestringrequired
    The display name of the tax rate, for example 20% VAT.
- updated_atstring · date-timerequired
  An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
sexstring | nullrequired
The sex of the Lead as supplied on the inquiry.
stageobject | nullrequired
The current pipeline stage of the lead. Read-only; use stage_id when updating the lead.
- created_atstring · date-timerequired
  An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
- idstring · uuidrequired
  The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
- is_conversion_stagebooleanrequired
  Whether moving a Lead into this stage can start the Organization's Lead conversion workflow.
- is_lost_stagebooleanrequired
  Whether moving a lead into this stage marks it as lost or rejected.
- namestringrequired
  The display name of the stage.
- objectanyrequired
  Discriminator value emitted at object.
- positioninteger | nullrequired
  The stage's display order within its pipeline.
- updated_atstring · date-timerequired
  An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
titlestring | nullrequired
The personal title of the lead, when recorded.
updated_atstring · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.

Example

{
  "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"
}

400

The Idempotency-Key header is missing (idempotency_key_required) or exceeds 255 characters (idempotency_key_too_long).

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "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"
  }
}

401

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

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "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"
  }
}

403

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

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "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"
  }
}

404

Error response.

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "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"
  }
}

409

A concurrent request holds the idempotency lease (idempotency_conflict). Retry after the delay indicated by Retry-After.

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "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"
  }
}

422

The Idempotency-Key was previously used with a different request body (idempotency_key_reused), or the request body failed validation.

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "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"
  }
}

429

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

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "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"
  }
}

Request

curl -X PATCH "https://api.carebit.co/v1/leads/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "presenting_problem": "Left knee pain (updated)",
  "stage_id": "00000000-0000-4000-8000-00000000000d"
}'

200 response

{
  "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"
}

400 response

{
  "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"
  }
}

401 response

{
  "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"
  }
}

403 response

{
  "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"
  }
}

404 response

{
  "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"
  }
}

409 response

{
  "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"
  }
}

422 response

{
  "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"
  }
}

429 response

{
  "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"
  }
}

Prefer plain text? Append ?format=md or send Accept: text/markdown to receive this page as raw Markdown.