Carebit API

Test Results

Structured or file-based Test Results.

Endpoints

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

post/v1/test_result_batchesCreate up to 100 Test Results in one request
get/v1/test_resultsList Test Results
post/v1/test_resultsCreate a Test Result
get/v1/test_results/:idGet a Test Result

post/v1/test_result_batches

Create up to 100 Test Results in one request

Returns 201 when every TestResult is created immediately. Returns 202 when at least one item includes file_url or file_base64; poll remote_file_import_batch for each file's import status. Both responses use TestResultBatchResponse.

Required API scopes: test_results.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

itemsarrayrequired
The test results to create. Items are processed in their submitted order.
- itemsobject
  - automatically_create_resource_permission_for_patientboolean
    Whether Carebit should automatically share the test result with the patient after processing.
  - booking_idstring | null · uuid
    The identifier of the booking associated with the test result, or null when it is not linked to a booking.
  - clinician_idstring | null · uuid
    The identifier of the clinician associated with the test result, or null when none is assigned.
  - descriptionstring | null
    A description of the TestResult.
  - file_base64string | null · byte
    The test result bytes encoded as Base64. Provide this with filename instead of file_url. The decoded file can be at most 7 MB.
  - file_urlstring | null · uri
    The public HTTPS URL of a test result document that Carebit should download.
  - filenamestring | null
    The filename to use for the test result. Required with file_base64; defaults to the remote file's filename for URL sources.
  - notify_patient_of_resource_permissionboolean
    Whether Carebit should notify the patient when the test result is shared with them.
  - patient_idstring · uuid
    The identifier of the patient that the test result belongs to.
  - statusstring
    The workflow status to assign to the test result.
    Allowed values: awaiting_review | complete | draft | reviewed
  - test_result_itemsarray
    The structured clinical observations to include in the test result.
    - itemsobject
      - is_abnormalboolean | null
        Whether the observation falls outside its reference range, when known.
      - notesstring | null
        Additional clinical notes about the observation.
      - observation_codestring | null
        The laboratory or clinical code that identifies the observation.
      - observation_namestring | null
        The observation's display name.
      - observation_textstring | null
        The textual observation value, when the result is not represented numerically.
      - observation_valuenumber | null
        The numeric value of the observation, when applicable.
      - observation_value_precisionstring | null
        The qualifier that indicates whether observation_value is exact or a boundary.
        Allowed values: < | = | > | null
      - observation_value_unitsstring | null
        The unit used for observation_value.
      - observed_atstring | null · date-time
        An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
      - reference_range_lower_boundnumber | null
        The lower bound of the expected reference range, when supplied.
      - reference_range_upper_boundnumber | null
        The upper bound of the expected reference range, when supplied.
      - statusstring | null
        The clinical workflow status to assign to the observation.
        Allowed values: corrected | final | pending | null
  - titlestring
    The display title of the test result.

Responses

201

Every TestResult was created immediately.

itemsarrayrequired
The per-item outcomes in their original request order.
- itemsobject
  The result of one item in a Test Result batch. test_result contains the created TestResult when processing finishes immediately. For an imported file, it is null and remote_file_import_batch_item_id identifies the item being processed.
  - objectanyrequired
    Always test_result_batch_item.
  - positionintegerrequired
    The zero-based position of the item in the request items array.
  - remote_file_import_batch_item_idstring | null · uuidrequired
    The import item identifier for a file that is still being processed. Null when the TestResult was created immediately. Poll the parent remote_file_import_batch for status.
  - statusstringrequired
    The item's processing status. succeeded when the TestResult was created immediately; otherwise the current file import status.
    Allowed values: failed | pending | processing | succeeded
  - test_resultobject | nullrequired
    The created TestResult, or null while an imported file is being processed.
    - automatically_create_resource_permission_for_patientbooleanrequired
      Whether Carebit automatically shares the test result with the patient after processing.
    - created_atstring · date-timerequired
      An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
    - download_urlstring | null · urirequired
      The short-lived signed download URL for the TestResult. Null until the uploaded file passes malware scanning.
    - filenamestring | nullrequired
      The original filename of the test result document, when one was supplied.
    - idstring · uuidrequired
      The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
    - linksobjectrequired
      URLs to related resources.
      - bookingstring | null · urirequired
        The full URL of a related resource.
      - clinicianstring | null · urirequired
        The full URL of a related resource.
      - patientstring | null · urirequired
        The full URL of a related resource.
      - remote_file_import_batchstring · uri
        The full URL of a related resource.
    - notify_patient_of_resource_permissionboolean | nullrequired
      Whether Carebit notifies the patient when the test result is shared with them.
    - objectanyrequired
      Discriminator value emitted at object.
    - remote_file_import_batch_idstring · uuid
      The identifier of the remote file import batch created for the uploaded file. Set on the create response when file_url or file_base64 was submitted.
    - statusstring | nullrequired
      The workflow status of the test result.
      Allowed values: awaiting_proofreading | awaiting_receipt | awaiting_review | awaiting_sending | awaiting_typing | complete | draft | reviewed | null
    - test_result_itemsarrayrequired
      The structured clinical observations included in the test result.
      - 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_abnormalboolean | nullrequired
        Whether the observation falls outside its reference range, when known.
        notesstring | nullrequired
        Additional clinical notes about the observation.
        objectanyrequired
        Discriminator value emitted at object.
        observation_codestring | nullrequired
        The laboratory or clinical code that identifies the observation.
        observation_namestring | nullrequired
        The observation's display name.
        observation_textstring | nullrequired
        The textual observation value, when the result is not represented numerically.
        observation_valuenumber | nullrequired
        The numeric value of the observation, when applicable.
        observation_value_precisionstring | nullrequired
        The precision qualifier for observation_value. < and > denote a bound, and = denotes an exact value.
        Allowed values: < | = | > | null
        observation_value_unitsstring | nullrequired
        The unit used for observation_value.
        observed_atstring | null · date-timerequired
        An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
        reference_range_lower_boundnumber | nullrequired
        The lower bound of the expected reference range, when supplied.
        reference_range_upper_boundnumber | nullrequired
        The upper bound of the expected reference range, when supplied.
        statusstring | nullrequired
        The clinical workflow status of the observation.
        Allowed values: corrected | final | pending | null
        updated_atstring · date-timerequired
        An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
    - titlestring | nullrequired
      The display title of the test result.
    - updated_atstring · date-timerequired
      An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
objectanyrequired
Always test_result_batch.
remote_file_import_batchobject | nullrequired
The file import batch to poll, or null when every TestResult was created immediately.
- completed_countintegerrequired
  The number of items that finished processing successfully.
- created_atstring · date-timerequired
  An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
- failed_countintegerrequired
  The number of items that finished processing with an error.
- idstring · uuidrequired
  The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
- itemsarrayrequired
  The import items in their original request order.
  - itemsobject
    - created_resourcestring | null · urirequired
      The URL of the resource created for a succeeded item. Null unless status is succeeded.
    - created_resource_idstring | null · uuidrequired
      The identifier of the resource created for a succeeded item. Null unless status is succeeded.
    - created_resource_typestring | nullrequired
      The type of resource created for a succeeded item. Null unless status is succeeded.
      Allowed values: null | Attachment | Letter | Note | TestResult
    - errorobject | nullrequired
      The failure details for this item. Null unless the item has failed.
      - codestring | nullrequired
        The machine-readable error code.
      - messagestring | nullrequired
        A message that explains how the item failed.
    - idstring · uuidrequired
      The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
    - objectanyrequired
      Always remote_file_import_batch_item.
    - positionintegerrequired
      The zero-based position of the item in the submitted batch.
    - statusstringrequired
      The current download, validation, and malware-scanning status of the item.
      Allowed values: failed | pending | processing | succeeded
- linksobjectrequired
  URLs to related resources.
  - selfstring · urirequired
    The full URL of a related resource.
- objectanyrequired
  Discriminator value emitted at object.
- resource_typestringrequired
  The type of resource created by every item in the batch.
  Allowed values: letter | note | test_result
- statusstringrequired
  The current download, validation, and malware-scanning status of the batch.
  Allowed values: completed | pending | processing
- total_countintegerrequired
  The total number of items submitted in the batch.
- updated_atstring · date-timerequired
  An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.

Example

{
  "object": "test_result_batch",
  "items":  … ]
     … }
      "object": "test_result_batch_item",
      "position": 0,
      "remote_file_import_batch_item_id": "57bed2bf-e2e1-463b-8a96-643e3817a8b8",
      "status": "failed",
      "test_result":  … }
        "id": "9d4a13e1-0eea-4669-88c4-03316c092c77",
        "object": "test_result",
        "automatically_create_resource_permission_for_patient": true,
        "created_at": "2026-01-01T09:00:00Z",
        "download_url": "https://files.example.invalid/document.pdf?signature=test",
        "filename": "referral-letter.pdf",
        "links":  … }
          "booking": "https://api.carebit.co/v1/bookings/92a3b4c5-d6e7-4f01-8234-56789abcdef0",
          "clinician": "https://api.carebit.co/v1/clinicians/2b3c4d5e-6f70-489a-9bcd-ef0123456789",
          "patient": "https://api.carebit.co/v1/patients/1a2b3c4d-5e6f-4789-8abc-def012345678",
          "remote_file_import_batch": "https://api.carebit.co/v1/remote_file_import_batches/ebc38802-f219-4c7b-8136-8e963a0c69e0"
        },
        "notify_patient_of_resource_permission": true,
        "remote_file_import_batch_id": "ebc38802-f219-4c7b-8136-8e963a0c69e0",
        "status": "awaiting_proofreading",
        "test_result_items":  … ]
           … }
            "id": "7592f451-4733-44f1-8560-1bb6075fa552",
            "object": "test_result_item",
            "created_at": "2026-01-01T09:00:00Z",
            "is_abnormal": false,
            "notes": "Please confirm the appointment by email.",
            "observation_code": "718-7",
            "observation_name": "Haemoglobin",
            "observation_text": "Within the expected range",
            "observation_value": 14.5,
            "observation_value_precision": "<",
            "observation_value_units": "g/dL",
            "observed_at": "2026-01-01T09:00:00Z",
            "reference_range_lower_bound": 12,
            "reference_range_upper_bound": 16,
            "status": "corrected",
            "updated_at": "2026-01-01T09:00:00Z"
          }
        ],
        "title": "Dr",
        "updated_at": "2026-01-01T09:00:00Z"
      }
    }
  ],
  "remote_file_import_batch":  … }
    "id": "ebc38802-f219-4c7b-8136-8e963a0c69e0",
    "object": "remote_file_import_batch",
    "completed_count": 0,
    "created_at": "2026-01-01T09:00:00Z",
    "failed_count": 0,
    "items":  … ]
       … }
        "id": "57bed2bf-e2e1-463b-8a96-643e3817a8b8",
        "object": "remote_file_import_batch_item",
        "created_resource": "https://api.carebit.co/v1/letters/c3d4e5f6-0718-49ab-acde-f01234567890",
        "created_resource_id": "7e09a8e3-e3c1-4dee-863b-85d56e4329da",
        "created_resource_type": null,
        "error": null,
        "position": 0,
        "status": "failed"
      }
    ],
    "links":  … }
      "self": "https://api.carebit.co/v1/remote_file_import_batches/ebc38802-f219-4c7b-8136-8e963a0c69e0"
    },
    "resource_type": "letter",
    "status": "completed",
    "total_count": 1,
    "updated_at": "2026-01-01T09:00:00Z"
  }
}

202

At least one file is being imported. Poll remote_file_import_batch for each item's status.

itemsarrayrequired
The per-item outcomes in their original request order.
- itemsobject
  The result of one item in a Test Result batch. test_result contains the created TestResult when processing finishes immediately. For an imported file, it is null and remote_file_import_batch_item_id identifies the item being processed.
  - objectanyrequired
    Always test_result_batch_item.
  - positionintegerrequired
    The zero-based position of the item in the request items array.
  - remote_file_import_batch_item_idstring | null · uuidrequired
    The import item identifier for a file that is still being processed. Null when the TestResult was created immediately. Poll the parent remote_file_import_batch for status.
  - statusstringrequired
    The item's processing status. succeeded when the TestResult was created immediately; otherwise the current file import status.
    Allowed values: failed | pending | processing | succeeded
  - test_resultobject | nullrequired
    The created TestResult, or null while an imported file is being processed.
    - automatically_create_resource_permission_for_patientbooleanrequired
      Whether Carebit automatically shares the test result with the patient after processing.
    - created_atstring · date-timerequired
      An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
    - download_urlstring | null · urirequired
      The short-lived signed download URL for the TestResult. Null until the uploaded file passes malware scanning.
    - filenamestring | nullrequired
      The original filename of the test result document, when one was supplied.
    - idstring · uuidrequired
      The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
    - linksobjectrequired
      URLs to related resources.
      - bookingstring | null · urirequired
        The full URL of a related resource.
      - clinicianstring | null · urirequired
        The full URL of a related resource.
      - patientstring | null · urirequired
        The full URL of a related resource.
      - remote_file_import_batchstring · uri
        The full URL of a related resource.
    - notify_patient_of_resource_permissionboolean | nullrequired
      Whether Carebit notifies the patient when the test result is shared with them.
    - objectanyrequired
      Discriminator value emitted at object.
    - remote_file_import_batch_idstring · uuid
      The identifier of the remote file import batch created for the uploaded file. Set on the create response when file_url or file_base64 was submitted.
    - statusstring | nullrequired
      The workflow status of the test result.
      Allowed values: awaiting_proofreading | awaiting_receipt | awaiting_review | awaiting_sending | awaiting_typing | complete | draft | reviewed | null
    - test_result_itemsarrayrequired
      The structured clinical observations included in the test result.
      - 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_abnormalboolean | nullrequired
        Whether the observation falls outside its reference range, when known.
        notesstring | nullrequired
        Additional clinical notes about the observation.
        objectanyrequired
        Discriminator value emitted at object.
        observation_codestring | nullrequired
        The laboratory or clinical code that identifies the observation.
        observation_namestring | nullrequired
        The observation's display name.
        observation_textstring | nullrequired
        The textual observation value, when the result is not represented numerically.
        observation_valuenumber | nullrequired
        The numeric value of the observation, when applicable.
        observation_value_precisionstring | nullrequired
        The precision qualifier for observation_value. < and > denote a bound, and = denotes an exact value.
        Allowed values: < | = | > | null
        observation_value_unitsstring | nullrequired
        The unit used for observation_value.
        observed_atstring | null · date-timerequired
        An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
        reference_range_lower_boundnumber | nullrequired
        The lower bound of the expected reference range, when supplied.
        reference_range_upper_boundnumber | nullrequired
        The upper bound of the expected reference range, when supplied.
        statusstring | nullrequired
        The clinical workflow status of the observation.
        Allowed values: corrected | final | pending | null
        updated_atstring · date-timerequired
        An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
    - titlestring | nullrequired
      The display title of the test result.
    - updated_atstring · date-timerequired
      An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
objectanyrequired
Always test_result_batch.
remote_file_import_batchobject | nullrequired
The file import batch to poll, or null when every TestResult was created immediately.
- completed_countintegerrequired
  The number of items that finished processing successfully.
- created_atstring · date-timerequired
  An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
- failed_countintegerrequired
  The number of items that finished processing with an error.
- idstring · uuidrequired
  The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
- itemsarrayrequired
  The import items in their original request order.
  - itemsobject
    - created_resourcestring | null · urirequired
      The URL of the resource created for a succeeded item. Null unless status is succeeded.
    - created_resource_idstring | null · uuidrequired
      The identifier of the resource created for a succeeded item. Null unless status is succeeded.
    - created_resource_typestring | nullrequired
      The type of resource created for a succeeded item. Null unless status is succeeded.
      Allowed values: null | Attachment | Letter | Note | TestResult
    - errorobject | nullrequired
      The failure details for this item. Null unless the item has failed.
      - codestring | nullrequired
        The machine-readable error code.
      - messagestring | nullrequired
        A message that explains how the item failed.
    - idstring · uuidrequired
      The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
    - objectanyrequired
      Always remote_file_import_batch_item.
    - positionintegerrequired
      The zero-based position of the item in the submitted batch.
    - statusstringrequired
      The current download, validation, and malware-scanning status of the item.
      Allowed values: failed | pending | processing | succeeded
- linksobjectrequired
  URLs to related resources.
  - selfstring · urirequired
    The full URL of a related resource.
- objectanyrequired
  Discriminator value emitted at object.
- resource_typestringrequired
  The type of resource created by every item in the batch.
  Allowed values: letter | note | test_result
- statusstringrequired
  The current download, validation, and malware-scanning status of the batch.
  Allowed values: completed | pending | processing
- total_countintegerrequired
  The total number of items submitted in the batch.
- updated_atstring · date-timerequired
  An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.

Example

{
  "object": "test_result_batch",
  "items":  … ]
     … }
      "object": "test_result_batch_item",
      "position": 0,
      "remote_file_import_batch_item_id": "57bed2bf-e2e1-463b-8a96-643e3817a8b8",
      "status": "failed",
      "test_result":  … }
        "id": "9d4a13e1-0eea-4669-88c4-03316c092c77",
        "object": "test_result",
        "automatically_create_resource_permission_for_patient": true,
        "created_at": "2026-01-01T09:00:00Z",
        "download_url": "https://files.example.invalid/document.pdf?signature=test",
        "filename": "referral-letter.pdf",
        "links":  … }
          "booking": "https://api.carebit.co/v1/bookings/92a3b4c5-d6e7-4f01-8234-56789abcdef0",
          "clinician": "https://api.carebit.co/v1/clinicians/2b3c4d5e-6f70-489a-9bcd-ef0123456789",
          "patient": "https://api.carebit.co/v1/patients/1a2b3c4d-5e6f-4789-8abc-def012345678",
          "remote_file_import_batch": "https://api.carebit.co/v1/remote_file_import_batches/ebc38802-f219-4c7b-8136-8e963a0c69e0"
        },
        "notify_patient_of_resource_permission": true,
        "remote_file_import_batch_id": "ebc38802-f219-4c7b-8136-8e963a0c69e0",
        "status": "awaiting_proofreading",
        "test_result_items":  … ]
           … }
            "id": "7592f451-4733-44f1-8560-1bb6075fa552",
            "object": "test_result_item",
            "created_at": "2026-01-01T09:00:00Z",
            "is_abnormal": false,
            "notes": "Please confirm the appointment by email.",
            "observation_code": "718-7",
            "observation_name": "Haemoglobin",
            "observation_text": "Within the expected range",
            "observation_value": 14.5,
            "observation_value_precision": "<",
            "observation_value_units": "g/dL",
            "observed_at": "2026-01-01T09:00:00Z",
            "reference_range_lower_bound": 12,
            "reference_range_upper_bound": 16,
            "status": "corrected",
            "updated_at": "2026-01-01T09:00:00Z"
          }
        ],
        "title": "Dr",
        "updated_at": "2026-01-01T09:00:00Z"
      }
    }
  ],
  "remote_file_import_batch":  … }
    "id": "ebc38802-f219-4c7b-8136-8e963a0c69e0",
    "object": "remote_file_import_batch",
    "completed_count": 0,
    "created_at": "2026-01-01T09:00:00Z",
    "failed_count": 0,
    "items":  … ]
       … }
        "id": "57bed2bf-e2e1-463b-8a96-643e3817a8b8",
        "object": "remote_file_import_batch_item",
        "created_resource": "https://api.carebit.co/v1/letters/c3d4e5f6-0718-49ab-acde-f01234567890",
        "created_resource_id": "7e09a8e3-e3c1-4dee-863b-85d56e4329da",
        "created_resource_type": null,
        "error": null,
        "position": 0,
        "status": "failed"
      }
    ],
    "links":  … }
      "self": "https://api.carebit.co/v1/remote_file_import_batches/ebc38802-f219-4c7b-8136-8e963a0c69e0"
    },
    "resource_type": "letter",
    "status": "completed",
    "total_count": 1,
    "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, or the project is disabled.

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 POST "https://api.carebit.co/v1/test_result_batches" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "items": [
    {
      "automatically_create_resource_permission_for_patient": true,
      "notify_patient_of_resource_permission": true,
      "patient_id": "00000000-0000-4000-8000-000000000004",
      "status": "complete",
      "test_result_items": [
        {
          "observation_name": "Haemoglobin",
          "observation_value": 14.5,
          "observation_value_units": "g/dL",
          "status": "final"
        }
      ],
      "title": "Full blood count"
    }
  ]
}'

201 response

{
  "object": "test_result_batch",
  "items":  … ]
     … }
      "object": "test_result_batch_item",
      "position": 0,
      "remote_file_import_batch_item_id": "57bed2bf-e2e1-463b-8a96-643e3817a8b8",
      "status": "failed",
      "test_result":  … }
        "id": "9d4a13e1-0eea-4669-88c4-03316c092c77",
        "object": "test_result",
        "automatically_create_resource_permission_for_patient": true,
        "created_at": "2026-01-01T09:00:00Z",
        "download_url": "https://files.example.invalid/document.pdf?signature=test",
        "filename": "referral-letter.pdf",
        "links":  … }
          "booking": "https://api.carebit.co/v1/bookings/92a3b4c5-d6e7-4f01-8234-56789abcdef0",
          "clinician": "https://api.carebit.co/v1/clinicians/2b3c4d5e-6f70-489a-9bcd-ef0123456789",
          "patient": "https://api.carebit.co/v1/patients/1a2b3c4d-5e6f-4789-8abc-def012345678",
          "remote_file_import_batch": "https://api.carebit.co/v1/remote_file_import_batches/ebc38802-f219-4c7b-8136-8e963a0c69e0"
        },
        "notify_patient_of_resource_permission": true,
        "remote_file_import_batch_id": "ebc38802-f219-4c7b-8136-8e963a0c69e0",
        "status": "awaiting_proofreading",
        "test_result_items":  … ]
           … }
            "id": "7592f451-4733-44f1-8560-1bb6075fa552",
            "object": "test_result_item",
            "created_at": "2026-01-01T09:00:00Z",
            "is_abnormal": false,
            "notes": "Please confirm the appointment by email.",
            "observation_code": "718-7",
            "observation_name": "Haemoglobin",
            "observation_text": "Within the expected range",
            "observation_value": 14.5,
            "observation_value_precision": "<",
            "observation_value_units": "g/dL",
            "observed_at": "2026-01-01T09:00:00Z",
            "reference_range_lower_bound": 12,
            "reference_range_upper_bound": 16,
            "status": "corrected",
            "updated_at": "2026-01-01T09:00:00Z"
          }
        ],
        "title": "Dr",
        "updated_at": "2026-01-01T09:00:00Z"
      }
    }
  ],
  "remote_file_import_batch":  … }
    "id": "ebc38802-f219-4c7b-8136-8e963a0c69e0",
    "object": "remote_file_import_batch",
    "completed_count": 0,
    "created_at": "2026-01-01T09:00:00Z",
    "failed_count": 0,
    "items":  … ]
       … }
        "id": "57bed2bf-e2e1-463b-8a96-643e3817a8b8",
        "object": "remote_file_import_batch_item",
        "created_resource": "https://api.carebit.co/v1/letters/c3d4e5f6-0718-49ab-acde-f01234567890",
        "created_resource_id": "7e09a8e3-e3c1-4dee-863b-85d56e4329da",
        "created_resource_type": null,
        "error": null,
        "position": 0,
        "status": "failed"
      }
    ],
    "links":  … }
      "self": "https://api.carebit.co/v1/remote_file_import_batches/ebc38802-f219-4c7b-8136-8e963a0c69e0"
    },
    "resource_type": "letter",
    "status": "completed",
    "total_count": 1,
    "updated_at": "2026-01-01T09:00:00Z"
  }
}

202 response

{
  "object": "test_result_batch",
  "items":  … ]
     … }
      "object": "test_result_batch_item",
      "position": 0,
      "remote_file_import_batch_item_id": "57bed2bf-e2e1-463b-8a96-643e3817a8b8",
      "status": "failed",
      "test_result":  … }
        "id": "9d4a13e1-0eea-4669-88c4-03316c092c77",
        "object": "test_result",
        "automatically_create_resource_permission_for_patient": true,
        "created_at": "2026-01-01T09:00:00Z",
        "download_url": "https://files.example.invalid/document.pdf?signature=test",
        "filename": "referral-letter.pdf",
        "links":  … }
          "booking": "https://api.carebit.co/v1/bookings/92a3b4c5-d6e7-4f01-8234-56789abcdef0",
          "clinician": "https://api.carebit.co/v1/clinicians/2b3c4d5e-6f70-489a-9bcd-ef0123456789",
          "patient": "https://api.carebit.co/v1/patients/1a2b3c4d-5e6f-4789-8abc-def012345678",
          "remote_file_import_batch": "https://api.carebit.co/v1/remote_file_import_batches/ebc38802-f219-4c7b-8136-8e963a0c69e0"
        },
        "notify_patient_of_resource_permission": true,
        "remote_file_import_batch_id": "ebc38802-f219-4c7b-8136-8e963a0c69e0",
        "status": "awaiting_proofreading",
        "test_result_items":  … ]
           … }
            "id": "7592f451-4733-44f1-8560-1bb6075fa552",
            "object": "test_result_item",
            "created_at": "2026-01-01T09:00:00Z",
            "is_abnormal": false,
            "notes": "Please confirm the appointment by email.",
            "observation_code": "718-7",
            "observation_name": "Haemoglobin",
            "observation_text": "Within the expected range",
            "observation_value": 14.5,
            "observation_value_precision": "<",
            "observation_value_units": "g/dL",
            "observed_at": "2026-01-01T09:00:00Z",
            "reference_range_lower_bound": 12,
            "reference_range_upper_bound": 16,
            "status": "corrected",
            "updated_at": "2026-01-01T09:00:00Z"
          }
        ],
        "title": "Dr",
        "updated_at": "2026-01-01T09:00:00Z"
      }
    }
  ],
  "remote_file_import_batch":  … }
    "id": "ebc38802-f219-4c7b-8136-8e963a0c69e0",
    "object": "remote_file_import_batch",
    "completed_count": 0,
    "created_at": "2026-01-01T09:00:00Z",
    "failed_count": 0,
    "items":  … ]
       … }
        "id": "57bed2bf-e2e1-463b-8a96-643e3817a8b8",
        "object": "remote_file_import_batch_item",
        "created_resource": "https://api.carebit.co/v1/letters/c3d4e5f6-0718-49ab-acde-f01234567890",
        "created_resource_id": "7e09a8e3-e3c1-4dee-863b-85d56e4329da",
        "created_resource_type": null,
        "error": null,
        "position": 0,
        "status": "failed"
      }
    ],
    "links":  … }
      "self": "https://api.carebit.co/v1/remote_file_import_batches/ebc38802-f219-4c7b-8136-8e963a0c69e0"
    },
    "resource_type": "letter",
    "status": "completed",
    "total_count": 1,
    "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/test_results

List Test Results

Required API scopes: test_results.read

Parameters

patient_id
query
string
-
booking_id
query
string
-
status
query
string · enum: awaiting_proofreading | awaiting_receipt | awaiting_review | awaiting_sending | awaiting_typing | complete | draft | reviewed
-
created_since
query
string
-
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 TestResult objects.

dataarrayrequired
- itemsobject
  - automatically_create_resource_permission_for_patientbooleanrequired
    Whether Carebit automatically shares the test result with the patient after processing.
  - created_atstring · date-timerequired
    An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
  - download_urlstring | null · urirequired
    The short-lived signed download URL for the TestResult. Null until the uploaded file passes malware scanning.
  - filenamestring | nullrequired
    The original filename of the test result document, when one was supplied.
  - idstring · uuidrequired
    The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - linksobjectrequired
    URLs to related resources.
    - bookingstring | null · urirequired
      The full URL of a related resource.
    - clinicianstring | null · urirequired
      The full URL of a related resource.
    - patientstring | null · urirequired
      The full URL of a related resource.
    - remote_file_import_batchstring · uri
      The full URL of a related resource.
  - notify_patient_of_resource_permissionboolean | nullrequired
    Whether Carebit notifies the patient when the test result is shared with them.
  - objectanyrequired
    Discriminator value emitted at object.
  - remote_file_import_batch_idstring · uuid
    The identifier of the remote file import batch created for the uploaded file. Set on the create response when file_url or file_base64 was submitted.
  - statusstring | nullrequired
    The workflow status of the test result.
    Allowed values: awaiting_proofreading | awaiting_receipt | awaiting_review | awaiting_sending | awaiting_typing | complete | draft | reviewed | null
  - test_result_itemsarrayrequired
    The structured clinical observations included in the test result.
    - 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_abnormalboolean | nullrequired
        Whether the observation falls outside its reference range, when known.
      - notesstring | nullrequired
        Additional clinical notes about the observation.
      - objectanyrequired
        Discriminator value emitted at object.
      - observation_codestring | nullrequired
        The laboratory or clinical code that identifies the observation.
      - observation_namestring | nullrequired
        The observation's display name.
      - observation_textstring | nullrequired
        The textual observation value, when the result is not represented numerically.
      - observation_valuenumber | nullrequired
        The numeric value of the observation, when applicable.
      - observation_value_precisionstring | nullrequired
        The precision qualifier for observation_value. < and > denote a bound, and = denotes an exact value.
        Allowed values: < | = | > | null
      - observation_value_unitsstring | nullrequired
        The unit used for observation_value.
      - observed_atstring | null · date-timerequired
        An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
      - reference_range_lower_boundnumber | nullrequired
        The lower bound of the expected reference range, when supplied.
      - reference_range_upper_boundnumber | nullrequired
        The upper bound of the expected reference range, when supplied.
      - statusstring | nullrequired
        The clinical workflow status of the observation.
        Allowed values: corrected | final | pending | null
      - updated_atstring · date-timerequired
        An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
  - titlestring | nullrequired
    The display title of the test result.
  - 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": "9d4a13e1-0eea-4669-88c4-03316c092c77",
      "object": "test_result",
      "automatically_create_resource_permission_for_patient": true,
      "created_at": "2026-01-01T09:00:00Z",
      "download_url": "https://files.example.invalid/document.pdf?signature=test",
      "filename": "referral-letter.pdf",
      "links":  … }
        "booking": "https://api.carebit.co/v1/bookings/92a3b4c5-d6e7-4f01-8234-56789abcdef0",
        "clinician": "https://api.carebit.co/v1/clinicians/2b3c4d5e-6f70-489a-9bcd-ef0123456789",
        "patient": "https://api.carebit.co/v1/patients/1a2b3c4d-5e6f-4789-8abc-def012345678",
        "remote_file_import_batch": "https://api.carebit.co/v1/remote_file_import_batches/ebc38802-f219-4c7b-8136-8e963a0c69e0"
      },
      "notify_patient_of_resource_permission": true,
      "remote_file_import_batch_id": "ebc38802-f219-4c7b-8136-8e963a0c69e0",
      "status": "awaiting_proofreading",
      "test_result_items":  … ]
         … }
          "id": "7592f451-4733-44f1-8560-1bb6075fa552",
          "object": "test_result_item",
          "created_at": "2026-01-01T09:00:00Z",
          "is_abnormal": false,
          "notes": "Please confirm the appointment by email.",
          "observation_code": "718-7",
          "observation_name": "Haemoglobin",
          "observation_text": "Within the expected range",
          "observation_value": 14.5,
          "observation_value_precision": "<",
          "observation_value_units": "g/dL",
          "observed_at": "2026-01-01T09:00:00Z",
          "reference_range_lower_bound": 12,
          "reference_range_upper_bound": 16,
          "status": "corrected",
          "updated_at": "2026-01-01T09:00:00Z"
        }
      ],
      "title": "Dr",
      "updated_at": "2026-01-01T09:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": "eyJzdGFydF90aW1lIjoiMjAyNi0wMS0wMVQwOTowMDowMFoifQ",
  "url": "/v1/test_results"
}

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

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/test_results" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"

200 response

{
  "object": "list",
  "data":  … ]
     … }
      "id": "9d4a13e1-0eea-4669-88c4-03316c092c77",
      "object": "test_result",
      "automatically_create_resource_permission_for_patient": true,
      "created_at": "2026-01-01T09:00:00Z",
      "download_url": "https://files.example.invalid/document.pdf?signature=test",
      "filename": "referral-letter.pdf",
      "links":  … }
        "booking": "https://api.carebit.co/v1/bookings/92a3b4c5-d6e7-4f01-8234-56789abcdef0",
        "clinician": "https://api.carebit.co/v1/clinicians/2b3c4d5e-6f70-489a-9bcd-ef0123456789",
        "patient": "https://api.carebit.co/v1/patients/1a2b3c4d-5e6f-4789-8abc-def012345678",
        "remote_file_import_batch": "https://api.carebit.co/v1/remote_file_import_batches/ebc38802-f219-4c7b-8136-8e963a0c69e0"
      },
      "notify_patient_of_resource_permission": true,
      "remote_file_import_batch_id": "ebc38802-f219-4c7b-8136-8e963a0c69e0",
      "status": "awaiting_proofreading",
      "test_result_items":  … ]
         … }
          "id": "7592f451-4733-44f1-8560-1bb6075fa552",
          "object": "test_result_item",
          "created_at": "2026-01-01T09:00:00Z",
          "is_abnormal": false,
          "notes": "Please confirm the appointment by email.",
          "observation_code": "718-7",
          "observation_name": "Haemoglobin",
          "observation_text": "Within the expected range",
          "observation_value": 14.5,
          "observation_value_precision": "<",
          "observation_value_units": "g/dL",
          "observed_at": "2026-01-01T09:00:00Z",
          "reference_range_lower_bound": 12,
          "reference_range_upper_bound": 16,
          "status": "corrected",
          "updated_at": "2026-01-01T09:00:00Z"
        }
      ],
      "title": "Dr",
      "updated_at": "2026-01-01T09:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": "eyJzdGFydF90aW1lIjoiMjAyNi0wMS0wMVQwOTowMDowMFoifQ",
  "url": "/v1/test_results"
}

400 response

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

401 response

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

403 response

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

429 response

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

post/v1/test_results

Create a Test Result

Returns the created TestResult with status 201. If you provide file_url or file_base64, the response also identifies a remote file import batch. Poll that batch for the file's import status.

Required API scopes: test_results.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

automatically_create_resource_permission_for_patientbooleanrequired
Whether Carebit should automatically share the test result with the patient after processing.
booking_idstring | null · uuid
The identifier of the booking associated with the test result, or null when it is not linked to a booking.
clinician_idstring | null · uuid
The identifier of the clinician associated with the test result, or null when none is assigned.
descriptionstring | null
A description of the TestResult.
file_base64string | null · byte
The test result bytes encoded as Base64. Provide this with filename instead of file_url. The decoded file can be at most 7 MB.
file_urlstring | null · uri
The public HTTPS URL of a test result document that Carebit should download.
filenamestring | null
The filename to use for the test result. Required with file_base64; defaults to the remote file's filename for URL sources.
notify_patient_of_resource_permissionbooleanrequired
Whether Carebit should notify the patient when the test result is shared with them.
patient_idstring · uuidrequired
The identifier of the patient that the test result belongs to.
statusstringrequired
The workflow status to assign to the test result.
Allowed values: awaiting_review | complete | draft | reviewed
test_result_itemsarray
The structured clinical observations to include in the test result.
- itemsobject
  - is_abnormalboolean | null
    Whether the observation falls outside its reference range, when known.
  - notesstring | null
    Additional clinical notes about the observation.
  - observation_codestring | null
    The laboratory or clinical code that identifies the observation.
  - observation_namestring | null
    The observation's display name.
  - observation_textstring | null
    The textual observation value, when the result is not represented numerically.
  - observation_valuenumber | null
    The numeric value of the observation, when applicable.
  - observation_value_precisionstring | null
    The qualifier that indicates whether observation_value is exact or a boundary.
    Allowed values: < | = | > | null
  - observation_value_unitsstring | null
    The unit used for observation_value.
  - observed_atstring | null · date-time
    An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
  - reference_range_lower_boundnumber | null
    The lower bound of the expected reference range, when supplied.
  - reference_range_upper_boundnumber | null
    The upper bound of the expected reference range, when supplied.
  - statusstring | null
    The clinical workflow status to assign to the observation.
    Allowed values: corrected | final | pending | null
titlestringrequired
The display title of the test result.

Responses

201

The requested TestResult.

automatically_create_resource_permission_for_patientbooleanrequired
Whether Carebit automatically shares the test result with the patient after processing.
created_atstring · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
download_urlstring | null · urirequired
The short-lived signed download URL for the TestResult. Null until the uploaded file passes malware scanning.
filenamestring | nullrequired
The original filename of the test result document, when one was supplied.
idstring · uuidrequired
The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
linksobjectrequired
URLs to related resources.
- bookingstring | null · urirequired
  The full URL of a related resource.
- clinicianstring | null · urirequired
  The full URL of a related resource.
- patientstring | null · urirequired
  The full URL of a related resource.
- remote_file_import_batchstring · uri
  The full URL of a related resource.
notify_patient_of_resource_permissionboolean | nullrequired
Whether Carebit notifies the patient when the test result is shared with them.
objectanyrequired
Discriminator value emitted at object.
remote_file_import_batch_idstring · uuid
The identifier of the remote file import batch created for the uploaded file. Set on the create response when file_url or file_base64 was submitted.
statusstring | nullrequired
The workflow status of the test result.
Allowed values: awaiting_proofreading | awaiting_receipt | awaiting_review | awaiting_sending | awaiting_typing | complete | draft | reviewed | null
test_result_itemsarrayrequired
The structured clinical observations included in the test result.
- 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_abnormalboolean | nullrequired
    Whether the observation falls outside its reference range, when known.
  - notesstring | nullrequired
    Additional clinical notes about the observation.
  - objectanyrequired
    Discriminator value emitted at object.
  - observation_codestring | nullrequired
    The laboratory or clinical code that identifies the observation.
  - observation_namestring | nullrequired
    The observation's display name.
  - observation_textstring | nullrequired
    The textual observation value, when the result is not represented numerically.
  - observation_valuenumber | nullrequired
    The numeric value of the observation, when applicable.
  - observation_value_precisionstring | nullrequired
    The precision qualifier for observation_value. < and > denote a bound, and = denotes an exact value.
    Allowed values: < | = | > | null
  - observation_value_unitsstring | nullrequired
    The unit used for observation_value.
  - observed_atstring | null · date-timerequired
    An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
  - reference_range_lower_boundnumber | nullrequired
    The lower bound of the expected reference range, when supplied.
  - reference_range_upper_boundnumber | nullrequired
    The upper bound of the expected reference range, when supplied.
  - statusstring | nullrequired
    The clinical workflow status of the observation.
    Allowed values: corrected | final | pending | null
  - updated_atstring · date-timerequired
    An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
titlestring | nullrequired
The display title of the test result.
updated_atstring · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.

Example

{
  "id": "9d4a13e1-0eea-4669-88c4-03316c092c77",
  "object": "test_result",
  "automatically_create_resource_permission_for_patient": true,
  "created_at": "2026-01-01T09:00:00Z",
  "download_url": "https://files.example.invalid/document.pdf?signature=test",
  "filename": "referral-letter.pdf",
  "links":  … }
    "booking": "https://api.carebit.co/v1/bookings/92a3b4c5-d6e7-4f01-8234-56789abcdef0",
    "clinician": "https://api.carebit.co/v1/clinicians/2b3c4d5e-6f70-489a-9bcd-ef0123456789",
    "patient": "https://api.carebit.co/v1/patients/1a2b3c4d-5e6f-4789-8abc-def012345678",
    "remote_file_import_batch": "https://api.carebit.co/v1/remote_file_import_batches/ebc38802-f219-4c7b-8136-8e963a0c69e0"
  },
  "notify_patient_of_resource_permission": true,
  "remote_file_import_batch_id": "ebc38802-f219-4c7b-8136-8e963a0c69e0",
  "status": "awaiting_proofreading",
  "test_result_items":  … ]
     … }
      "id": "7592f451-4733-44f1-8560-1bb6075fa552",
      "object": "test_result_item",
      "created_at": "2026-01-01T09:00:00Z",
      "is_abnormal": false,
      "notes": "Please confirm the appointment by email.",
      "observation_code": "718-7",
      "observation_name": "Haemoglobin",
      "observation_text": "Within the expected range",
      "observation_value": 14.5,
      "observation_value_precision": "<",
      "observation_value_units": "g/dL",
      "observed_at": "2026-01-01T09:00:00Z",
      "reference_range_lower_bound": 12,
      "reference_range_upper_bound": 16,
      "status": "corrected",
      "updated_at": "2026-01-01T09:00:00Z"
    }
  ],
  "title": "Dr",
  "updated_at": "2026-01-01T09:00:00Z"
}

400

The request contains more test result items than the per-request limit permits.

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

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 POST "https://api.carebit.co/v1/test_results" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "automatically_create_resource_permission_for_patient": true,
  "notify_patient_of_resource_permission": true,
  "patient_id": "00000000-0000-4000-8000-000000000004",
  "status": "complete",
  "test_result_items": [
    {
      "is_abnormal": false,
      "observation_code": "718-7",
      "observation_name": "Haemoglobin",
      "observation_value": 14.5,
      "observation_value_units": "g/dL",
      "reference_range_lower_bound": 12,
      "reference_range_upper_bound": 16,
      "status": "final"
    }
  ],
  "title": "Full blood count"
}'

201 response

{
  "id": "9d4a13e1-0eea-4669-88c4-03316c092c77",
  "object": "test_result",
  "automatically_create_resource_permission_for_patient": true,
  "created_at": "2026-01-01T09:00:00Z",
  "download_url": "https://files.example.invalid/document.pdf?signature=test",
  "filename": "referral-letter.pdf",
  "links":  … }
    "booking": "https://api.carebit.co/v1/bookings/92a3b4c5-d6e7-4f01-8234-56789abcdef0",
    "clinician": "https://api.carebit.co/v1/clinicians/2b3c4d5e-6f70-489a-9bcd-ef0123456789",
    "patient": "https://api.carebit.co/v1/patients/1a2b3c4d-5e6f-4789-8abc-def012345678",
    "remote_file_import_batch": "https://api.carebit.co/v1/remote_file_import_batches/ebc38802-f219-4c7b-8136-8e963a0c69e0"
  },
  "notify_patient_of_resource_permission": true,
  "remote_file_import_batch_id": "ebc38802-f219-4c7b-8136-8e963a0c69e0",
  "status": "awaiting_proofreading",
  "test_result_items":  … ]
     … }
      "id": "7592f451-4733-44f1-8560-1bb6075fa552",
      "object": "test_result_item",
      "created_at": "2026-01-01T09:00:00Z",
      "is_abnormal": false,
      "notes": "Please confirm the appointment by email.",
      "observation_code": "718-7",
      "observation_name": "Haemoglobin",
      "observation_text": "Within the expected range",
      "observation_value": 14.5,
      "observation_value_precision": "<",
      "observation_value_units": "g/dL",
      "observed_at": "2026-01-01T09:00:00Z",
      "reference_range_lower_bound": 12,
      "reference_range_upper_bound": 16,
      "status": "corrected",
      "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/test_results/:id

Get a Test Result

Required API scopes: test_results.read

Parameters

id
path · required
string
-

Responses

200

The requested TestResult.

automatically_create_resource_permission_for_patientbooleanrequired
Whether Carebit automatically shares the test result with the patient after processing.
created_atstring · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
download_urlstring | null · urirequired
The short-lived signed download URL for the TestResult. Null until the uploaded file passes malware scanning.
filenamestring | nullrequired
The original filename of the test result document, when one was supplied.
idstring · uuidrequired
The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
linksobjectrequired
URLs to related resources.
- bookingstring | null · urirequired
  The full URL of a related resource.
- clinicianstring | null · urirequired
  The full URL of a related resource.
- patientstring | null · urirequired
  The full URL of a related resource.
- remote_file_import_batchstring · uri
  The full URL of a related resource.
notify_patient_of_resource_permissionboolean | nullrequired
Whether Carebit notifies the patient when the test result is shared with them.
objectanyrequired
Discriminator value emitted at object.
remote_file_import_batch_idstring · uuid
The identifier of the remote file import batch created for the uploaded file. Set on the create response when file_url or file_base64 was submitted.
statusstring | nullrequired
The workflow status of the test result.
Allowed values: awaiting_proofreading | awaiting_receipt | awaiting_review | awaiting_sending | awaiting_typing | complete | draft | reviewed | null
test_result_itemsarrayrequired
The structured clinical observations included in the test result.
- 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_abnormalboolean | nullrequired
    Whether the observation falls outside its reference range, when known.
  - notesstring | nullrequired
    Additional clinical notes about the observation.
  - objectanyrequired
    Discriminator value emitted at object.
  - observation_codestring | nullrequired
    The laboratory or clinical code that identifies the observation.
  - observation_namestring | nullrequired
    The observation's display name.
  - observation_textstring | nullrequired
    The textual observation value, when the result is not represented numerically.
  - observation_valuenumber | nullrequired
    The numeric value of the observation, when applicable.
  - observation_value_precisionstring | nullrequired
    The precision qualifier for observation_value. < and > denote a bound, and = denotes an exact value.
    Allowed values: < | = | > | null
  - observation_value_unitsstring | nullrequired
    The unit used for observation_value.
  - observed_atstring | null · date-timerequired
    An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
  - reference_range_lower_boundnumber | nullrequired
    The lower bound of the expected reference range, when supplied.
  - reference_range_upper_boundnumber | nullrequired
    The upper bound of the expected reference range, when supplied.
  - statusstring | nullrequired
    The clinical workflow status of the observation.
    Allowed values: corrected | final | pending | null
  - updated_atstring · date-timerequired
    An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
titlestring | nullrequired
The display title of the test result.
updated_atstring · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.

Example

{
  "id": "9d4a13e1-0eea-4669-88c4-03316c092c77",
  "object": "test_result",
  "automatically_create_resource_permission_for_patient": true,
  "created_at": "2026-01-01T09:00:00Z",
  "download_url": "https://files.example.invalid/document.pdf?signature=test",
  "filename": "referral-letter.pdf",
  "links":  … }
    "booking": "https://api.carebit.co/v1/bookings/92a3b4c5-d6e7-4f01-8234-56789abcdef0",
    "clinician": "https://api.carebit.co/v1/clinicians/2b3c4d5e-6f70-489a-9bcd-ef0123456789",
    "patient": "https://api.carebit.co/v1/patients/1a2b3c4d-5e6f-4789-8abc-def012345678",
    "remote_file_import_batch": "https://api.carebit.co/v1/remote_file_import_batches/ebc38802-f219-4c7b-8136-8e963a0c69e0"
  },
  "notify_patient_of_resource_permission": true,
  "remote_file_import_batch_id": "ebc38802-f219-4c7b-8136-8e963a0c69e0",
  "status": "awaiting_proofreading",
  "test_result_items":  … ]
     … }
      "id": "7592f451-4733-44f1-8560-1bb6075fa552",
      "object": "test_result_item",
      "created_at": "2026-01-01T09:00:00Z",
      "is_abnormal": false,
      "notes": "Please confirm the appointment by email.",
      "observation_code": "718-7",
      "observation_name": "Haemoglobin",
      "observation_text": "Within the expected range",
      "observation_value": 14.5,
      "observation_value_precision": "<",
      "observation_value_units": "g/dL",
      "observed_at": "2026-01-01T09:00:00Z",
      "reference_range_lower_bound": 12,
      "reference_range_upper_bound": 16,
      "status": "corrected",
      "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, or the project is disabled.

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

200 response

{
  "id": "9d4a13e1-0eea-4669-88c4-03316c092c77",
  "object": "test_result",
  "automatically_create_resource_permission_for_patient": true,
  "created_at": "2026-01-01T09:00:00Z",
  "download_url": "https://files.example.invalid/document.pdf?signature=test",
  "filename": "referral-letter.pdf",
  "links":  … }
    "booking": "https://api.carebit.co/v1/bookings/92a3b4c5-d6e7-4f01-8234-56789abcdef0",
    "clinician": "https://api.carebit.co/v1/clinicians/2b3c4d5e-6f70-489a-9bcd-ef0123456789",
    "patient": "https://api.carebit.co/v1/patients/1a2b3c4d-5e6f-4789-8abc-def012345678",
    "remote_file_import_batch": "https://api.carebit.co/v1/remote_file_import_batches/ebc38802-f219-4c7b-8136-8e963a0c69e0"
  },
  "notify_patient_of_resource_permission": true,
  "remote_file_import_batch_id": "ebc38802-f219-4c7b-8136-8e963a0c69e0",
  "status": "awaiting_proofreading",
  "test_result_items":  … ]
     … }
      "id": "7592f451-4733-44f1-8560-1bb6075fa552",
      "object": "test_result_item",
      "created_at": "2026-01-01T09:00:00Z",
      "is_abnormal": false,
      "notes": "Please confirm the appointment by email.",
      "observation_code": "718-7",
      "observation_name": "Haemoglobin",
      "observation_text": "Within the expected range",
      "observation_value": 14.5,
      "observation_value_precision": "<",
      "observation_value_units": "g/dL",
      "observed_at": "2026-01-01T09:00:00Z",
      "reference_range_lower_bound": 12,
      "reference_range_upper_bound": 16,
      "status": "corrected",
      "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"
  }
}

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