# Digital Form Responses

Patient responses to DigitalForms.

## List a Patient's DigitalFormResponses

`GET /v1/digital_form_responses`

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

## Parameters

- `patient_id` (query, `string`) (required) - The Patient whose DigitalFormResponses 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`.

## Response `200`

Paginated list of `DigitalFormResponse` objects.

- `any`

### Example

```json
{
  "object": "list",
  "data": [
    {
      "id": "4262fdc0-c7a1-4856-83c4-16ed34cb8773",
      "object": "digital_form_response",
      "answers": [
        {
          "id": "7ae2abaf-6f3e-4fbf-842d-5cbbe91b8492",
          "attachment_url": "https://files.example.invalid/document.pdf?signature=test",
          "date_value": "2026-01-01",
          "digital_form_question": {
            "id": "6d826770-c3ae-43c6-8b16-5ff8a72a24da",
            "choices": [
              {
                "id": "4f4f0cb8-0f36-42ed-8292-e679adb19729",
                "numerical_value": 1.5,
                "text_value": "yes",
                "title": "Dr"
              }
            ],
            "help_text": "Select every option that applies.",
            "is_answer_required": true,
            "list_order_number": 1,
            "question_type": "consent_required",
            "title": "Dr"
          },
          "digital_form_question_choice_id": "26a2ba65-f724-4add-8940-9f63f02f8711",
          "digital_form_question_id": "6d826770-c3ae-43c6-8b16-5ff8a72a24da",
          "has_consented": true,
          "numerical_value": 1.5,
          "text_value": "The symptoms started two weeks ago."
        }
      ],
      "booking_id": "92a3b4c5-d6e7-4f01-8234-56789abcdef0",
      "completed_at": "2026-01-01T09:00:00Z",
      "created_at": "2026-01-01T09:00:00Z",
      "digital_form": {
        "id": "e75b04dc-2889-491d-8e08-691c3a830d9c",
        "object": "digital_form",
        "attachment_url": "https://files.example.invalid/document.pdf?signature=test",
        "created_at": "2026-01-01T09:00:00Z",
        "patient_instructions": "Please complete this form before your appointment.",
        "questions": [
          {
            "id": "2214b284-64d6-4130-8b10-1602a2050126",
            "choices": [
              {
                "id": "4f4f0cb8-0f36-42ed-8292-e679adb19729",
                "numerical_value": 1.5,
                "text_value": "yes",
                "title": "Dr"
              }
            ],
            "help_text": "Select every option that applies.",
            "is_answer_required": true,
            "list_order_number": 1,
            "question_type": "consent_required",
            "title": "Dr"
          }
        ],
        "title": "Dr",
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "due_at": "2026-01-01T09:00:00Z",
      "links": {
        "patient": "https://api.carebit.co/v1/patients/1a2b3c4d-5e6f-4789-8abc-def012345678",
        "transmissions": "https://api.carebit.co/v1/transmissions?patient_id=1a2b3c4d-5e6f-4789-8abc-def012345678&resource_type=digital_form_response"
      },
      "patient_id": "1a2b3c4d-5e6f-4789-8abc-def012345678",
      "status": "awaiting_completion",
      "total_score": 1,
      "updated_at": "2026-01-01T09:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": "eyJzdGFydF90aW1lIjoiMjAyNi0wMS0wMVQwOTowMDowMFoifQ",
  "url": "/v1/digital_form_responses"
}
```

## 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, or the project is disabled.

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

```javascript
const response = await fetch("https://api.carebit.co/v1/digital_form_responses?patient_id=8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
  },
});

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

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

```python
import os
import requests

response = requests.get(
    "https://api.carebit.co/v1/digital_form_responses?patient_id=8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"

response = HTTParty.get(
  "https://api.carebit.co/v1/digital_form_responses?patient_id=8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}"
  }
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->get("https://api.carebit.co/v1/digital_form_responses?patient_id=8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


## Create and send a DigitalFormResponse

`POST /v1/digital_form_responses`

Creates a pending DigitalFormResponse and queues an email asking the Patient to complete it.

**Required API scopes:** `digital_form_responses.create`

## Parameters

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

- `object`
  - `booking_id` (`string | null`) - format: `uuid`; The optional Booking associated with the response.
  - `digital_form_id` (`string`) - format: `uuid`; The DigitalForm to send to the Patient.
  - `due_at` (`string | null`) - format: `date-time`; The optional time by which the Patient should complete the DigitalForm.
  - `patient_id` (`string`) - format: `uuid`; The Patient who should complete the DigitalForm.

### Example

```json
{
  "booking_id": "00000000-0000-4000-8000-000000000001",
  "digital_form_id": "00000000-0000-4000-8000-000000000020",
  "due_at": "2026-01-04T17:00:00Z",
  "patient_id": "00000000-0000-4000-8000-000000000004"
}
```

## Response `201`

The requested `DigitalFormResponse`.

- `object`
  - `answers` (`array`) - The answers currently recorded for the DigitalFormResponse.
    - `items` (`object`)
      - `attachment_url` (`string | null`) - format: `uri`; The temporary URL for an attached answer.
      - `date_value` (`string | null`) - format: `date`; The date supplied for a date question.
      - `digital_form_question` (`object`) - A question on a DigitalForm. Embedded on DigitalForm and on each DigitalFormResponse answer.
        - `choices` (`array`) - The choices available for a choice question.
          - `items` (`object`)
            - `id` (`string`) - format: `uuid`; The identifier of the DigitalFormQuestionChoice.
            - `numerical_value` (`number | null`) - The optional numerical value assigned to the choice.
            - `text_value` (`string | null`) - The optional machine-readable text value assigned to the choice.
            - `title` (`string`) - The choice shown to the Patient.
        - `help_text` (`string | null`) - The supplementary guidance shown with the question.
        - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
        - `is_answer_required` (`boolean`) - Whether the Patient must answer the question.
        - `list_order_number` (`integer | null`) - The position of the question in the DigitalForm.
        - `question_type` (`string`) - enum: `consent_required`, `information_statement`, `multiple_choice_input`, `single_choice_input`, `text_input`, `number_input`, `date_input`, `signature_input`; The input and consent behavior of the question.
        - `title` (`string`) - The question shown to the Patient.
      - `digital_form_question_choice_id` (`string | null`) - format: `uuid`; The selected DigitalFormQuestionChoice.
      - `digital_form_question_id` (`string`) - format: `uuid`; The DigitalFormQuestion answered.
      - `has_consented` (`boolean | null`) - Whether the Patient granted the requested consent.
      - `id` (`string`) - format: `uuid`; The identifier of the DigitalFormQuestionAnswer.
      - `numerical_value` (`number | null`) - The numerical answer.
      - `text_value` (`string | null`) - The text answer or selected choice title.
  - `booking_id` (`string | null`) - format: `uuid`; The Booking associated with the response.
  - `completed_at` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `digital_form` (`object`)
    - `attachment_url` (`string | null`) - format: `uri`; The temporary URL for the attachment displayed with the DigitalForm.
    - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
    - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
    - `object` (`any`) - Discriminator value emitted at `object`.
    - `patient_instructions` (`string | null`) - The sanitized instructions shown to the Patient.
    - `questions` (`array`) - The ordered questions included in the DigitalForm.
      - `items` (`object`) - A question on a DigitalForm. Embedded on DigitalForm and on each DigitalFormResponse answer.
        - `choices` (`array`) - The choices available for a choice question.
          - `items` (`object`)
            - `id` (`string`) - format: `uuid`; The identifier of the DigitalFormQuestionChoice.
            - `numerical_value` (`number | null`) - The optional numerical value assigned to the choice.
            - `text_value` (`string | null`) - The optional machine-readable text value assigned to the choice.
            - `title` (`string`) - The choice shown to the Patient.
        - `help_text` (`string | null`) - The supplementary guidance shown with the question.
        - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
        - `is_answer_required` (`boolean`) - Whether the Patient must answer the question.
        - `list_order_number` (`integer | null`) - The position of the question in the DigitalForm.
        - `question_type` (`string`) - enum: `consent_required`, `information_statement`, `multiple_choice_input`, `single_choice_input`, `text_input`, `number_input`, `date_input`, `signature_input`; The input and consent behavior of the question.
        - `title` (`string`) - The question shown to the Patient.
    - `title` (`string`) - The title of the DigitalForm.
    - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `due_at` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - `links` (`object`) - URLs to related resources.
    - `patient` (`string`) - format: `uri`; The full URL of a related resource.
    - `transmissions` (`string`) - format: `uri`; The full URL of a related resource.
  - `object` (`any`) - Discriminator value emitted at `object`.
  - `patient_id` (`string`) - format: `uuid`; The Patient asked to complete the DigitalForm.
  - `status` (`string`) - enum: `awaiting_completion`, `partially_completed`, `overdue`, `completed`; The completion status of the DigitalFormResponse.
  - `total_score` (`integer | null`) - The sum of numerical answers configured to contribute to the score.
  - `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": "4262fdc0-c7a1-4856-83c4-16ed34cb8773",
  "object": "digital_form_response",
  "answers": [
    {
      "id": "7ae2abaf-6f3e-4fbf-842d-5cbbe91b8492",
      "attachment_url": "https://files.example.invalid/document.pdf?signature=test",
      "date_value": "2026-01-01",
      "digital_form_question": {
        "id": "6d826770-c3ae-43c6-8b16-5ff8a72a24da",
        "choices": [
          {
            "id": "4f4f0cb8-0f36-42ed-8292-e679adb19729",
            "numerical_value": 1.5,
            "text_value": "yes",
            "title": "Dr"
          }
        ],
        "help_text": "Select every option that applies.",
        "is_answer_required": true,
        "list_order_number": 1,
        "question_type": "consent_required",
        "title": "Dr"
      },
      "digital_form_question_choice_id": "26a2ba65-f724-4add-8940-9f63f02f8711",
      "digital_form_question_id": "6d826770-c3ae-43c6-8b16-5ff8a72a24da",
      "has_consented": true,
      "numerical_value": 1.5,
      "text_value": "The symptoms started two weeks ago."
    }
  ],
  "booking_id": "92a3b4c5-d6e7-4f01-8234-56789abcdef0",
  "completed_at": "2026-01-01T09:00:00Z",
  "created_at": "2026-01-01T09:00:00Z",
  "digital_form": {
    "id": "e75b04dc-2889-491d-8e08-691c3a830d9c",
    "object": "digital_form",
    "attachment_url": "https://files.example.invalid/document.pdf?signature=test",
    "created_at": "2026-01-01T09:00:00Z",
    "patient_instructions": "Please complete this form before your appointment.",
    "questions": [
      {
        "id": "2214b284-64d6-4130-8b10-1602a2050126",
        "choices": [
          {
            "id": "4f4f0cb8-0f36-42ed-8292-e679adb19729",
            "numerical_value": 1.5,
            "text_value": "yes",
            "title": "Dr"
          }
        ],
        "help_text": "Select every option that applies.",
        "is_answer_required": true,
        "list_order_number": 1,
        "question_type": "consent_required",
        "title": "Dr"
      }
    ],
    "title": "Dr",
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "due_at": "2026-01-01T09:00:00Z",
  "links": {
    "patient": "https://api.carebit.co/v1/patients/1a2b3c4d-5e6f-4789-8abc-def012345678",
    "transmissions": "https://api.carebit.co/v1/transmissions?patient_id=1a2b3c4d-5e6f-4789-8abc-def012345678&resource_type=digital_form_response"
  },
  "patient_id": "1a2b3c4d-5e6f-4789-8abc-def012345678",
  "status": "awaiting_completion",
  "total_score": 1,
  "updated_at": "2026-01-01T09:00:00Z"
}
```

## Response `400`

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

- `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 `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, or the project is disabled.

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

A concurrent request holds the idempotency lease (`idempotency_conflict`). 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"
  }
}
```

## Response `422`

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

- `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 POST "https://api.carebit.co/v1/digital_form_responses" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "booking_id": "00000000-0000-4000-8000-000000000001",
  "digital_form_id": "00000000-0000-4000-8000-000000000020",
  "due_at": "2026-01-04T17:00:00Z",
  "patient_id": "00000000-0000-4000-8000-000000000004"
}'
```

```javascript
const response = await fetch("https://api.carebit.co/v1/digital_form_responses", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
  "booking_id": "00000000-0000-4000-8000-000000000001",
  "digital_form_id": "00000000-0000-4000-8000-000000000020",
  "due_at": "2026-01-04T17:00:00Z",
  "patient_id": "00000000-0000-4000-8000-000000000004"
}),
});

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

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

```python
import os
import requests
import uuid

response = requests.post(
    "https://api.carebit.co/v1/digital_form_responses",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "booking_id": "00000000-0000-4000-8000-000000000001",
        "digital_form_id": "00000000-0000-4000-8000-000000000020",
        "due_at": "2026-01-04T17:00:00Z",
        "patient_id": "00000000-0000-4000-8000-000000000004"
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"
require "json"
require "securerandom"

response = HTTParty.post(
  "https://api.carebit.co/v1/digital_form_responses",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}",
    "Idempotency-Key" => SecureRandom.uuid,
    "Content-Type" => "application/json"
  },
  body: {
    "booking_id" => "00000000-0000-4000-8000-000000000001",
    "digital_form_id" => "00000000-0000-4000-8000-000000000020",
    "due_at" => "2026-01-04T17:00:00Z",
    "patient_id" => "00000000-0000-4000-8000-000000000004"
  }.to_json
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->post("https://api.carebit.co/v1/digital_form_responses", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
      "Idempotency-Key" => bin2hex(random_bytes(16)),
    ],
    "json" => [
      "booking_id" => "00000000-0000-4000-8000-000000000001",
      "digital_form_id" => "00000000-0000-4000-8000-000000000020",
      "due_at" => "2026-01-04T17:00:00Z",
      "patient_id" => "00000000-0000-4000-8000-000000000004"
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


## Retrieve a DigitalFormResponse

`GET /v1/digital_form_responses/:id`

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

## Parameters

- `id` (path, `string`) (required) - The identifier of the DigitalFormResponse.

## Response `200`

The requested `DigitalFormResponse`.

- `object`
  - `answers` (`array`) - The answers currently recorded for the DigitalFormResponse.
    - `items` (`object`)
      - `attachment_url` (`string | null`) - format: `uri`; The temporary URL for an attached answer.
      - `date_value` (`string | null`) - format: `date`; The date supplied for a date question.
      - `digital_form_question` (`object`) - A question on a DigitalForm. Embedded on DigitalForm and on each DigitalFormResponse answer.
        - `choices` (`array`) - The choices available for a choice question.
          - `items` (`object`)
            - `id` (`string`) - format: `uuid`; The identifier of the DigitalFormQuestionChoice.
            - `numerical_value` (`number | null`) - The optional numerical value assigned to the choice.
            - `text_value` (`string | null`) - The optional machine-readable text value assigned to the choice.
            - `title` (`string`) - The choice shown to the Patient.
        - `help_text` (`string | null`) - The supplementary guidance shown with the question.
        - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
        - `is_answer_required` (`boolean`) - Whether the Patient must answer the question.
        - `list_order_number` (`integer | null`) - The position of the question in the DigitalForm.
        - `question_type` (`string`) - enum: `consent_required`, `information_statement`, `multiple_choice_input`, `single_choice_input`, `text_input`, `number_input`, `date_input`, `signature_input`; The input and consent behavior of the question.
        - `title` (`string`) - The question shown to the Patient.
      - `digital_form_question_choice_id` (`string | null`) - format: `uuid`; The selected DigitalFormQuestionChoice.
      - `digital_form_question_id` (`string`) - format: `uuid`; The DigitalFormQuestion answered.
      - `has_consented` (`boolean | null`) - Whether the Patient granted the requested consent.
      - `id` (`string`) - format: `uuid`; The identifier of the DigitalFormQuestionAnswer.
      - `numerical_value` (`number | null`) - The numerical answer.
      - `text_value` (`string | null`) - The text answer or selected choice title.
  - `booking_id` (`string | null`) - format: `uuid`; The Booking associated with the response.
  - `completed_at` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `digital_form` (`object`)
    - `attachment_url` (`string | null`) - format: `uri`; The temporary URL for the attachment displayed with the DigitalForm.
    - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
    - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
    - `object` (`any`) - Discriminator value emitted at `object`.
    - `patient_instructions` (`string | null`) - The sanitized instructions shown to the Patient.
    - `questions` (`array`) - The ordered questions included in the DigitalForm.
      - `items` (`object`) - A question on a DigitalForm. Embedded on DigitalForm and on each DigitalFormResponse answer.
        - `choices` (`array`) - The choices available for a choice question.
          - `items` (`object`)
            - `id` (`string`) - format: `uuid`; The identifier of the DigitalFormQuestionChoice.
            - `numerical_value` (`number | null`) - The optional numerical value assigned to the choice.
            - `text_value` (`string | null`) - The optional machine-readable text value assigned to the choice.
            - `title` (`string`) - The choice shown to the Patient.
        - `help_text` (`string | null`) - The supplementary guidance shown with the question.
        - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
        - `is_answer_required` (`boolean`) - Whether the Patient must answer the question.
        - `list_order_number` (`integer | null`) - The position of the question in the DigitalForm.
        - `question_type` (`string`) - enum: `consent_required`, `information_statement`, `multiple_choice_input`, `single_choice_input`, `text_input`, `number_input`, `date_input`, `signature_input`; The input and consent behavior of the question.
        - `title` (`string`) - The question shown to the Patient.
    - `title` (`string`) - The title of the DigitalForm.
    - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `due_at` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - `links` (`object`) - URLs to related resources.
    - `patient` (`string`) - format: `uri`; The full URL of a related resource.
    - `transmissions` (`string`) - format: `uri`; The full URL of a related resource.
  - `object` (`any`) - Discriminator value emitted at `object`.
  - `patient_id` (`string`) - format: `uuid`; The Patient asked to complete the DigitalForm.
  - `status` (`string`) - enum: `awaiting_completion`, `partially_completed`, `overdue`, `completed`; The completion status of the DigitalFormResponse.
  - `total_score` (`integer | null`) - The sum of numerical answers configured to contribute to the score.
  - `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": "4262fdc0-c7a1-4856-83c4-16ed34cb8773",
  "object": "digital_form_response",
  "answers": [
    {
      "id": "7ae2abaf-6f3e-4fbf-842d-5cbbe91b8492",
      "attachment_url": "https://files.example.invalid/document.pdf?signature=test",
      "date_value": "2026-01-01",
      "digital_form_question": {
        "id": "6d826770-c3ae-43c6-8b16-5ff8a72a24da",
        "choices": [
          {
            "id": "4f4f0cb8-0f36-42ed-8292-e679adb19729",
            "numerical_value": 1.5,
            "text_value": "yes",
            "title": "Dr"
          }
        ],
        "help_text": "Select every option that applies.",
        "is_answer_required": true,
        "list_order_number": 1,
        "question_type": "consent_required",
        "title": "Dr"
      },
      "digital_form_question_choice_id": "26a2ba65-f724-4add-8940-9f63f02f8711",
      "digital_form_question_id": "6d826770-c3ae-43c6-8b16-5ff8a72a24da",
      "has_consented": true,
      "numerical_value": 1.5,
      "text_value": "The symptoms started two weeks ago."
    }
  ],
  "booking_id": "92a3b4c5-d6e7-4f01-8234-56789abcdef0",
  "completed_at": "2026-01-01T09:00:00Z",
  "created_at": "2026-01-01T09:00:00Z",
  "digital_form": {
    "id": "e75b04dc-2889-491d-8e08-691c3a830d9c",
    "object": "digital_form",
    "attachment_url": "https://files.example.invalid/document.pdf?signature=test",
    "created_at": "2026-01-01T09:00:00Z",
    "patient_instructions": "Please complete this form before your appointment.",
    "questions": [
      {
        "id": "2214b284-64d6-4130-8b10-1602a2050126",
        "choices": [
          {
            "id": "4f4f0cb8-0f36-42ed-8292-e679adb19729",
            "numerical_value": 1.5,
            "text_value": "yes",
            "title": "Dr"
          }
        ],
        "help_text": "Select every option that applies.",
        "is_answer_required": true,
        "list_order_number": 1,
        "question_type": "consent_required",
        "title": "Dr"
      }
    ],
    "title": "Dr",
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "due_at": "2026-01-01T09:00:00Z",
  "links": {
    "patient": "https://api.carebit.co/v1/patients/1a2b3c4d-5e6f-4789-8abc-def012345678",
    "transmissions": "https://api.carebit.co/v1/transmissions?patient_id=1a2b3c4d-5e6f-4789-8abc-def012345678&resource_type=digital_form_response"
  },
  "patient_id": "1a2b3c4d-5e6f-4789-8abc-def012345678",
  "status": "awaiting_completion",
  "total_score": 1,
  "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, or the project is disabled.

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

```javascript
const response = await fetch("https://api.carebit.co/v1/digital_form_responses/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
  },
});

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

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

```python
import os
import requests

response = requests.get(
    "https://api.carebit.co/v1/digital_form_responses/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"

response = HTTParty.get(
  "https://api.carebit.co/v1/digital_form_responses/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}"
  }
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->get("https://api.carebit.co/v1/digital_form_responses/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```