Creating and connecting Patients

POST /v1/patients creates a Patient for your organisation, or connects your organisation to a Patient who already exists in Carebit.

Carebit first finds possible matches using first name, last name, date of birth, sex, and postcode. All five fields must match. Name punctuation and postcode spaces do not affect matching, and the first token of a multi-part first name can match. Email, phone, mobile, and NHS number then help rank possible matches. Always send those fields when you have them.

Requires patients.create and an Idempotency-Key. This endpoint allows 10 requests per access token per minute.

What comes back

Handle the HTTP status:

Carebit does not overwrite an existing Patient with the body you sent. Use PATCH /v1/patients/{id} after you have a connected Patient if you need to update their record. That requires patients.update.

When Carebit creates a Patient and the body includes email, Carebit also creates a Patient Portal account for that email. Carebit does not send the portal welcome email. The same account is created if you add an email later with PATCH /v1/patients/{id} and the Patient does not already have one. A Patient with no email has no portal account.

Explicit connection

Carebit never connects an unconnected match as part of POST /v1/patients, even when a supplied email, phone number, or NHS number agrees. The create call returns 202 and a PatientConnectionRequest. A separate action makes the organisation, not Carebit, responsible for choosing the outcome.

If you are happy that the recommended candidate is the same person, you can grant access immediately by posting connect_existing_patient. You do not have to wait for staff.

Staff can also compare the records in Carebit and grant access, create a separate Patient, or deny the request. An automated integration or AI agent can make the same explicit action through the API. Both workflows are recorded on the PatientConnectionRequest for audit.

PatientConnectionRequest

A PatientConnectionRequest is a durable, auditable request for your organisation to choose how to proceed.

The 202 body looks like this:

{
  "id": "11111111-1111-4111-8111-111111111111",
  "object": "patient_connection_request",
  "created_at": "2026-09-24T10:00:00Z",
  "expires_at": "2026-10-24T10:00:00Z",
  "status": "pending",
  "resolved_outcome": null,
  "patient_id": null,
  "available_actions": [
    "connect_existing_patient",
    "create_new_patient",
    "deny"
  ],
  "candidate": {
    "matched_fields": [
      "first_name",
      "last_name",
      "date_of_birth",
      "sex",
      "postcode"
    ],
    "conflicting_fields": [],
    "not_recorded_fields": []
  },
  "submitted": {
    "first_name": "Alex",
    "last_name": "Morgan",
    "date_of_birth": "1990-01-01",
    "sex": "female",
    "postcode": "SW1A 1AA",
    "email": "alex.morgan@example.com"
  },
  "links": {
    "dashboard": "https://example.carebit.co/admin/patients/connection-requests"
  }
}

Carebit returns only the strongest candidate. Demographic, contact, and NHS number evidence determine the ranking; PatientConnection and Document counts break ties. Only matching demographic field names are disclosed. POST connect_existing_patient to connect the strongest current recommendation. Carebit does not disclose alternatives, activity counts, the Patient ID, contact or NHS number classifications, another organisation, or any existing value that you did not submit.

While status is pending, denied, or expired, patient_id is null. After connect_existing_patient or create_new_patient, the request is granted and includes the resulting patient_id.

Staff can open links.dashboard to view every Patient connection request in Carebit, compare the complete records, and choose Grant access, Create separate Patient, or Deny. Carebit does not email the organisation when a request is created. Send links.dashboard yourself if you want staff to be notified.

Carebit does not email or text the Patient to confirm the match.

After an approved action, patient_id is present and you can call GET /v1/patients/{id} with patients.read.

Act on a request through the API

Any Developer Platform project in the organisation can grant access immediately, or apply another organisation policy, with patients.create. One project can create the request and another can act on it. There is no separate grant scope. The action must be a second API call, so retry it with an Idempotency-Key.

If you are ready to connect the recommended Patient, put the request id in POST /v1/patient_connection_requests/{id}/actions and send {"action":"connect_existing_patient"}.

Use {"action":"create_new_patient"} when your organisation determines that the recommendation is not the same person. This explicitly creates a separate Patient from the submitted details. Use {"action":"deny"} to deny the request.

Any project in the organisation with patients.create can POST an action. Poll GET /v1/patient_connection_requests/{id} if your credential also has patients.read.

Enabled webhook endpoints on the project that created the request always receive these required system events. Other projects in the organisation do not receive them. You do not subscribe to them, and they do not appear in the subscription picker:

• patient_connection_request.created
• patient_connection_request.granted
• patient_connection_request.denied
• patient_connection_request.expired

You can also subscribe to patient_connection.created. That is the signal that your organisation can now use the Patient. It also fires when Carebit creates a Patient.

List requests with GET /v1/patient_connection_requests. You may filter by status: pending, granted, denied, or expired.

Pending requests expire after 30 days if your organisation has not acted.

Branch on the status in your application:

1. 201 or 200: read id from the Patient and continue (for example create a Booking).
2. 202: store the PatientConnectionRequest id. If you are ready to connect the recommended Patient, POST connect_existing_patient immediately. Otherwise let staff review the request in Carebit, or apply another organisation policy through the actions endpoint. Wait for patient_connection_request.granted before creating records that need a connected Patient. Keep uploads or other registration data in your own pending workflow until then.

Repeating the same details while a request is still pending returns that same pending request rather than creating another one.

What this endpoint will not do

• It will not automatically create a second Patient when a match exists.

• It will not automatically connect an unconnected match, even when a contact field agrees.

• It will not accept an unconnected Patient identifier in the create body so you can claim that record.

• It will not expose alternative candidates or accept a Patient ID as the API recommendation.

• It will not contact the Patient to confirm they are the same person.

• It will not email organisation staff when a request is created.

• Create a Patient

• List PatientConnectionRequests

• Webhook setup

• Idempotency and safe retries