post/v1/quotes

Create a Quote

Creates a draft Quote. Supply patient_id for a Patient Quote, or omit it and supply alternative_payor_id to quote another organisation. Supply booking_ids to generate line items from those Bookings, or supply line_items to quote custom charges. Bookings require a Patient. Sending, accepting, and converting remain in the Carebit staff and Patient Portal interfaces.

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

alternative_payor_idstring | null · uuid
Required when payor_type is alternative_payor, and when patient_id is omitted. For Patient Quotes it must be available through a Patient Payor. For Quotes without a Patient it identifies the organisation being quoted.
booking_idsarray
Optional unique Booking IDs in the Organization that belong to the Quote's Patient. Omit this field when the Quote has no Patient.
- itemsstring · uuid
clinician_idstring | null · uuid
The optional Clinician attributed to the Quote. When omitted, Carebit infers it only if every supplied Booking shares one Clinician.
expires_onstring · date
The date the Quote remains valid through. Defaults to the Organization's default quote validity, which is 28 days unless changed.
line_itemsarray
Optional custom charges. When omitted and booking_ids is supplied, Carebit generates line items from those Bookings. Amounts are minor currency units.
- itemsobject
  - booking_idstring | null · uuid
    The optional Booking associated with this line item. The Booking must be included in booking_ids.
  - discount_amountinteger
    The discount in minor currency units.
  - external_provider_namestring | null
    The provider that collects an external fee.
  - is_billed_by_another_providerboolean
    Whether another provider bills this line instead of the practice that issued the Quote.
  - quantitynumber
    The quantity quoted. Defaults to 1.
  - tax_treatmentstring | null
    The tax treatment for the line item.
    Allowed values: exempt | no_vat | standard | zero_rated
  - titlestringrequired
    The line item description.
  - unit_priceintegerrequired
    The unit price in minor currency units, excluding tax.
notesstring | null
HTML notes shown on the Quote.
patient_idstring | null · uuid
The Patient with an active connection to the Organization. Omit this field to quote another organisation, and supply alternative_payor_id instead.
payor_typestring
The party the Quote is issued to. Defaults from linked Bookings, to patient for a standalone Patient Quote, or to alternative_payor when patient_id is omitted.
Allowed values: patient | alternative_payor
quoted_onstring · date
The Quote date. Defaults to today.
termsstring | null
HTML terms. When omitted, Carebit copies the Clinician or Organization default.
titlestring | null
The Quote title.

Responses

201

The requested Quote.

accepted_atstring | null · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
alternative_payor_idstring | null · uuidrequired
The AlternativePayor for an alternative-payor Quote.
booking_idsarrayrequired
The Bookings linked to the Quote.
- itemsstring · uuid
cancel_reasonstring | nullrequired
Why the Quote was canceled. staff is a staff cancellation. superseded is set when a revised Quote replaces it.
Allowed values: staff | superseded | null
canceled_atstring | null · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
clinician_idstring | null · uuidrequired
The Clinician attributed to the Quote.
created_atstring · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
creation_sourcestring | nullrequired
How the Quote was created.
Allowed values: staff_member | api | null
currencystring | nullrequired
The ISO 4217 currency code.
current_invoice_idstring | null · uuidrequired
The current non-cancelled Invoice generated from the Quote.
declined_atstring | null · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
expired_atstring | null · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
expires_onstring | null · daterequired
The date the Quote remains valid through.
idstring · uuidrequired
The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
invoice_idstring | null · uuidrequired
The Invoice created by the first conversion or acceptance.
invoice_idsarrayrequired
Every Invoice generated from the Quote, including cancelled generations.
- itemsstring · uuid
invoiced_atstring | null · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
line_itemsarrayrequired
The proposed charges on the Quote.
- itemsobject
  - booking_idstring | null · uuidrequired
    The Booking associated with the line item.
  - created_atstring · date-timerequired
    An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
  - currencystring | nullrequired
    The ISO 4217 currency code.
  - discount_amountinteger | nullrequired
    The discount in minor currency units.
  - external_provider_namestring | nullrequired
    The provider that collects an external fee.
  - idstring · uuidrequired
    The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - is_billed_by_another_providerbooleanrequired
    Whether another provider bills this line instead of the practice that issued the Quote.
  - objectanyrequired
    Discriminator value emitted at object.
  - quantitynumber | nullrequired
    The quantity quoted.
  - titlestring | nullrequired
    The line item description.
  - totalinteger | nullrequired
    The line total in minor currency units.
  - unit_priceinteger | nullrequired
    The unit price in minor currency units.
  - updated_atstring · date-timerequired
    An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
linksobjectrequired
URLs to related resources.
- alternative_payorstring | null · urirequired
  The full URL of a related resource.
- bookingsarrayrequired
  Developer Platform URLs for linked Bookings.
  - itemsstring · uri
    The full URL of a related resource.
- clinicianstring | null · urirequired
  The full URL of a related resource.
- current_invoicestring | null · urirequired
  The full URL of a related resource.
- invoicestring | null · urirequired
  The full URL of a related resource.
- invoicesarrayrequired
  Developer Platform URLs for every generated Invoice.
  - itemsstring · uri
    The full URL of a related resource.
- patientstring | null · urirequired
  The full URL of a related resource.
notesstring | nullrequired
Sanitized HTML notes on the Quote.
objectanyrequired
Discriminator value emitted at object.
patient_idstring | null · uuidrequired
The Patient associated with the Quote.
payor_typestring | nullrequired
The party the Quote is issued to.
Allowed values: patient | alternative_payor | null
quote_numberstring | nullrequired
The Quote number, unique within the Organization.
quoted_onstring | null · daterequired
The date the Quote was issued or drafted.
recipient_display_namestring | nullrequired
The display name of the live Patient or AlternativePayor the Quote is sent to.
sent_atstring | null · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
statusstring | nullrequired
The Quote's current status.
Allowed values: draft | sent | accepted | declined | expired | canceled | invoiced | null
termsstring | nullrequired
Sanitized HTML terms copied onto the Quote.
titlestring | nullrequired
The Quote title.
totalintegerrequired
The Quote total in minor currency units, including lines billed by another provider.
total_collectible_by_issuing_organizationintegerrequired
The amount the issuing Organization will collect, in minor currency units. Excludes lines billed by another provider.
updated_atstring · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.

Example

{
  "id": "f72cd09f-9bdc-4341-8184-bf2f900a8669",
  "object": "quote",
  "accepted_at": "2026-01-01T09:00:00Z",
  "alternative_payor_id": null,
  "booking_ids":  … ]
    "00000000-0000-4000-8000-000000000001"
  ],
  "cancel_reason": "staff",
  "canceled_at": "2026-01-01T09:00:00Z",
  "clinician_id": "00000000-0000-4000-8000-000000000002",
  "created_at": "2026-01-01T09:00:00Z",
  "creation_source": "staff_member",
  "currency": "GBP",
  "current_invoice_id": "b478fd43-d3a3-4599-8444-e55e805e96fe",
  "declined_at": "2026-01-01T09:00:00Z",
  "expired_at": "2026-01-01T09:00:00Z",
  "expires_on": "2026-01-01",
  "invoice_id": "00000000-0000-4000-8000-000000000027",
  "invoice_ids":  … ]
    "00000000-0000-4000-8000-000000000027"
  ],
  "invoiced_at": "2026-01-01T09:00:00Z",
  "line_items":  … ]
     … }
      "id": "a2811c16-a221-45cd-8c38-176432273234",
      "object": "quote_line_item",
      "booking_id": "00000000-0000-4000-8000-000000000001",
      "created_at": "2026-01-01T09:00:00Z",
      "currency": "GBP",
      "discount_amount": 1,
      "external_provider_name": "London Bridge Hospital",
      "is_billed_by_another_provider": true,
      "quantity": 1.5,
      "title": "Dr",
      "total": 1,
      "unit_price": 1,
      "updated_at": "2026-01-01T09:00:00Z"
    }
  ],
  "links":  … }
    "alternative_payor": "https://api.carebit.co/v1/alternative_payors/815dfc1e-6eaf-4b71-8a94-ec2a13224fca",
    "bookings":  … ]
      "https://api.carebit.co/v1/bookings/00000000-0000-4000-8000-000000000001"
    ],
    "clinician": "https://api.carebit.co/v1/clinicians/00000000-0000-4000-8000-000000000002",
    "current_invoice": "https://api.carebit.co/v1/current_invoices/b478fd43-d3a3-4599-8444-e55e805e96fe",
    "invoice": "https://api.carebit.co/v1/invoices/00000000-0000-4000-8000-000000000027",
    "invoices":  … ]
      "https://api.carebit.co/v1/invoices/00000000-0000-4000-8000-000000000027"
    ],
    "patient": "https://api.carebit.co/v1/patients/00000000-0000-4000-8000-000000000004"
  },
  "notes": "Please confirm the appointment by email.",
  "patient_id": "00000000-0000-4000-8000-000000000004",
  "payor_type": "insurance_company",
  "quote_number": "QUO-1001",
  "quoted_on": "2026-01-01",
  "recipient_display_name": "Alex Morgan",
  "sent_at": "2026-01-01T09:00:00Z",
  "status": "draft",
  "terms": "<p>This quote is valid until the expiry date shown.</p>",
  "title": "Initial consultation quote",
  "total": 1,
  "total_collectible_by_issuing_organization": 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

The Patient, Clinician, Booking, or AlternativePayor was not found in the Organization.

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

Example

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

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 Quote cannot be created. payor_type must be patient or alternative_payor.

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/quotes" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "booking_ids": [
    "00000000-0000-4000-8000-000000000001"
  ],
  "clinician_id": "00000000-0000-4000-8000-000000000002",
  "patient_id": "00000000-0000-4000-8000-000000000004",
  "payor_type": "patient",
  "title": "Initial consultation quote"
}'

201 response

{
  "id": "f72cd09f-9bdc-4341-8184-bf2f900a8669",
  "object": "quote",
  "accepted_at": "2026-01-01T09:00:00Z",
  "alternative_payor_id": null,
  "booking_ids":  … ]
    "00000000-0000-4000-8000-000000000001"
  ],
  "cancel_reason": "staff",
  "canceled_at": "2026-01-01T09:00:00Z",
  "clinician_id": "00000000-0000-4000-8000-000000000002",
  "created_at": "2026-01-01T09:00:00Z",
  "creation_source": "staff_member",
  "currency": "GBP",
  "current_invoice_id": "b478fd43-d3a3-4599-8444-e55e805e96fe",
  "declined_at": "2026-01-01T09:00:00Z",
  "expired_at": "2026-01-01T09:00:00Z",
  "expires_on": "2026-01-01",
  "invoice_id": "00000000-0000-4000-8000-000000000027",
  "invoice_ids":  … ]
    "00000000-0000-4000-8000-000000000027"
  ],
  "invoiced_at": "2026-01-01T09:00:00Z",
  "line_items":  … ]
     … }
      "id": "a2811c16-a221-45cd-8c38-176432273234",
      "object": "quote_line_item",
      "booking_id": "00000000-0000-4000-8000-000000000001",
      "created_at": "2026-01-01T09:00:00Z",
      "currency": "GBP",
      "discount_amount": 1,
      "external_provider_name": "London Bridge Hospital",
      "is_billed_by_another_provider": true,
      "quantity": 1.5,
      "title": "Dr",
      "total": 1,
      "unit_price": 1,
      "updated_at": "2026-01-01T09:00:00Z"
    }
  ],
  "links":  … }
    "alternative_payor": "https://api.carebit.co/v1/alternative_payors/815dfc1e-6eaf-4b71-8a94-ec2a13224fca",
    "bookings":  … ]
      "https://api.carebit.co/v1/bookings/00000000-0000-4000-8000-000000000001"
    ],
    "clinician": "https://api.carebit.co/v1/clinicians/00000000-0000-4000-8000-000000000002",
    "current_invoice": "https://api.carebit.co/v1/current_invoices/b478fd43-d3a3-4599-8444-e55e805e96fe",
    "invoice": "https://api.carebit.co/v1/invoices/00000000-0000-4000-8000-000000000027",
    "invoices":  … ]
      "https://api.carebit.co/v1/invoices/00000000-0000-4000-8000-000000000027"
    ],
    "patient": "https://api.carebit.co/v1/patients/00000000-0000-4000-8000-000000000004"
  },
  "notes": "Please confirm the appointment by email.",
  "patient_id": "00000000-0000-4000-8000-000000000004",
  "payor_type": "insurance_company",
  "quote_number": "QUO-1001",
  "quoted_on": "2026-01-01",
  "recipient_display_name": "Alex Morgan",
  "sent_at": "2026-01-01T09:00:00Z",
  "status": "draft",
  "terms": "<p>This quote is valid until the expiry date shown.</p>",
  "title": "Initial consultation quote",
  "total": 1,
  "total_collectible_by_issuing_organization": 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"
  }
}

Endpoints

Parameters

Request body

Responses