Carebit API

Patient Connection Requests

Audited requests for an Organization to connect an existing Patient, create a separate Patient, or deny the request. There is no separate PatientConnectionRequest scope: list and retrieve use patients.read, and act uses patients.create.

Required API scopes: patients.createpatients.read

Endpoints

Scroll this page to read every Patient Connection Requests endpoint, or jump to one below.

get/v1/patient_connection_requestsList PatientConnectionRequestspatients.read
get/v1/patient_connection_requests/:idGet a PatientConnectionRequestpatients.read
post/v1/patient_connection_requests/:id/actionsAction a PatientConnectionRequestpatients.create

get/v1/patient_connection_requests

List PatientConnectionRequests

Returns PatientConnectionRequests created for the Organization by POST /v1/patients. Filter by status. Results are newest first. Pending payloads omit the matched Patient identifier.

Required API scopes: patients.read

Parameters

status
query
string · enum: pending | granted | denied | expired
Return only PatientConnectionRequests with this status.
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 PatientConnectionRequest objects.

dataarrayrequired
- itemsobject
  - available_actionsarrayrequired
    The actions the caller can take while this request is pending. The array is empty after resolution or expiry.
    - itemsstring
      Allowed values: connect_existing_patient | create_new_patient | deny
  - candidateobject | nullrequired
    The strongest current match, or null when no match remains. Demographic, contact, and NHS number evidence determine the ranking; PatientConnection and Document counts break ties. Only matching demographic field names are disclosed. Existing values, contact and NHS number classifications, activity counts, alternative candidates, and Patient identifiers are not disclosed. POST connect_existing_patient to connect this recommendation.
    - conflicting_fieldsarrayrequired
      Reserved for compatibility. Carebit returns an empty array so the response cannot disclose whether a candidate has a particular contact or NHS number value.
      - itemsstring
    - matched_fieldsarrayrequired
      The submitted demographic fields that match the recommended candidate. Contact and NHS number matches are not disclosed.
      - itemsstring
    - not_recorded_fieldsarrayrequired
      Reserved for compatibility. Carebit returns an empty array so the response cannot disclose whether a candidate has a particular contact or NHS number value.
      - itemsstring
  - created_atstring · date-timerequired
    An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
  - expires_atstring · date-timerequired
    The time after which a pending PatientConnectionRequest expires if the Organization has not resolved it.
  - idstring · uuidrequired
    The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - linksobjectrequired
    URLs to related resources.
    - dashboardstring · urirequired
      The Carebit Admin URL listing Patient connection requests for the Organization. This is a Carebit UI URL, not a Developer Platform API URL. Carebit does not email staff when a request is created. Send this URL if you want someone to review pending requests.
    - patientstring | null · urirequired
      The Patient retrieve URL after an approved action. Null while the request is pending, denied, or expired.
  - objectanyrequired
    Discriminator value emitted at object.
  - patient_idstring | null · uuidrequired
    The resulting Patient identifier after the Organization connects an existing Patient or creates a separate Patient. Null while pending, denied, or expired.
  - resolved_outcomestring | nullrequired
    How the Organization resolved this request. Null while it is pending.
    Allowed values: connected_existing | created_new | denied | expired | null
  - statusstringrequired
    The lifecycle status of the PatientConnectionRequest. granted means a resulting PatientConnection exists.
    Allowed values: pending | granted | denied | expired
  - submittedobjectrequired
    The Patient create payload that produced this request. Carebit echoes the fields you sent. It does not include existing-Patient fields you did not submit.
  - 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": "f50a3a17-e1a9-4eaf-813b-a062b56e6683",
      "object": "patient_connection_request",
      "available_actions":  … ]
        "connect_existing_patient"
      ],
      "candidate":  … }
        "conflicting_fields": [],
        "matched_fields":  … ]
          "first_name",
          "last_name",
          "date_of_birth",
          "sex",
          "postcode"
        ],
        "not_recorded_fields": []
      },
      "created_at": "2026-01-01T09:00:00Z",
      "expires_at": "2026-01-01T09:00:00Z",
      "links":  … }
        "dashboard": "https://example.carebit.co/admin/patients/connection-requests",
        "patient": "https://api.carebit.co/v1/patients/00000000-0000-4000-8000-000000000004"
      },
      "patient_id": "00000000-0000-4000-8000-000000000004",
      "resolved_outcome": "connected_existing",
      "status": "pending",
      "submitted": {},
      "updated_at": "2026-01-01T09:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": "eyJzdGFydF90aW1lIjoiMjAyNi0wMS0wMVQwOTowMDowMFoifQ",
  "url": "/v1/patient_connection_requests"
}

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

200 response

{
  "object": "list",
  "data":  … ]
     … }
      "id": "f50a3a17-e1a9-4eaf-813b-a062b56e6683",
      "object": "patient_connection_request",
      "available_actions":  … ]
        "connect_existing_patient"
      ],
      "candidate":  … }
        "conflicting_fields": [],
        "matched_fields":  … ]
          "first_name",
          "last_name",
          "date_of_birth",
          "sex",
          "postcode"
        ],
        "not_recorded_fields": []
      },
      "created_at": "2026-01-01T09:00:00Z",
      "expires_at": "2026-01-01T09:00:00Z",
      "links":  … }
        "dashboard": "https://example.carebit.co/admin/patients/connection-requests",
        "patient": "https://api.carebit.co/v1/patients/00000000-0000-4000-8000-000000000004"
      },
      "patient_id": "00000000-0000-4000-8000-000000000004",
      "resolved_outcome": "connected_existing",
      "status": "pending",
      "submitted": {},
      "updated_at": "2026-01-01T09:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": "eyJzdGFydF90aW1lIjoiMjAyNi0wMS0wMVQwOTowMDowMFoifQ",
  "url": "/v1/patient_connection_requests"
}

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"
  }
}

get/v1/patient_connection_requests/:id

Get a PatientConnectionRequest

Returns one PatientConnectionRequest created for the Organization. Pending, denied, and expired payloads omit the matched Patient identifier. After grant the object includes patient_id.

Required API scopes: patients.read

Parameters

id
path · required
string
-

Responses

200

The requested PatientConnectionRequest.

available_actionsarrayrequired
The actions the caller can take while this request is pending. The array is empty after resolution or expiry.
- itemsstring
  Allowed values: connect_existing_patient | create_new_patient | deny
candidateobject | nullrequired
The strongest current match, or null when no match remains. Demographic, contact, and NHS number evidence determine the ranking; PatientConnection and Document counts break ties. Only matching demographic field names are disclosed. Existing values, contact and NHS number classifications, activity counts, alternative candidates, and Patient identifiers are not disclosed. POST connect_existing_patient to connect this recommendation.
- conflicting_fieldsarrayrequired
  Reserved for compatibility. Carebit returns an empty array so the response cannot disclose whether a candidate has a particular contact or NHS number value.
  - itemsstring
- matched_fieldsarrayrequired
  The submitted demographic fields that match the recommended candidate. Contact and NHS number matches are not disclosed.
  - itemsstring
- not_recorded_fieldsarrayrequired
  Reserved for compatibility. Carebit returns an empty array so the response cannot disclose whether a candidate has a particular contact or NHS number value.
  - itemsstring
created_atstring · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
expires_atstring · date-timerequired
The time after which a pending PatientConnectionRequest expires if the Organization has not resolved it.
idstring · uuidrequired
The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
linksobjectrequired
URLs to related resources.
- dashboardstring · urirequired
  The Carebit Admin URL listing Patient connection requests for the Organization. This is a Carebit UI URL, not a Developer Platform API URL. Carebit does not email staff when a request is created. Send this URL if you want someone to review pending requests.
- patientstring | null · urirequired
  The Patient retrieve URL after an approved action. Null while the request is pending, denied, or expired.
objectanyrequired
Discriminator value emitted at object.
patient_idstring | null · uuidrequired
The resulting Patient identifier after the Organization connects an existing Patient or creates a separate Patient. Null while pending, denied, or expired.
resolved_outcomestring | nullrequired
How the Organization resolved this request. Null while it is pending.
Allowed values: connected_existing | created_new | denied | expired | null
statusstringrequired
The lifecycle status of the PatientConnectionRequest. granted means a resulting PatientConnection exists.
Allowed values: pending | granted | denied | expired
submittedobjectrequired
The Patient create payload that produced this request. Carebit echoes the fields you sent. It does not include existing-Patient fields you did not submit.
updated_atstring · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.

Example

{
  "id": "f50a3a17-e1a9-4eaf-813b-a062b56e6683",
  "object": "patient_connection_request",
  "available_actions":  … ]
    "connect_existing_patient"
  ],
  "candidate":  … }
    "conflicting_fields": [],
    "matched_fields":  … ]
      "first_name",
      "last_name",
      "date_of_birth",
      "sex",
      "postcode"
    ],
    "not_recorded_fields": []
  },
  "created_at": "2026-01-01T09:00:00Z",
  "expires_at": "2026-01-01T09:00:00Z",
  "links":  … }
    "dashboard": "https://example.carebit.co/admin/patients/connection-requests",
    "patient": "https://api.carebit.co/v1/patients/00000000-0000-4000-8000-000000000004"
  },
  "patient_id": "00000000-0000-4000-8000-000000000004",
  "resolved_outcome": "connected_existing",
  "status": "pending",
  "submitted": {},
  "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/patient_connection_requests/f50a3a17-e1a9-4eaf-813b-a062b56e6683" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"

200 response

{
  "id": "f50a3a17-e1a9-4eaf-813b-a062b56e6683",
  "object": "patient_connection_request",
  "available_actions":  … ]
    "connect_existing_patient"
  ],
  "candidate":  … }
    "conflicting_fields": [],
    "matched_fields":  … ]
      "first_name",
      "last_name",
      "date_of_birth",
      "sex",
      "postcode"
    ],
    "not_recorded_fields": []
  },
  "created_at": "2026-01-01T09:00:00Z",
  "expires_at": "2026-01-01T09:00:00Z",
  "links":  … }
    "dashboard": "https://example.carebit.co/admin/patients/connection-requests",
    "patient": "https://api.carebit.co/v1/patients/00000000-0000-4000-8000-000000000004"
  },
  "patient_id": "00000000-0000-4000-8000-000000000004",
  "resolved_outcome": "connected_existing",
  "status": "pending",
  "submitted": {},
  "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"
  }
}

post/v1/patient_connection_requests/:id/actions

Action a PatientConnectionRequest

Applies the Organization's explicit action to a pending PatientConnectionRequest. connect_existing_patient connects the strongest current recommendation, create_new_patient creates a separate Patient, and deny denies the request. Any Project in the Organization with patients.create can act. The acting API credential is recorded for audit.

Required API scopes: patients.create

Parameters

id
path · required
string
The PatientConnectionRequest id from the 202 create response or from GET /v1/patient_connection_requests/{id}.
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

actionstringrequired
The Organization's explicit action for this request.
Allowed values: connect_existing_patient | create_new_patient | deny
clinician_idstring | null · uuid
The optional Clinician to assign to the resulting PatientConnection.

Responses

201

The requested PatientConnectionRequest.

available_actionsarrayrequired
The actions the caller can take while this request is pending. The array is empty after resolution or expiry.
- itemsstring
  Allowed values: connect_existing_patient | create_new_patient | deny
candidateobject | nullrequired
The strongest current match, or null when no match remains. Demographic, contact, and NHS number evidence determine the ranking; PatientConnection and Document counts break ties. Only matching demographic field names are disclosed. Existing values, contact and NHS number classifications, activity counts, alternative candidates, and Patient identifiers are not disclosed. POST connect_existing_patient to connect this recommendation.
- conflicting_fieldsarrayrequired
  Reserved for compatibility. Carebit returns an empty array so the response cannot disclose whether a candidate has a particular contact or NHS number value.
  - itemsstring
- matched_fieldsarrayrequired
  The submitted demographic fields that match the recommended candidate. Contact and NHS number matches are not disclosed.
  - itemsstring
- not_recorded_fieldsarrayrequired
  Reserved for compatibility. Carebit returns an empty array so the response cannot disclose whether a candidate has a particular contact or NHS number value.
  - itemsstring
created_atstring · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
expires_atstring · date-timerequired
The time after which a pending PatientConnectionRequest expires if the Organization has not resolved it.
idstring · uuidrequired
The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
linksobjectrequired
URLs to related resources.
- dashboardstring · urirequired
  The Carebit Admin URL listing Patient connection requests for the Organization. This is a Carebit UI URL, not a Developer Platform API URL. Carebit does not email staff when a request is created. Send this URL if you want someone to review pending requests.
- patientstring | null · urirequired
  The Patient retrieve URL after an approved action. Null while the request is pending, denied, or expired.
objectanyrequired
Discriminator value emitted at object.
patient_idstring | null · uuidrequired
The resulting Patient identifier after the Organization connects an existing Patient or creates a separate Patient. Null while pending, denied, or expired.
resolved_outcomestring | nullrequired
How the Organization resolved this request. Null while it is pending.
Allowed values: connected_existing | created_new | denied | expired | null
statusstringrequired
The lifecycle status of the PatientConnectionRequest. granted means a resulting PatientConnection exists.
Allowed values: pending | granted | denied | expired
submittedobjectrequired
The Patient create payload that produced this request. Carebit echoes the fields you sent. It does not include existing-Patient fields you did not submit.
updated_atstring · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.

Example

{
  "id": "f50a3a17-e1a9-4eaf-813b-a062b56e6683",
  "object": "patient_connection_request",
  "available_actions":  … ]
    "connect_existing_patient"
  ],
  "candidate":  … }
    "conflicting_fields": [],
    "matched_fields":  … ]
      "first_name",
      "last_name",
      "date_of_birth",
      "sex",
      "postcode"
    ],
    "not_recorded_fields": []
  },
  "created_at": "2026-01-01T09:00:00Z",
  "expires_at": "2026-01-01T09:00:00Z",
  "links":  … }
    "dashboard": "https://example.carebit.co/admin/patients/connection-requests",
    "patient": "https://api.carebit.co/v1/patients/00000000-0000-4000-8000-000000000004"
  },
  "patient_id": "00000000-0000-4000-8000-000000000004",
  "resolved_outcome": "connected_existing",
  "status": "pending",
  "submitted": {},
  "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

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 POST "https://api.carebit.co/v1/patient_connection_requests/f50a3a17-e1a9-4eaf-813b-a062b56e6683/actions" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "action": "connect_existing_patient"
}'

201 response

{
  "id": "f50a3a17-e1a9-4eaf-813b-a062b56e6683",
  "object": "patient_connection_request",
  "available_actions":  … ]
    "connect_existing_patient"
  ],
  "candidate":  … }
    "conflicting_fields": [],
    "matched_fields":  … ]
      "first_name",
      "last_name",
      "date_of_birth",
      "sex",
      "postcode"
    ],
    "not_recorded_fields": []
  },
  "created_at": "2026-01-01T09:00:00Z",
  "expires_at": "2026-01-01T09:00:00Z",
  "links":  … }
    "dashboard": "https://example.carebit.co/admin/patients/connection-requests",
    "patient": "https://api.carebit.co/v1/patients/00000000-0000-4000-8000-000000000004"
  },
  "patient_id": "00000000-0000-4000-8000-000000000004",
  "resolved_outcome": "connected_existing",
  "status": "pending",
  "submitted": {},
  "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.