Carebit API

Photos

Photos stored on a Patient's record.

Required API scopes: photos.createphotos.readphotos.update

Endpoints

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

get/v1/photosList Photosphotos.read
post/v1/photosCreate a Photo with a filephotos.create
get/v1/photos/:idGet a Photophotos.read
patch/v1/photos/:idUpdate a Photophotos.update

get/v1/photos

List Photos

Required API scopes: photos.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 Photo objects.

dataarrayrequired
- itemsobject
  - assigned_staff_memberobject | nullrequired
    The StaffMember assigned to the photo, or null when nobody is assigned.
    - created_atstring · date-timerequired
      An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
    - emailstring · emailrequired
      The sign-in email address of the staff member.
    - first_namestringrequired
      The first name of the staff member.
    - idstring · uuidrequired
      The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
    - last_namestringrequired
      The last name of the staff member.
    - linksobjectrequired
      URLs to related resources.
      - selfstring · urirequired
        URL to retrieve this StaffMember.
    - namestringrequired
      The display name of the staff member, including title.
    - objectanyrequired
      Discriminator value emitted at object.
    - titlestringrequired
      The professional or personal title of the staff member, such as Dr.
    - updated_atstring · date-timerequired
      An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
  - automatically_create_resource_permission_for_patientbooleanrequired
    Whether Carebit automatically shares the photo 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 Photo. Null until the file passes malware scanning and the Photo is complete or reviewed.
  - filenamestring | nullrequired
    The original filename of the photo.
  - idstring · uuidrequired
    The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - linksobjectrequired
    URLs to related resources.
    - assigned_staff_memberstring | null · urirequired
      The full URL of a related resource.
    - 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 photo 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 or update response when a file was submitted.
  - sent_atstring | null · date-timerequired
    When the photo was sent. Null when it has not been sent.
  - statusstring | nullrequired
    The Photo's workflow status. An owned Photo is readable while it is awaiting review.
    Allowed values: awaiting_proofreading | awaiting_receipt | awaiting_review | awaiting_sending | awaiting_typing | complete | draft | reviewed | null
  - titlestring | nullrequired
    The display title of the photo.
  - 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": "24097db0-9916-44a3-8959-93b7a787c6da",
      "object": "photo",
      "assigned_staff_member":  … }
        "id": "af02fa53-0af3-48ab-83b5-82488923e84f",
        "object": "staff_member",
        "created_at": "2026-01-01T09:00:00Z",
        "email": "alex.morgan@example.com",
        "first_name": "Alex",
        "last_name": "Morgan",
        "links":  … }
          "self": "https://api.carebit.co/v1/staff_members/af02fa53-0af3-48ab-83b5-82488923e84f"
        },
        "name": "Initial consultation",
        "title": "Dr",
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "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":  … }
        "assigned_staff_member": "https://api.carebit.co/v1/assigned_staff_members/e6ff1712-cb57-449f-8960-eb185db9a9a8",
        "booking": "https://api.carebit.co/v1/bookings/00000000-0000-4000-8000-000000000001",
        "clinician": "https://api.carebit.co/v1/clinicians/00000000-0000-4000-8000-000000000002",
        "patient": "https://api.carebit.co/v1/patients/00000000-0000-4000-8000-000000000004",
        "remote_file_import_batch": "https://api.carebit.co/v1/remote_file_import_batches/00000000-0000-4000-8000-00000000000a"
      },
      "notify_patient_of_resource_permission": true,
      "remote_file_import_batch_id": "00000000-0000-4000-8000-00000000000a",
      "sent_at": "2026-01-01T09:00:00Z",
      "status": "awaiting_proofreading",
      "title": "Dr",
      "updated_at": "2026-01-01T09:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": "eyJzdGFydF90aW1lIjoiMjAyNi0wMS0wMVQwOTowMDowMFoifQ",
  "url": "/v1/photos"
}

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

200 response

{
  "object": "list",
  "data":  … ]
     … }
      "id": "24097db0-9916-44a3-8959-93b7a787c6da",
      "object": "photo",
      "assigned_staff_member":  … }
        "id": "af02fa53-0af3-48ab-83b5-82488923e84f",
        "object": "staff_member",
        "created_at": "2026-01-01T09:00:00Z",
        "email": "alex.morgan@example.com",
        "first_name": "Alex",
        "last_name": "Morgan",
        "links":  … }
          "self": "https://api.carebit.co/v1/staff_members/af02fa53-0af3-48ab-83b5-82488923e84f"
        },
        "name": "Initial consultation",
        "title": "Dr",
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "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":  … }
        "assigned_staff_member": "https://api.carebit.co/v1/assigned_staff_members/e6ff1712-cb57-449f-8960-eb185db9a9a8",
        "booking": "https://api.carebit.co/v1/bookings/00000000-0000-4000-8000-000000000001",
        "clinician": "https://api.carebit.co/v1/clinicians/00000000-0000-4000-8000-000000000002",
        "patient": "https://api.carebit.co/v1/patients/00000000-0000-4000-8000-000000000004",
        "remote_file_import_batch": "https://api.carebit.co/v1/remote_file_import_batches/00000000-0000-4000-8000-00000000000a"
      },
      "notify_patient_of_resource_permission": true,
      "remote_file_import_batch_id": "00000000-0000-4000-8000-00000000000a",
      "sent_at": "2026-01-01T09:00:00Z",
      "status": "awaiting_proofreading",
      "title": "Dr",
      "updated_at": "2026-01-01T09:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": "eyJzdGFydF90aW1lIjoiMjAyNi0wMS0wMVQwOTowMDowMFoifQ",
  "url": "/v1/photos"
}

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/photos

Create a Photo with a file

Creates the Photo immediately, then imports its file in the background. Accepted formats are JPEG, PNG, PDF, and DICOM (.dcm). Convert TIFF or BMP files before uploading. Provide the file as a public HTTPS file_url or Base64-encoded file_base64. Poll /v1/remote_file_import_batches/:remote_file_import_batch_id for the import status.

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

assigned_staff_member_idstring | null · uuid
The identifier of the StaffMember assigned to the photo. Send null to clear the assignment. Omit the field to leave the current assignment unchanged.
automatically_create_resource_permission_for_patientbooleanrequired
Whether Carebit should automatically share the photo with the patient after processing.
booking_idstring | null · uuid
The identifier of the booking associated with the photo, or null when it is not linked to a booking.
clinician_idstring | null · uuid
The identifier of the clinician associated with the photo, or null when none is assigned.
created_atstring · date-time
When the photo was created. This is the Date created field in Carebit. Omit it to use the current time. On update, omit it to keep the stored time.
descriptionstring | null
A description of the photo.
file_base64string · byte
The photo bytes encoded as Base64. Provide this with filename instead of file_url. The decoded file can be at most 7 MB.
file_urlstring · uri
The public HTTPS URL that Carebit can fetch.
filenamestring | null
The filename to use for the photo. 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 photo is shared with them.
patient_idstring · uuidrequired
The identifier of the patient that the photo belongs to.
sent_atstring | null · date-time
When the photo was sent. Send null to clear the sent time. Omit the field to leave the current value unchanged. A timestamp stores that time and marks the photo complete.
statusstringrequired
The workflow status to assign to the photo.
Allowed values: awaiting_receipt | awaiting_review | awaiting_sending | complete | draft | reviewed
titlestringrequired
The display title of the photo.

Responses

201

The requested Photo.

assigned_staff_memberobject | nullrequired
The StaffMember assigned to the photo, or null when nobody is assigned.
- created_atstring · date-timerequired
  An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
- emailstring · emailrequired
  The sign-in email address of the staff member.
- first_namestringrequired
  The first name of the staff member.
- idstring · uuidrequired
  The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
- last_namestringrequired
  The last name of the staff member.
- linksobjectrequired
  URLs to related resources.
  - selfstring · urirequired
    URL to retrieve this StaffMember.
- namestringrequired
  The display name of the staff member, including title.
- objectanyrequired
  Discriminator value emitted at object.
- titlestringrequired
  The professional or personal title of the staff member, such as Dr.
- updated_atstring · date-timerequired
  An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
automatically_create_resource_permission_for_patientbooleanrequired
Whether Carebit automatically shares the photo 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 Photo. Null until the file passes malware scanning and the Photo is complete or reviewed.
filenamestring | nullrequired
The original filename of the photo.
idstring · uuidrequired
The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
linksobjectrequired
URLs to related resources.
- assigned_staff_memberstring | null · urirequired
  The full URL of a related resource.
- 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 photo 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 or update response when a file was submitted.
sent_atstring | null · date-timerequired
When the photo was sent. Null when it has not been sent.
statusstring | nullrequired
The Photo's workflow status. An owned Photo is readable while it is awaiting review.
Allowed values: awaiting_proofreading | awaiting_receipt | awaiting_review | awaiting_sending | awaiting_typing | complete | draft | reviewed | null
titlestring | nullrequired
The display title of the photo.
updated_atstring · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.

Example

{
  "id": "24097db0-9916-44a3-8959-93b7a787c6da",
  "object": "photo",
  "assigned_staff_member":  … }
    "id": "af02fa53-0af3-48ab-83b5-82488923e84f",
    "object": "staff_member",
    "created_at": "2026-01-01T09:00:00Z",
    "email": "alex.morgan@example.com",
    "first_name": "Alex",
    "last_name": "Morgan",
    "links":  … }
      "self": "https://api.carebit.co/v1/staff_members/af02fa53-0af3-48ab-83b5-82488923e84f"
    },
    "name": "Initial consultation",
    "title": "Dr",
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "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":  … }
    "assigned_staff_member": "https://api.carebit.co/v1/assigned_staff_members/e6ff1712-cb57-449f-8960-eb185db9a9a8",
    "booking": "https://api.carebit.co/v1/bookings/00000000-0000-4000-8000-000000000001",
    "clinician": "https://api.carebit.co/v1/clinicians/00000000-0000-4000-8000-000000000002",
    "patient": "https://api.carebit.co/v1/patients/00000000-0000-4000-8000-000000000004",
    "remote_file_import_batch": "https://api.carebit.co/v1/remote_file_import_batches/00000000-0000-4000-8000-00000000000a"
  },
  "notify_patient_of_resource_permission": true,
  "remote_file_import_batch_id": "00000000-0000-4000-8000-00000000000a",
  "sent_at": "2026-01-01T09:00:00Z",
  "status": "awaiting_proofreading",
  "title": "Dr",
  "updated_at": "2026-01-01T09:00:00Z"
}

400

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

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

Example

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

401

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

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

Example

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

403

The access token lacks the required scope, 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/photos" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "automatically_create_resource_permission_for_patient": false,
  "file_url": "https://storage.example.invalid/photos/photo.jpg",
  "filename": "photo.jpg",
  "notify_patient_of_resource_permission": false,
  "patient_id": "00000000-0000-4000-8000-000000000004",
  "status": "awaiting_review",
  "title": "Clinical photograph"
}'

201 response

{
  "id": "24097db0-9916-44a3-8959-93b7a787c6da",
  "object": "photo",
  "assigned_staff_member":  … }
    "id": "af02fa53-0af3-48ab-83b5-82488923e84f",
    "object": "staff_member",
    "created_at": "2026-01-01T09:00:00Z",
    "email": "alex.morgan@example.com",
    "first_name": "Alex",
    "last_name": "Morgan",
    "links":  … }
      "self": "https://api.carebit.co/v1/staff_members/af02fa53-0af3-48ab-83b5-82488923e84f"
    },
    "name": "Initial consultation",
    "title": "Dr",
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "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":  … }
    "assigned_staff_member": "https://api.carebit.co/v1/assigned_staff_members/e6ff1712-cb57-449f-8960-eb185db9a9a8",
    "booking": "https://api.carebit.co/v1/bookings/00000000-0000-4000-8000-000000000001",
    "clinician": "https://api.carebit.co/v1/clinicians/00000000-0000-4000-8000-000000000002",
    "patient": "https://api.carebit.co/v1/patients/00000000-0000-4000-8000-000000000004",
    "remote_file_import_batch": "https://api.carebit.co/v1/remote_file_import_batches/00000000-0000-4000-8000-00000000000a"
  },
  "notify_patient_of_resource_permission": true,
  "remote_file_import_batch_id": "00000000-0000-4000-8000-00000000000a",
  "sent_at": "2026-01-01T09:00:00Z",
  "status": "awaiting_proofreading",
  "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/photos/:id

Get a Photo

Required API scopes: photos.read

Parameters

id
path · required
string
-

Responses

200

The requested Photo.

assigned_staff_memberobject | nullrequired
The StaffMember assigned to the photo, or null when nobody is assigned.
- created_atstring · date-timerequired
  An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
- emailstring · emailrequired
  The sign-in email address of the staff member.
- first_namestringrequired
  The first name of the staff member.
- idstring · uuidrequired
  The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
- last_namestringrequired
  The last name of the staff member.
- linksobjectrequired
  URLs to related resources.
  - selfstring · urirequired
    URL to retrieve this StaffMember.
- namestringrequired
  The display name of the staff member, including title.
- objectanyrequired
  Discriminator value emitted at object.
- titlestringrequired
  The professional or personal title of the staff member, such as Dr.
- updated_atstring · date-timerequired
  An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
automatically_create_resource_permission_for_patientbooleanrequired
Whether Carebit automatically shares the photo 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 Photo. Null until the file passes malware scanning and the Photo is complete or reviewed.
filenamestring | nullrequired
The original filename of the photo.
idstring · uuidrequired
The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
linksobjectrequired
URLs to related resources.
- assigned_staff_memberstring | null · urirequired
  The full URL of a related resource.
- 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 photo 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 or update response when a file was submitted.
sent_atstring | null · date-timerequired
When the photo was sent. Null when it has not been sent.
statusstring | nullrequired
The Photo's workflow status. An owned Photo is readable while it is awaiting review.
Allowed values: awaiting_proofreading | awaiting_receipt | awaiting_review | awaiting_sending | awaiting_typing | complete | draft | reviewed | null
titlestring | nullrequired
The display title of the photo.
updated_atstring · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.

Example

{
  "id": "24097db0-9916-44a3-8959-93b7a787c6da",
  "object": "photo",
  "assigned_staff_member":  … }
    "id": "af02fa53-0af3-48ab-83b5-82488923e84f",
    "object": "staff_member",
    "created_at": "2026-01-01T09:00:00Z",
    "email": "alex.morgan@example.com",
    "first_name": "Alex",
    "last_name": "Morgan",
    "links":  … }
      "self": "https://api.carebit.co/v1/staff_members/af02fa53-0af3-48ab-83b5-82488923e84f"
    },
    "name": "Initial consultation",
    "title": "Dr",
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "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":  … }
    "assigned_staff_member": "https://api.carebit.co/v1/assigned_staff_members/e6ff1712-cb57-449f-8960-eb185db9a9a8",
    "booking": "https://api.carebit.co/v1/bookings/00000000-0000-4000-8000-000000000001",
    "clinician": "https://api.carebit.co/v1/clinicians/00000000-0000-4000-8000-000000000002",
    "patient": "https://api.carebit.co/v1/patients/00000000-0000-4000-8000-000000000004",
    "remote_file_import_batch": "https://api.carebit.co/v1/remote_file_import_batches/00000000-0000-4000-8000-00000000000a"
  },
  "notify_patient_of_resource_permission": true,
  "remote_file_import_batch_id": "00000000-0000-4000-8000-00000000000a",
  "sent_at": "2026-01-01T09:00:00Z",
  "status": "awaiting_proofreading",
  "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/photos/24097db0-9916-44a3-8959-93b7a787c6da" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"

200 response

{
  "id": "24097db0-9916-44a3-8959-93b7a787c6da",
  "object": "photo",
  "assigned_staff_member":  … }
    "id": "af02fa53-0af3-48ab-83b5-82488923e84f",
    "object": "staff_member",
    "created_at": "2026-01-01T09:00:00Z",
    "email": "alex.morgan@example.com",
    "first_name": "Alex",
    "last_name": "Morgan",
    "links":  … }
      "self": "https://api.carebit.co/v1/staff_members/af02fa53-0af3-48ab-83b5-82488923e84f"
    },
    "name": "Initial consultation",
    "title": "Dr",
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "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":  … }
    "assigned_staff_member": "https://api.carebit.co/v1/assigned_staff_members/e6ff1712-cb57-449f-8960-eb185db9a9a8",
    "booking": "https://api.carebit.co/v1/bookings/00000000-0000-4000-8000-000000000001",
    "clinician": "https://api.carebit.co/v1/clinicians/00000000-0000-4000-8000-000000000002",
    "patient": "https://api.carebit.co/v1/patients/00000000-0000-4000-8000-000000000004",
    "remote_file_import_batch": "https://api.carebit.co/v1/remote_file_import_batches/00000000-0000-4000-8000-00000000000a"
  },
  "notify_patient_of_resource_permission": true,
  "remote_file_import_batch_id": "00000000-0000-4000-8000-00000000000a",
  "sent_at": "2026-01-01T09:00:00Z",
  "status": "awaiting_proofreading",
  "title": "Dr",
  "updated_at": "2026-01-01T09:00:00Z"
}

401 response

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

403 response

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

404 response

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

429 response

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

patch/v1/photos/:id

Update a Photo

Updates a Photo owned by the Organization, including one that is awaiting review. Provide file_url or file_base64 only when replacing the file. Accepted replacement formats are JPEG, PNG, PDF, and DICOM (.dcm). Convert TIFF or BMP files before uploading. A failed replacement keeps the Photo and its previous file.

Required API scopes: photos.update

Parameters

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

Request body

application/json

assigned_staff_member_idstring | null · uuid
The identifier of the StaffMember assigned to the photo. Send null to clear the assignment. Omit the field to leave the current assignment unchanged.
automatically_create_resource_permission_for_patientboolean
Whether Carebit should automatically share the photo with the patient after processing.
booking_idstring | null · uuid
The identifier of the booking associated with the photo, or null when it is not linked to a booking.
clinician_idstring | null · uuid
The identifier of the clinician associated with the photo, or null when none is assigned.
created_atstring · date-time
When the photo was created. This is the Date created field in Carebit. Omit it to use the current time. On update, omit it to keep the stored time.
descriptionstring | null
A description of the photo.
file_base64string | null · byte
The photo 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 that Carebit can fetch.
filenamestring | null
The filename to use for the photo. 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 photo is shared with them.
sent_atstring | null · date-time
When the photo was sent. Send null to clear the sent time. Omit the field to leave the current value unchanged. A timestamp stores that time and marks the photo complete.
statusstring
The workflow status to assign to the photo.
Allowed values: awaiting_receipt | awaiting_review | awaiting_sending | complete | draft | reviewed
titlestring
The display title of the photo.

Responses

200

The requested Photo.

assigned_staff_memberobject | nullrequired
The StaffMember assigned to the photo, or null when nobody is assigned.
- created_atstring · date-timerequired
  An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
- emailstring · emailrequired
  The sign-in email address of the staff member.
- first_namestringrequired
  The first name of the staff member.
- idstring · uuidrequired
  The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
- last_namestringrequired
  The last name of the staff member.
- linksobjectrequired
  URLs to related resources.
  - selfstring · urirequired
    URL to retrieve this StaffMember.
- namestringrequired
  The display name of the staff member, including title.
- objectanyrequired
  Discriminator value emitted at object.
- titlestringrequired
  The professional or personal title of the staff member, such as Dr.
- updated_atstring · date-timerequired
  An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
automatically_create_resource_permission_for_patientbooleanrequired
Whether Carebit automatically shares the photo 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 Photo. Null until the file passes malware scanning and the Photo is complete or reviewed.
filenamestring | nullrequired
The original filename of the photo.
idstring · uuidrequired
The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
linksobjectrequired
URLs to related resources.
- assigned_staff_memberstring | null · urirequired
  The full URL of a related resource.
- 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 photo 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 or update response when a file was submitted.
sent_atstring | null · date-timerequired
When the photo was sent. Null when it has not been sent.
statusstring | nullrequired
The Photo's workflow status. An owned Photo is readable while it is awaiting review.
Allowed values: awaiting_proofreading | awaiting_receipt | awaiting_review | awaiting_sending | awaiting_typing | complete | draft | reviewed | null
titlestring | nullrequired
The display title of the photo.
updated_atstring · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.

Example

{
  "id": "24097db0-9916-44a3-8959-93b7a787c6da",
  "object": "photo",
  "assigned_staff_member":  … }
    "id": "af02fa53-0af3-48ab-83b5-82488923e84f",
    "object": "staff_member",
    "created_at": "2026-01-01T09:00:00Z",
    "email": "alex.morgan@example.com",
    "first_name": "Alex",
    "last_name": "Morgan",
    "links":  … }
      "self": "https://api.carebit.co/v1/staff_members/af02fa53-0af3-48ab-83b5-82488923e84f"
    },
    "name": "Initial consultation",
    "title": "Dr",
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "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":  … }
    "assigned_staff_member": "https://api.carebit.co/v1/assigned_staff_members/e6ff1712-cb57-449f-8960-eb185db9a9a8",
    "booking": "https://api.carebit.co/v1/bookings/00000000-0000-4000-8000-000000000001",
    "clinician": "https://api.carebit.co/v1/clinicians/00000000-0000-4000-8000-000000000002",
    "patient": "https://api.carebit.co/v1/patients/00000000-0000-4000-8000-000000000004",
    "remote_file_import_batch": "https://api.carebit.co/v1/remote_file_import_batches/00000000-0000-4000-8000-00000000000a"
  },
  "notify_patient_of_resource_permission": true,
  "remote_file_import_batch_id": "00000000-0000-4000-8000-00000000000a",
  "sent_at": "2026-01-01T09:00:00Z",
  "status": "awaiting_proofreading",
  "title": "Dr",
  "updated_at": "2026-01-01T09:00:00Z"
}

400

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

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

Example

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

401

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

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

Example

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

403

The access token lacks the required scope, 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 PATCH "https://api.carebit.co/v1/photos/24097db0-9916-44a3-8959-93b7a787c6da" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "complete",
  "title": "Clinical photograph"
}'

200 response

{
  "id": "24097db0-9916-44a3-8959-93b7a787c6da",
  "object": "photo",
  "assigned_staff_member":  … }
    "id": "af02fa53-0af3-48ab-83b5-82488923e84f",
    "object": "staff_member",
    "created_at": "2026-01-01T09:00:00Z",
    "email": "alex.morgan@example.com",
    "first_name": "Alex",
    "last_name": "Morgan",
    "links":  … }
      "self": "https://api.carebit.co/v1/staff_members/af02fa53-0af3-48ab-83b5-82488923e84f"
    },
    "name": "Initial consultation",
    "title": "Dr",
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "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":  … }
    "assigned_staff_member": "https://api.carebit.co/v1/assigned_staff_members/e6ff1712-cb57-449f-8960-eb185db9a9a8",
    "booking": "https://api.carebit.co/v1/bookings/00000000-0000-4000-8000-000000000001",
    "clinician": "https://api.carebit.co/v1/clinicians/00000000-0000-4000-8000-000000000002",
    "patient": "https://api.carebit.co/v1/patients/00000000-0000-4000-8000-000000000004",
    "remote_file_import_batch": "https://api.carebit.co/v1/remote_file_import_batches/00000000-0000-4000-8000-00000000000a"
  },
  "notify_patient_of_resource_permission": true,
  "remote_file_import_batch_id": "00000000-0000-4000-8000-00000000000a",
  "sent_at": "2026-01-01T09:00:00Z",
  "status": "awaiting_proofreading",
  "title": "Dr",
  "updated_at": "2026-01-01T09:00:00Z"
}

400 response

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

401 response

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

403 response

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

404 response

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

409 response

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

422 response

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

429 response

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

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