# Get a Lead's form response

`GET /v1/lead_form_responses/:id`

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, `string`) (required)

## Response `200`

The requested `LeadFormResponse`.

- `object`
  - `answers` (`array`) - 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`.
    - `items` (`object`) - One question and its submitted answer, embedded in a FormResponse.
      - `field_name` (`string | null`) - 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_type` (`string | null`) - The kind of question asked, for example `text_area` or `date_field`. Use it to parse `value`.
      - `label` (`string`) - The question as it was shown to the respondent, with HTML sanitized. A question saved with no label returns an empty string.
      - `value` (`string | null`) - 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.
      - `values` (`array`) - 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.
        - `items` (`string`)
  - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `form_name` (`string`) - The name of the form the respondent submitted.
  - `form_type` (`string`) - enum: `inquiry_form`, `referral_form`; 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.
  - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - `lead_id` (`string`) - format: `uuid`; The Lead the submission created or updated.
  - `links` (`object`) - URLs to related resources.
    - `lead` (`string`) - format: `uri`; The full URL of a related resource.
    - `self` (`string`) - format: `uri`; The full URL of a related resource.
  - `object` (`any`) - Discriminator value emitted at `object`.
  - `referral_notes` (`string | null`) - 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_source` (`string | null`) - enum: `consultant`, `embassy`, `family_or_friend`, `gp_practice`, `hospital`, `insurance_company`, `physiotherapist`, `presentation_talk`, `previous_patient`, `private_practice`, `search_engine`, `self_referral`, `social_media`, `website`, `other`, `null`; How this submission reached the Organization. A form submitted on the Organization's website records `website`.
  - `referred_by_clinician_id` (`string | null`) - format: `uuid`; The Clinician who referred this submission, when one was identified.
  - `referred_by_organization_id` (`string | null`) - format: `uuid`; The Organization that referred this submission, when one was identified.
  - `submitted_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `tracking` (`any`) - The marketing attribution captured with this submission.
  - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.

### Example

```json
{
  "id": "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"
}
```

## Response `401`

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

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

### Example

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

## Response `403`

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

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

### Example

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

## Response `404`

Error response.

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

### Example

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

## Response `429`

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

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

### Example

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

## Code samples

```bash
curl -X GET "https://api.carebit.co/v1/lead_form_responses/b5f5c363-d0b7-4e92-86ef-1d87afe8e8f8" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"
```

```javascript
const response = await fetch("https://api.carebit.co/v1/lead_form_responses/b5f5c363-d0b7-4e92-86ef-1d87afe8e8f8", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
  },
});

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

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

```python
import os
import requests

response = requests.get(
    "https://api.carebit.co/v1/lead_form_responses/b5f5c363-d0b7-4e92-86ef-1d87afe8e8f8",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"

response = HTTParty.get(
  "https://api.carebit.co/v1/lead_form_responses/b5f5c363-d0b7-4e92-86ef-1d87afe8e8f8",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}"
  }
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->get("https://api.carebit.co/v1/lead_form_responses/b5f5c363-d0b7-4e92-86ef-1d87afe8e8f8", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```