# Get a PatientConnectionRequest

`GET /v1/patient_connection_requests/:id`

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, `string`) (required)

## Response `200`

The requested `PatientConnectionRequest`.

- `object`
  - `available_actions` (`array`) - The actions the caller can take while this request is pending. The array is empty after resolution or expiry.
    - `items` (`string`) - enum: `connect_existing_patient`, `create_new_patient`, `deny`
  - `candidate` (`object | null`) - 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_fields` (`array`) - Reserved for compatibility. Carebit returns an empty array so the response cannot disclose whether a candidate has a particular contact or NHS number value.
      - `items` (`string`)
    - `matched_fields` (`array`) - The submitted demographic fields that match the recommended candidate. Contact and NHS number matches are not disclosed.
      - `items` (`string`)
    - `not_recorded_fields` (`array`) - Reserved for compatibility. Carebit returns an empty array so the response cannot disclose whether a candidate has a particular contact or NHS number value.
      - `items` (`string`)
  - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `expires_at` (`string`) - format: `date-time`; The time after which a pending PatientConnectionRequest expires if the Organization has not resolved it.
  - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - `links` (`object`) - URLs to related resources.
    - `dashboard` (`string`) - format: `uri`; 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.
    - `patient` (`string | null`) - format: `uri`; The Patient retrieve URL after an approved action. Null while the request is pending, denied, or expired.
  - `object` (`any`) - Discriminator value emitted at `object`.
  - `patient_id` (`string | null`) - format: `uuid`; The resulting Patient identifier after the Organization connects an existing Patient or creates a separate Patient. Null while pending, denied, or expired.
  - `resolved_outcome` (`string | null`) - enum: `connected_existing`, `created_new`, `denied`, `expired`, `null`; How the Organization resolved this request. Null while it is pending.
  - `status` (`string`) - enum: `pending`, `granted`, `denied`, `expired`; The lifecycle status of the PatientConnectionRequest. `granted` means a resulting PatientConnection exists.
  - `submitted` (`object`) - 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_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.

### Example

```json
{
  "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"
}
```

## Response `401`

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

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "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"
  }
}
```

## Response `403`

The access token lacks the required scope, or the project is disabled.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "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"
  }
}
```

## Response `404`

Error response.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "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"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "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"
  }
}
```

## Code samples

```bash
curl -X GET "https://api.carebit.co/v1/patient_connection_requests/f50a3a17-e1a9-4eaf-813b-a062b56e6683" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"
```

```javascript
const response = await fetch("https://api.carebit.co/v1/patient_connection_requests/f50a3a17-e1a9-4eaf-813b-a062b56e6683", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
  },
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests

response = requests.get(
    "https://api.carebit.co/v1/patient_connection_requests/f50a3a17-e1a9-4eaf-813b-a062b56e6683",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"

response = HTTParty.get(
  "https://api.carebit.co/v1/patient_connection_requests/f50a3a17-e1a9-4eaf-813b-a062b56e6683",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}"
  }
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->get("https://api.carebit.co/v1/patient_connection_requests/f50a3a17-e1a9-4eaf-813b-a062b56e6683", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```