Carebit API

Leads

Patient enquiries and referrals received by the Organization.

Required API scopes: leads.createleads.readleads.update

Endpoints

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

get/v1/lead_form_responsesList a Lead's form responsesleads.read
get/v1/lead_form_responses/:idGet a Lead's form responseleads.read
get/v1/lead_pipelinesList Lead pipelines and stagesleads.read
get/v1/leadsList Leadsleads.read
post/v1/leadsCreate a Leadleads.create
get/v1/leads/:idGet a Leadleads.read
patch/v1/leads/:idUpdate a Leadleads.update

get/v1/lead_form_responses

List a Lead's form responses

Returns the forms a Lead submitted, newest first. lead_id is required. The same submissions are summarized in the form_responses array of the Lead itself. Enquiries a staff member recorded by hand are not returned, because they have no form. Lost Leads are included. Carebit Pro is required.

Required API scopes: leads.read

Parameters

lead_id
query · required
string
The Lead whose form submissions should be returned.
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 LeadFormResponse objects.

dataarrayrequired
- itemsobject
  - answersarrayrequired
    The questions and answers, in the order the respondent saw them. Layout blocks, hidden fields and the form's bot trap are omitted. A file upload question is omitted too; the uploaded files appear in the Lead's attachments.
    - itemsobject
      One question and its submitted answer, embedded in a FormResponse.
      - field_namestring | nullrequired
        The machine name of the question, for example presenting_problem. Match on this rather than on label, which an Organization can reword at any time.
      - field_typestring | nullrequired
        The kind of question asked, for example text_area or date_field. Use it to parse value.
      - labelstringrequired
        The question as it was shown to the respondent, with HTML sanitized. A question saved with no label returns an empty string.
      - valuestring | nullrequired
        The submitted answer, always a string. A date_field returns an ISO 8601 date such as 1990-06-15. A consent_field returns a UTC ISO 8601 timestamp. A number_field returns a decimal such as 12.5. A checkbox returns true or false. A dropdown or radio returns the selected option's value, such as both_knees, not its display label. A multiselect returns null and uses values instead.
      - valuesarrayrequired
        The selected option values for a multiselect question, such as ["both_knees"]. Empty for every other question type. Like value, these are option values rather than display labels, because a label is free text the Organization can reword at any time.
        itemsstring
  - created_atstring · date-timerequired
    An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
  - form_namestringrequired
    The name of the form the respondent submitted.
  - form_typestringrequired
    Whether the submission came from an enquiry form or a referral form. This describes the form, not the Lead. A Lead whose lead_type is referral can still hold an inquiry_form submission.
    Allowed values: inquiry_form | referral_form
  - idstring · uuidrequired
    The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - lead_idstring · uuidrequired
    The Lead the submission created or updated.
  - linksobjectrequired
    URLs to related resources.
    - leadstring · urirequired
      The full URL of a related resource.
    - selfstring · urirequired
      The full URL of a related resource.
  - objectanyrequired
    Discriminator value emitted at object.
  - referral_notesstring | nullrequired
    The referral notes captured with this submission. The Lead's own referral_notes is taken from its first submission that supplied one, so this can differ.
  - referral_sourcestring | nullrequired
    How this submission reached the Organization. A form submitted on the Organization's website records website.
    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
  - referred_by_clinician_idstring | null · uuidrequired
    The Clinician who referred this submission, when one was identified.
  - referred_by_organization_idstring | null · uuidrequired
    The Organization that referred this submission, when one was identified.
  - submitted_atstring · date-timerequired
    An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
  - trackingobjectrequired
    The marketing attribution captured with this submission.
    - ad_idstring | nullrequired
      The ad_id advertising identifier.
    - fbclidstring | nullrequired
      The Facebook click identifier.
    - gad_campaign_idstring | nullrequired
      The Google Ads campaign identifier, from gad_campaignid.
    - gad_sourcestring | nullrequired
      The Google Ads source.
    - gbraidstring | nullrequired
      The Google gbraid click identifier.
    - gclidstring | nullrequired
      The Google click identifier.
    - landing_page_originstring | null · urirequired
      The scheme and host of the page the form was submitted from, for example https://www.example.com. Null when no landing page URL was recorded.
    - utm_campaignstring | nullrequired
      The utm_campaign parameter.
    - utm_contentstring | nullrequired
      The utm_content parameter.
    - utm_mediumstring | nullrequired
      The utm_medium parameter.
    - utm_sourcestring | nullrequired
      The utm_source parameter.
    - utm_termstring | nullrequired
      The utm_term parameter.
  - 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": "b5f5c363-d0b7-4e92-86ef-1d87afe8e8f8",
      "object": "lead_form_response",
      "answers":  … ]
         … }
          "field_name": "presenting_problem",
          "field_type": "text_area",
          "label": "What can we help with?",
          "value": "Persistent knee pain",
          "values": []
        }
      ],
      "created_at": "2026-01-01T09:00:00Z",
      "form_name": "New patient inquiry",
      "form_type": "inquiry_form",
      "lead_id": "00000000-0000-4000-8000-00000000000c",
      "links":  … }
        "lead": "https://api.carebit.co/v1/leads/00000000-0000-4000-8000-00000000000c",
        "self": "https://api.carebit.co/v1/lead_form_responses/b5f5c363-d0b7-4e92-86ef-1d87afe8e8f8"
      },
      "referral_notes": null,
      "referral_source": "consultant",
      "referred_by_clinician_id": "b5ac896f-f746-4df1-899a-c12d33b84b2d",
      "referred_by_organization_id": "8cda84a9-bf46-4f81-8f3c-66dd352e95db",
      "submitted_at": "2026-01-01T09:00:00Z",
      "tracking":  … }
        "ad_id": null,
        "fbclid": null,
        "gad_campaign_id": null,
        "gad_source": null,
        "gbraid": null,
        "gclid": null,
        "landing_page_origin": null,
        "utm_campaign": null,
        "utm_content": null,
        "utm_medium": null,
        "utm_source": null,
        "utm_term": null
      },
      "updated_at": "2026-01-01T09:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": "eyJzdGFydF90aW1lIjoiMjAyNi0wMS0wMVQwOTowMDowMFoifQ",
  "url": "/v1/lead_form_responses"
}

400

The lead_id parameter is missing, or a 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"
  }
}

404

The Lead does not exist in this 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"
  }
}

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_form_responses?lead_id=00000000-0000-4000-8000-00000000000c" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"

200 response

{
  "object": "list",
  "data":  … ]
     … }
      "id": "b5f5c363-d0b7-4e92-86ef-1d87afe8e8f8",
      "object": "lead_form_response",
      "answers":  … ]
         … }
          "field_name": "presenting_problem",
          "field_type": "text_area",
          "label": "What can we help with?",
          "value": "Persistent knee pain",
          "values": []
        }
      ],
      "created_at": "2026-01-01T09:00:00Z",
      "form_name": "New patient inquiry",
      "form_type": "inquiry_form",
      "lead_id": "00000000-0000-4000-8000-00000000000c",
      "links":  … }
        "lead": "https://api.carebit.co/v1/leads/00000000-0000-4000-8000-00000000000c",
        "self": "https://api.carebit.co/v1/lead_form_responses/b5f5c363-d0b7-4e92-86ef-1d87afe8e8f8"
      },
      "referral_notes": null,
      "referral_source": "consultant",
      "referred_by_clinician_id": "b5ac896f-f746-4df1-899a-c12d33b84b2d",
      "referred_by_organization_id": "8cda84a9-bf46-4f81-8f3c-66dd352e95db",
      "submitted_at": "2026-01-01T09:00:00Z",
      "tracking":  … }
        "ad_id": null,
        "fbclid": null,
        "gad_campaign_id": null,
        "gad_source": null,
        "gbraid": null,
        "gclid": null,
        "landing_page_origin": null,
        "utm_campaign": null,
        "utm_content": null,
        "utm_medium": null,
        "utm_source": null,
        "utm_term": null
      },
      "updated_at": "2026-01-01T09:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": "eyJzdGFydF90aW1lIjoiMjAyNi0wMS0wMVQwOTowMDowMFoifQ",
  "url": "/v1/lead_form_responses"
}

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

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/lead_form_responses/:id

Get a Lead's form response

Returns one form submission with its questions and answers, the referral data captured with it, and its marketing attribution. Carebit Pro is required.

Required API scopes: leads.read

Parameters

id
path · required
string
-

Responses

200

The requested LeadFormResponse.

answersarrayrequired
The questions and answers, in the order the respondent saw them. Layout blocks, hidden fields and the form's bot trap are omitted. A file upload question is omitted too; the uploaded files appear in the Lead's attachments.
- itemsobject
  One question and its submitted answer, embedded in a FormResponse.
  - field_namestring | nullrequired
    The machine name of the question, for example presenting_problem. Match on this rather than on label, which an Organization can reword at any time.
  - field_typestring | nullrequired
    The kind of question asked, for example text_area or date_field. Use it to parse value.
  - labelstringrequired
    The question as it was shown to the respondent, with HTML sanitized. A question saved with no label returns an empty string.
  - valuestring | nullrequired
    The submitted answer, always a string. A date_field returns an ISO 8601 date such as 1990-06-15. A consent_field returns a UTC ISO 8601 timestamp. A number_field returns a decimal such as 12.5. A checkbox returns true or false. A dropdown or radio returns the selected option's value, such as both_knees, not its display label. A multiselect returns null and uses values instead.
  - valuesarrayrequired
    The selected option values for a multiselect question, such as ["both_knees"]. Empty for every other question type. Like value, these are option values rather than display labels, because a label is free text the Organization can reword at any time.
    - itemsstring
created_atstring · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
form_namestringrequired
The name of the form the respondent submitted.
form_typestringrequired
Whether the submission came from an enquiry form or a referral form. This describes the form, not the Lead. A Lead whose lead_type is referral can still hold an inquiry_form submission.
Allowed values: inquiry_form | referral_form
idstring · uuidrequired
The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
lead_idstring · uuidrequired
The Lead the submission created or updated.
linksobjectrequired
URLs to related resources.
- leadstring · urirequired
  The full URL of a related resource.
- selfstring · urirequired
  The full URL of a related resource.
objectanyrequired
Discriminator value emitted at object.
referral_notesstring | nullrequired
The referral notes captured with this submission. The Lead's own referral_notes is taken from its first submission that supplied one, so this can differ.
referral_sourcestring | nullrequired
How this submission reached the Organization. A form submitted on the Organization's website records website.
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
referred_by_clinician_idstring | null · uuidrequired
The Clinician who referred this submission, when one was identified.
referred_by_organization_idstring | null · uuidrequired
The Organization that referred this submission, when one was identified.
submitted_atstring · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
trackingobjectrequired
The marketing attribution captured with this submission.
- ad_idstring | nullrequired
  The ad_id advertising identifier.
- fbclidstring | nullrequired
  The Facebook click identifier.
- gad_campaign_idstring | nullrequired
  The Google Ads campaign identifier, from gad_campaignid.
- gad_sourcestring | nullrequired
  The Google Ads source.
- gbraidstring | nullrequired
  The Google gbraid click identifier.
- gclidstring | nullrequired
  The Google click identifier.
- landing_page_originstring | null · urirequired
  The scheme and host of the page the form was submitted from, for example https://www.example.com. Null when no landing page URL was recorded.
- utm_campaignstring | nullrequired
  The utm_campaign parameter.
- utm_contentstring | nullrequired
  The utm_content parameter.
- utm_mediumstring | nullrequired
  The utm_medium parameter.
- utm_sourcestring | nullrequired
  The utm_source parameter.
- utm_termstring | nullrequired
  The utm_term parameter.
updated_atstring · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.

Example

{
  "id": "b5f5c363-d0b7-4e92-86ef-1d87afe8e8f8",
  "object": "lead_form_response",
  "answers":  … ]
     … }
      "field_name": "presenting_problem",
      "field_type": "text_area",
      "label": "What can we help with?",
      "value": "Persistent knee pain",
      "values": []
    }
  ],
  "created_at": "2026-01-01T09:00:00Z",
  "form_name": "New patient inquiry",
  "form_type": "inquiry_form",
  "lead_id": "00000000-0000-4000-8000-00000000000c",
  "links":  … }
    "lead": "https://api.carebit.co/v1/leads/00000000-0000-4000-8000-00000000000c",
    "self": "https://api.carebit.co/v1/lead_form_responses/b5f5c363-d0b7-4e92-86ef-1d87afe8e8f8"
  },
  "referral_notes": null,
  "referral_source": "consultant",
  "referred_by_clinician_id": "b5ac896f-f746-4df1-899a-c12d33b84b2d",
  "referred_by_organization_id": "8cda84a9-bf46-4f81-8f3c-66dd352e95db",
  "submitted_at": "2026-01-01T09:00:00Z",
  "tracking":  … }
    "ad_id": null,
    "fbclid": null,
    "gad_campaign_id": null,
    "gad_source": null,
    "gbraid": null,
    "gclid": null,
    "landing_page_origin": null,
    "utm_campaign": null,
    "utm_content": null,
    "utm_medium": null,
    "utm_source": null,
    "utm_term": null
  },
  "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/lead_form_responses/b5f5c363-d0b7-4e92-86ef-1d87afe8e8f8" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"

200 response

{
  "id": "b5f5c363-d0b7-4e92-86ef-1d87afe8e8f8",
  "object": "lead_form_response",
  "answers":  … ]
     … }
      "field_name": "presenting_problem",
      "field_type": "text_area",
      "label": "What can we help with?",
      "value": "Persistent knee pain",
      "values": []
    }
  ],
  "created_at": "2026-01-01T09:00:00Z",
  "form_name": "New patient inquiry",
  "form_type": "inquiry_form",
  "lead_id": "00000000-0000-4000-8000-00000000000c",
  "links":  … }
    "lead": "https://api.carebit.co/v1/leads/00000000-0000-4000-8000-00000000000c",
    "self": "https://api.carebit.co/v1/lead_form_responses/b5f5c363-d0b7-4e92-86ef-1d87afe8e8f8"
  },
  "referral_notes": null,
  "referral_source": "consultant",
  "referred_by_clinician_id": "b5ac896f-f746-4df1-899a-c12d33b84b2d",
  "referred_by_organization_id": "8cda84a9-bf46-4f81-8f3c-66dd352e95db",
  "submitted_at": "2026-01-01T09:00:00Z",
  "tracking":  … }
    "ad_id": null,
    "fbclid": null,
    "gad_campaign_id": null,
    "gad_source": null,
    "gbraid": null,
    "gclid": null,
    "landing_page_origin": null,
    "utm_campaign": null,
    "utm_content": null,
    "utm_medium": null,
    "utm_source": null,
    "utm_term": null
  },
  "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"
  }
}

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 enquiries 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": "00000000-0000-4000-8000-00000000000d",
          "object": "lead_stage",
          "created_at": "2026-01-01T09:00:00Z",
          "is_conversion_stage": true,
          "is_lost_stage": true,
          "name": "Initial consultation",
          "position": 1,
          "updated_at": "2026-01-01T09:00:00Z"
        }
      ],
      "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": "00000000-0000-4000-8000-00000000000d",
          "object": "lead_stage",
          "created_at": "2026-01-01T09:00:00Z",
          "is_conversion_stage": true,
          "is_lost_stage": true,
          "name": "Initial consultation",
          "position": 1,
          "updated_at": "2026-01-01T09:00:00Z"
        }
      ],
      "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 enquiries and referrals. Results include leads in a lost stage, including a lead discarded when it was marked lost. A discarded lead that is not in a lost stage is omitted. Use is_lost to return only one group, and stage_id to return leads in one stage. Carebit Pro is required.

Required API scopes: leads.read

Parameters

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

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 API. 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.
  - form_responsesarrayrequired
    The forms this lead submitted, oldest first. Follow each url for the answers. Enquiries a staff member recorded by hand are not listed, because they have no form.
    - itemsobject
      - form_namestringrequired
        The name of the form the respondent submitted.
      - form_typestringrequired
        Whether the submission came from an enquiry form or a referral form.
        Allowed values: inquiry_form | referral_form
      - idstring · uuidrequired
        The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
      - submitted_atstring · date-timerequired
        An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
      - urlstring · urirequired
        The full URL of a related resource.
  - 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's current pipeline stage is a lost stage. A lost stage has the mark_lead_lost action, or the title Lost or Rejected. 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 enquiry 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
  - referred_by_clinician_idstring | null · uuidrequired
    The Clinician who referred this Lead, when one was identified. Taken from the Lead's first submission that identified one; a per-submission value is on the LeadFormResponse.
  - referred_by_organization_idstring | null · uuidrequired
    The Organization that referred this Lead, when one was identified. Taken from the Lead's first submission that identified one; a per-submission value is on the LeadFormResponse.
  - 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 enquiring 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 enquiry.
  - 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": "00000000-0000-4000-8000-00000000000c",
      "object": "lead",
      "address_line_1": "10 Harley Street",
      "address_line_2": "Marylebone",
      "attachments":  … ]
         … }
          "id": "f631636b-32e2-41be-8e4f-0a34ee0d5d59",
          "download_url": "https://files.example.invalid/document.pdf?signature=test",
          "filename": "referral-letter.pdf"
        }
      ],
      "city": "London",
      "clinician":  … }
        "id": "00000000-0000-4000-8000-000000000002",
        "object": "clinician",
        "created_at": "2026-01-01T09:00:00Z",
        "display_name": "Dr Alex Morgan",
        "email": "alex.morgan@example.com",
        "first_name": "Alex",
        "last_name": "Morgan",
        "links":  … }
          "bookings": "https://api.carebit.co/v1/bookings?clinician_id=00000000-0000-4000-8000-000000000002"
        },
        "medical_specialty": "Cardiology",
        "title": "Dr",
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "country_code": "GB",
      "county": "Greater London",
      "created_at": "2026-01-01T09:00:00Z",
      "creation_source": "api",
      "date_of_birth": "1990-01-01",
      "display_name": "Dr Alex Morgan",
      "email": "alex.morgan@example.com",
      "first_name": "Alex",
      "form_responses":  … ]
         … }
          "id": "adf881b8-4eed-42c0-8903-515f6cc8a134",
          "form_name": "New patient inquiry",
          "form_type": "inquiry_form",
          "submitted_at": "2026-01-01T09:00:00Z",
          "url": "https://files.example.invalid/document.pdf?signature=test"
        }
      ],
      "gdpr_consent_granted_at": "2026-01-01T09:00:00Z",
      "gdpr_consent_withdrawn_at": "2026-01-01T09:00:00Z",
      "internal_notes": "Asked about evening appointments with Dr Smith.",
      "is_converted_to_patient": true,
      "is_lost": false,
      "is_opted_out_of_sms": false,
      "is_signed_up_to_newsletters": true,
      "last_name": "Morgan",
      "lead_type": "inquiry",
      "links":  … }
        "clinician": "https://api.carebit.co/v1/clinicians/00000000-0000-4000-8000-000000000002",
        "remote_file_import_batch": "https://api.carebit.co/v1/remote_file_import_batches/00000000-0000-4000-8000-00000000000a",
        "self": "https://api.carebit.co/v1/leads/00000000-0000-4000-8000-00000000000c",
        "service": "https://api.carebit.co/v1/services/00000000-0000-4000-8000-000000000005"
      },
      "mobile": "7700900123",
      "mobile_country_dial_code": "GB",
      "organization_privacy_policy_consent_granted_at": "2026-01-01T09:00:00Z",
      "patient_id": "00000000-0000-4000-8000-000000000004",
      "phone": "2071234567",
      "phone_country_dial_code": "GB",
      "postcode": "W1G 9PF",
      "presenting_problem": "Persistent right knee pain",
      "referral_notes": "Referred by Dr Patel at Riverside Medical.",
      "referral_source": "consultant",
      "referred_by_clinician_id": "b5ac896f-f746-4df1-899a-c12d33b84b2d",
      "referred_by_organization_id": "8cda84a9-bf46-4f81-8f3c-66dd352e95db",
      "remote_file_import_batch_id": "00000000-0000-4000-8000-00000000000a",
      "service":  … }
        "id": "00000000-0000-4000-8000-000000000005",
        "object": "service",
        "created_at": "2026-01-01T09:00:00Z",
        "description": "An initial consultation at the Harley Street Clinic.",
        "duration_minutes": 30,
        "is_bookable_online": true,
        "name": "Initial consultation",
        "service_variants":  … ]
           … }
            "id": "00000000-0000-4000-8000-000000000006",
            "clinician_id": "00000000-0000-4000-8000-000000000002",
            "currency": "GBP",
            "description": "An initial consultation at the Harley Street Clinic.",
            "links":  … }
              "clinician": "https://api.carebit.co/v1/clinicians/00000000-0000-4000-8000-000000000002",
              "location": "https://api.carebit.co/v1/locations/00000000-0000-4000-8000-000000000003"
            },
            "location_id": "00000000-0000-4000-8000-000000000003",
            "net_price": 1,
            "permits_remote_bookings": true
          }
        ],
        "tax_rate":  … }
          "id": "00000000-0000-4000-8000-000000000029",
          "description": "An initial consultation at the Harley Street Clinic.",
          "percentage": 20,
          "title": "VAT"
        },
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "sex": "female",
      "stage":  … }
        "id": "00000000-0000-4000-8000-00000000000d",
        "object": "lead_stage",
        "created_at": "2026-01-01T09:00:00Z",
        "is_conversion_stage": true,
        "is_lost_stage": true,
        "name": "Initial consultation",
        "position": 1,
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "title": "Dr",
      "updated_at": "2026-01-01T09:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": "eyJzdGFydF90aW1lIjoiMjAyNi0wMS0wMVQwOTowMDowMFoifQ",
  "url": "/v1/leads"
}

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

404

The stage_id was not found on a lead pipeline in the 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"
  }
}

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

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

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 enquiry 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 enquiry 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 enquiring about. It must belong to your Organization. Pass null to clear.
sexstring | null
The sex of the Lead as supplied on the enquiry.
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 API. 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.
form_responsesarrayrequired
The forms this lead submitted, oldest first. Follow each url for the answers. Enquiries a staff member recorded by hand are not listed, because they have no form.
- itemsobject
  - form_namestringrequired
    The name of the form the respondent submitted.
  - form_typestringrequired
    Whether the submission came from an enquiry form or a referral form.
    Allowed values: inquiry_form | referral_form
  - idstring · uuidrequired
    The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - submitted_atstring · date-timerequired
    An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
  - urlstring · urirequired
    The full URL of a related resource.
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's current pipeline stage is a lost stage. A lost stage has the mark_lead_lost action, or the title Lost or Rejected. 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 enquiry 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
referred_by_clinician_idstring | null · uuidrequired
The Clinician who referred this Lead, when one was identified. Taken from the Lead's first submission that identified one; a per-submission value is on the LeadFormResponse.
referred_by_organization_idstring | null · uuidrequired
The Organization that referred this Lead, when one was identified. Taken from the Lead's first submission that identified one; a per-submission value is on the LeadFormResponse.
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 enquiring 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 enquiry.
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": "00000000-0000-4000-8000-00000000000c",
  "object": "lead",
  "address_line_1": "10 Harley Street",
  "address_line_2": "Marylebone",
  "attachments":  … ]
     … }
      "id": "f631636b-32e2-41be-8e4f-0a34ee0d5d59",
      "download_url": "https://files.example.invalid/document.pdf?signature=test",
      "filename": "referral-letter.pdf"
    }
  ],
  "city": "London",
  "clinician":  … }
    "id": "00000000-0000-4000-8000-000000000002",
    "object": "clinician",
    "created_at": "2026-01-01T09:00:00Z",
    "display_name": "Dr Alex Morgan",
    "email": "alex.morgan@example.com",
    "first_name": "Alex",
    "last_name": "Morgan",
    "links":  … }
      "bookings": "https://api.carebit.co/v1/bookings?clinician_id=00000000-0000-4000-8000-000000000002"
    },
    "medical_specialty": "Cardiology",
    "title": "Dr",
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "country_code": "GB",
  "county": "Greater London",
  "created_at": "2026-01-01T09:00:00Z",
  "creation_source": "api",
  "date_of_birth": "1990-01-01",
  "display_name": "Dr Alex Morgan",
  "email": "alex.morgan@example.com",
  "first_name": "Alex",
  "form_responses":  … ]
     … }
      "id": "adf881b8-4eed-42c0-8903-515f6cc8a134",
      "form_name": "New patient inquiry",
      "form_type": "inquiry_form",
      "submitted_at": "2026-01-01T09:00:00Z",
      "url": "https://files.example.invalid/document.pdf?signature=test"
    }
  ],
  "gdpr_consent_granted_at": "2026-01-01T09:00:00Z",
  "gdpr_consent_withdrawn_at": "2026-01-01T09:00:00Z",
  "internal_notes": "Asked about evening appointments with Dr Smith.",
  "is_converted_to_patient": true,
  "is_lost": false,
  "is_opted_out_of_sms": false,
  "is_signed_up_to_newsletters": true,
  "last_name": "Morgan",
  "lead_type": "inquiry",
  "links":  … }
    "clinician": "https://api.carebit.co/v1/clinicians/00000000-0000-4000-8000-000000000002",
    "remote_file_import_batch": "https://api.carebit.co/v1/remote_file_import_batches/00000000-0000-4000-8000-00000000000a",
    "self": "https://api.carebit.co/v1/leads/00000000-0000-4000-8000-00000000000c",
    "service": "https://api.carebit.co/v1/services/00000000-0000-4000-8000-000000000005"
  },
  "mobile": "7700900123",
  "mobile_country_dial_code": "GB",
  "organization_privacy_policy_consent_granted_at": "2026-01-01T09:00:00Z",
  "patient_id": "00000000-0000-4000-8000-000000000004",
  "phone": "2071234567",
  "phone_country_dial_code": "GB",
  "postcode": "W1G 9PF",
  "presenting_problem": "Persistent right knee pain",
  "referral_notes": "Referred by Dr Patel at Riverside Medical.",
  "referral_source": "consultant",
  "referred_by_clinician_id": "b5ac896f-f746-4df1-899a-c12d33b84b2d",
  "referred_by_organization_id": "8cda84a9-bf46-4f81-8f3c-66dd352e95db",
  "remote_file_import_batch_id": "00000000-0000-4000-8000-00000000000a",
  "service":  … }
    "id": "00000000-0000-4000-8000-000000000005",
    "object": "service",
    "created_at": "2026-01-01T09:00:00Z",
    "description": "An initial consultation at the Harley Street Clinic.",
    "duration_minutes": 30,
    "is_bookable_online": true,
    "name": "Initial consultation",
    "service_variants":  … ]
       … }
        "id": "00000000-0000-4000-8000-000000000006",
        "clinician_id": "00000000-0000-4000-8000-000000000002",
        "currency": "GBP",
        "description": "An initial consultation at the Harley Street Clinic.",
        "links":  … }
          "clinician": "https://api.carebit.co/v1/clinicians/00000000-0000-4000-8000-000000000002",
          "location": "https://api.carebit.co/v1/locations/00000000-0000-4000-8000-000000000003"
        },
        "location_id": "00000000-0000-4000-8000-000000000003",
        "net_price": 1,
        "permits_remote_bookings": true
      }
    ],
    "tax_rate":  … }
      "id": "00000000-0000-4000-8000-000000000029",
      "description": "An initial consultation at the Harley Street Clinic.",
      "percentage": 20,
      "title": "VAT"
    },
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "sex": "female",
  "stage":  … }
    "id": "00000000-0000-4000-8000-00000000000d",
    "object": "lead_stage",
    "created_at": "2026-01-01T09:00:00Z",
    "is_conversion_stage": true,
    "is_lost_stage": true,
    "name": "Initial consultation",
    "position": 1,
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "title": "Dr",
  "updated_at": "2026-01-01T09:00:00Z"
}

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

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 enquiry or referral from the Organization. A discarded lead that is not in a lost stage is not found. 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 API. 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.
form_responsesarrayrequired
The forms this lead submitted, oldest first. Follow each url for the answers. Enquiries a staff member recorded by hand are not listed, because they have no form.
- itemsobject
  - form_namestringrequired
    The name of the form the respondent submitted.
  - form_typestringrequired
    Whether the submission came from an enquiry form or a referral form.
    Allowed values: inquiry_form | referral_form
  - idstring · uuidrequired
    The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - submitted_atstring · date-timerequired
    An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
  - urlstring · urirequired
    The full URL of a related resource.
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's current pipeline stage is a lost stage. A lost stage has the mark_lead_lost action, or the title Lost or Rejected. 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 enquiry 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
referred_by_clinician_idstring | null · uuidrequired
The Clinician who referred this Lead, when one was identified. Taken from the Lead's first submission that identified one; a per-submission value is on the LeadFormResponse.
referred_by_organization_idstring | null · uuidrequired
The Organization that referred this Lead, when one was identified. Taken from the Lead's first submission that identified one; a per-submission value is on the LeadFormResponse.
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 enquiring 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 enquiry.
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": "00000000-0000-4000-8000-00000000000c",
  "object": "lead",
  "address_line_1": "10 Harley Street",
  "address_line_2": "Marylebone",
  "attachments":  … ]
     … }
      "id": "f631636b-32e2-41be-8e4f-0a34ee0d5d59",
      "download_url": "https://files.example.invalid/document.pdf?signature=test",
      "filename": "referral-letter.pdf"
    }
  ],
  "city": "London",
  "clinician":  … }
    "id": "00000000-0000-4000-8000-000000000002",
    "object": "clinician",
    "created_at": "2026-01-01T09:00:00Z",
    "display_name": "Dr Alex Morgan",
    "email": "alex.morgan@example.com",
    "first_name": "Alex",
    "last_name": "Morgan",
    "links":  … }
      "bookings": "https://api.carebit.co/v1/bookings?clinician_id=00000000-0000-4000-8000-000000000002"
    },
    "medical_specialty": "Cardiology",
    "title": "Dr",
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "country_code": "GB",
  "county": "Greater London",
  "created_at": "2026-01-01T09:00:00Z",
  "creation_source": "api",
  "date_of_birth": "1990-01-01",
  "display_name": "Dr Alex Morgan",
  "email": "alex.morgan@example.com",
  "first_name": "Alex",
  "form_responses":  … ]
     … }
      "id": "adf881b8-4eed-42c0-8903-515f6cc8a134",
      "form_name": "New patient inquiry",
      "form_type": "inquiry_form",
      "submitted_at": "2026-01-01T09:00:00Z",
      "url": "https://files.example.invalid/document.pdf?signature=test"
    }
  ],
  "gdpr_consent_granted_at": "2026-01-01T09:00:00Z",
  "gdpr_consent_withdrawn_at": "2026-01-01T09:00:00Z",
  "internal_notes": "Asked about evening appointments with Dr Smith.",
  "is_converted_to_patient": true,
  "is_lost": false,
  "is_opted_out_of_sms": false,
  "is_signed_up_to_newsletters": true,
  "last_name": "Morgan",
  "lead_type": "inquiry",
  "links":  … }
    "clinician": "https://api.carebit.co/v1/clinicians/00000000-0000-4000-8000-000000000002",
    "remote_file_import_batch": "https://api.carebit.co/v1/remote_file_import_batches/00000000-0000-4000-8000-00000000000a",
    "self": "https://api.carebit.co/v1/leads/00000000-0000-4000-8000-00000000000c",
    "service": "https://api.carebit.co/v1/services/00000000-0000-4000-8000-000000000005"
  },
  "mobile": "7700900123",
  "mobile_country_dial_code": "GB",
  "organization_privacy_policy_consent_granted_at": "2026-01-01T09:00:00Z",
  "patient_id": "00000000-0000-4000-8000-000000000004",
  "phone": "2071234567",
  "phone_country_dial_code": "GB",
  "postcode": "W1G 9PF",
  "presenting_problem": "Persistent right knee pain",
  "referral_notes": "Referred by Dr Patel at Riverside Medical.",
  "referral_source": "consultant",
  "referred_by_clinician_id": "b5ac896f-f746-4df1-899a-c12d33b84b2d",
  "referred_by_organization_id": "8cda84a9-bf46-4f81-8f3c-66dd352e95db",
  "remote_file_import_batch_id": "00000000-0000-4000-8000-00000000000a",
  "service":  … }
    "id": "00000000-0000-4000-8000-000000000005",
    "object": "service",
    "created_at": "2026-01-01T09:00:00Z",
    "description": "An initial consultation at the Harley Street Clinic.",
    "duration_minutes": 30,
    "is_bookable_online": true,
    "name": "Initial consultation",
    "service_variants":  … ]
       … }
        "id": "00000000-0000-4000-8000-000000000006",
        "clinician_id": "00000000-0000-4000-8000-000000000002",
        "currency": "GBP",
        "description": "An initial consultation at the Harley Street Clinic.",
        "links":  … }
          "clinician": "https://api.carebit.co/v1/clinicians/00000000-0000-4000-8000-000000000002",
          "location": "https://api.carebit.co/v1/locations/00000000-0000-4000-8000-000000000003"
        },
        "location_id": "00000000-0000-4000-8000-000000000003",
        "net_price": 1,
        "permits_remote_bookings": true
      }
    ],
    "tax_rate":  … }
      "id": "00000000-0000-4000-8000-000000000029",
      "description": "An initial consultation at the Harley Street Clinic.",
      "percentage": 20,
      "title": "VAT"
    },
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "sex": "female",
  "stage":  … }
    "id": "00000000-0000-4000-8000-00000000000d",
    "object": "lead_stage",
    "created_at": "2026-01-01T09:00:00Z",
    "is_conversion_stage": true,
    "is_lost_stage": true,
    "name": "Initial consultation",
    "position": 1,
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "title": "Dr",
  "updated_at": "2026-01-01T09:00:00Z"
}

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/00000000-0000-4000-8000-00000000000c" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"

200 response

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

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 enquiry 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 enquiry 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 enquiring about. It must belong to your Organization. Pass null to clear.
sexstring | null
The sex of the Lead as supplied on the enquiry.
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 API. 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.
form_responsesarrayrequired
The forms this lead submitted, oldest first. Follow each url for the answers. Enquiries a staff member recorded by hand are not listed, because they have no form.
- itemsobject
  - form_namestringrequired
    The name of the form the respondent submitted.
  - form_typestringrequired
    Whether the submission came from an enquiry form or a referral form.
    Allowed values: inquiry_form | referral_form
  - idstring · uuidrequired
    The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - submitted_atstring · date-timerequired
    An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
  - urlstring · urirequired
    The full URL of a related resource.
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's current pipeline stage is a lost stage. A lost stage has the mark_lead_lost action, or the title Lost or Rejected. 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 enquiry 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
referred_by_clinician_idstring | null · uuidrequired
The Clinician who referred this Lead, when one was identified. Taken from the Lead's first submission that identified one; a per-submission value is on the LeadFormResponse.
referred_by_organization_idstring | null · uuidrequired
The Organization that referred this Lead, when one was identified. Taken from the Lead's first submission that identified one; a per-submission value is on the LeadFormResponse.
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 enquiring 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 enquiry.
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": "00000000-0000-4000-8000-00000000000c",
  "object": "lead",
  "address_line_1": "10 Harley Street",
  "address_line_2": "Marylebone",
  "attachments":  … ]
     … }
      "id": "f631636b-32e2-41be-8e4f-0a34ee0d5d59",
      "download_url": "https://files.example.invalid/document.pdf?signature=test",
      "filename": "referral-letter.pdf"
    }
  ],
  "city": "London",
  "clinician":  … }
    "id": "00000000-0000-4000-8000-000000000002",
    "object": "clinician",
    "created_at": "2026-01-01T09:00:00Z",
    "display_name": "Dr Alex Morgan",
    "email": "alex.morgan@example.com",
    "first_name": "Alex",
    "last_name": "Morgan",
    "links":  … }
      "bookings": "https://api.carebit.co/v1/bookings?clinician_id=00000000-0000-4000-8000-000000000002"
    },
    "medical_specialty": "Cardiology",
    "title": "Dr",
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "country_code": "GB",
  "county": "Greater London",
  "created_at": "2026-01-01T09:00:00Z",
  "creation_source": "api",
  "date_of_birth": "1990-01-01",
  "display_name": "Dr Alex Morgan",
  "email": "alex.morgan@example.com",
  "first_name": "Alex",
  "form_responses":  … ]
     … }
      "id": "adf881b8-4eed-42c0-8903-515f6cc8a134",
      "form_name": "New patient inquiry",
      "form_type": "inquiry_form",
      "submitted_at": "2026-01-01T09:00:00Z",
      "url": "https://files.example.invalid/document.pdf?signature=test"
    }
  ],
  "gdpr_consent_granted_at": "2026-01-01T09:00:00Z",
  "gdpr_consent_withdrawn_at": "2026-01-01T09:00:00Z",
  "internal_notes": "Asked about evening appointments with Dr Smith.",
  "is_converted_to_patient": true,
  "is_lost": false,
  "is_opted_out_of_sms": false,
  "is_signed_up_to_newsletters": true,
  "last_name": "Morgan",
  "lead_type": "inquiry",
  "links":  … }
    "clinician": "https://api.carebit.co/v1/clinicians/00000000-0000-4000-8000-000000000002",
    "remote_file_import_batch": "https://api.carebit.co/v1/remote_file_import_batches/00000000-0000-4000-8000-00000000000a",
    "self": "https://api.carebit.co/v1/leads/00000000-0000-4000-8000-00000000000c",
    "service": "https://api.carebit.co/v1/services/00000000-0000-4000-8000-000000000005"
  },
  "mobile": "7700900123",
  "mobile_country_dial_code": "GB",
  "organization_privacy_policy_consent_granted_at": "2026-01-01T09:00:00Z",
  "patient_id": "00000000-0000-4000-8000-000000000004",
  "phone": "2071234567",
  "phone_country_dial_code": "GB",
  "postcode": "W1G 9PF",
  "presenting_problem": "Persistent right knee pain",
  "referral_notes": "Referred by Dr Patel at Riverside Medical.",
  "referral_source": "consultant",
  "referred_by_clinician_id": "b5ac896f-f746-4df1-899a-c12d33b84b2d",
  "referred_by_organization_id": "8cda84a9-bf46-4f81-8f3c-66dd352e95db",
  "remote_file_import_batch_id": "00000000-0000-4000-8000-00000000000a",
  "service":  … }
    "id": "00000000-0000-4000-8000-000000000005",
    "object": "service",
    "created_at": "2026-01-01T09:00:00Z",
    "description": "An initial consultation at the Harley Street Clinic.",
    "duration_minutes": 30,
    "is_bookable_online": true,
    "name": "Initial consultation",
    "service_variants":  … ]
       … }
        "id": "00000000-0000-4000-8000-000000000006",
        "clinician_id": "00000000-0000-4000-8000-000000000002",
        "currency": "GBP",
        "description": "An initial consultation at the Harley Street Clinic.",
        "links":  … }
          "clinician": "https://api.carebit.co/v1/clinicians/00000000-0000-4000-8000-000000000002",
          "location": "https://api.carebit.co/v1/locations/00000000-0000-4000-8000-000000000003"
        },
        "location_id": "00000000-0000-4000-8000-000000000003",
        "net_price": 1,
        "permits_remote_bookings": true
      }
    ],
    "tax_rate":  … }
      "id": "00000000-0000-4000-8000-000000000029",
      "description": "An initial consultation at the Harley Street Clinic.",
      "percentage": 20,
      "title": "VAT"
    },
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "sex": "female",
  "stage":  … }
    "id": "00000000-0000-4000-8000-00000000000d",
    "object": "lead_stage",
    "created_at": "2026-01-01T09:00:00Z",
    "is_conversion_stage": true,
    "is_lost_stage": true,
    "name": "Initial consultation",
    "position": 1,
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "title": "Dr",
  "updated_at": "2026-01-01T09:00:00Z"
}

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

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.