# 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: | Status | Object | Meaning | | ------ | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `201` | Patient | Carebit created a new Patient and connected them to your organisation. | | `200` | Patient | The Patient already existed and was already connected to your organisation. Carebit returned them without changing their record. | | `202` | PatientConnectionRequest | One or more unconnected Patients may match. Your organisation must explicitly connect the strongest recommendation, create a separate Patient, or deny the request. | 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: ```json { "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](/api/patients/create) - [List PatientConnectionRequests](/api/patient-connection-requests) - [Webhook setup](/guides/webhook-setup) - [Idempotency and safe retries](/guides/idempotency-and-retries)