# List appointment summaries by status for referrers and specialists

Returns appointment summaries filtered by provider number when the caller is authorized and scoped to referrer/specialist grants. Provider numbers are resolved from the authenticated principal's access grants and are not supplied as query parameters. Supports cursor-based pagination via pageSize and nextToken.

Endpoint: GET /integrations/v1/{domain}/appointments/referrer/by-status/{status}
Version: v1
Security: Bearer

## Path parameters:

  - `domain` (string, required)
    Partner domain identifier. Your bearer token is scoped to one or more domains and requests outside that scope are rejected.
    Example: "acme"

  - `status` (string, required)
    Appointment status filter value. Must match one of the known QUBS appointment status strings.
    Enum: "NOT ARRIVED", "ARRIVED", "DID NOT ATTEND", "APPPOINTMENT CANCELLED", "CANCELLATION LIST", "DICTATION INPROGRESS", "DICTATED", "TYPED", "AUTHORISING", "AUTHORISED", "TYPING INPROGRESS", "PENDING REPORTING", "STUDY INPROGRESS", "SECOND REVIEW", "FINALISED", "REVIEW TYPED", "PEER REVIEW", "SECOND OPINION"

## Query parameters:

  - `pageSize` (integer)
    Maximum number of items to return in a page. Defaults to 100 when omitted. Must be between 1 and 500.
    Example: 100

  - `nextToken` (string)
    Opaque, URL-safe continuation token returned as nextToken in a previous paged response. Omit for the first page.
    Example: "DDB_NEXT_TOKEN"

## Header parameters:

  - `X-Correlation-Id` (string)
    Request correlation identifier. Echoes the incoming X-Correlation-Id header when provided.
    Example: "4b7f0a91b4f54f2a"

## Response 200 fields (application/json):

  - `items` (array, required)
    Appointment summaries in the current page.

  - `items.domain` (string, required)
    Domain this appointment belongs to.
    Example: "Example domain"

  - `items.appointmentId` (string, required)
    Appointment identifier.
    Example: "123"

  - `items.scheduledSite` (string, required)
    Scheduled site name.
    Example: "Example scheduledSite"

  - `items.status` (string, required)
    Appointment status.
    Enum: "NOT ARRIVED", "ARRIVED", "DID NOT ATTEND", "APPPOINTMENT CANCELLED", "CANCELLATION LIST", "DICTATION INPROGRESS", "DICTATED", "TYPED", "AUTHORISING", "AUTHORISED", "TYPING INPROGRESS", "PENDING REPORTING", "STUDY INPROGRESS", "SECOND REVIEW", "FINALISED", "REVIEW TYPED", "PEER REVIEW", "SECOND OPINION"

  - `items.appointmentDate` (null,string)
    Appointment date (ISO 8601, yyyy-MM-dd) in the scheduled site's local timezone.
    Example: "2020-01-01"

  - `items.startTime` (null,string)
    Scheduled start time (ISO 8601, HH:mm:ss) in the scheduled site's local timezone.
    Example: "13:45:00"

  - `items.endTime` (null,string)
    Scheduled end time (ISO 8601, HH:mm:ss) in the scheduled site's local timezone.
    Example: "13:45:00"

  - `items.modality` (string)
    Example: "Example modality"

  - `items.studyDescription` (string)
    Example: "Example description"

  - `nextToken` (null,string)
    Opaque continuation token to fetch the next page, when more results are available.
    Example: "Example nextToken"

## Response 400 fields (application/problem+json):

  - `type` (string)
    Stable error type identifier (urn:qubs:integrations:...). For each response, the type matches the HTTP status.
    Enum: "urn:qubs:integrations:bad-request"

  - `title` (null,string)
    Short, human-readable summary of the error.
    Example: "Example title"

  - `status` (integer)
    HTTP status code for this error response.
    Example: 400

  - `detail` (null,string)
    Detailed description of the error.
    Example: "Example detail"

  - `instance` (null,string)
    Request path for this error.
    Example: "Example instance"

  - `requestId` (string)
    Request correlation identifier for support. Also returned as the X-Correlation-Id response header.
    Example: "4b7f0a91b4f54f2a"

## Response 401 fields (application/problem+json):

  - `type` (string)
    Stable error type identifier (urn:qubs:integrations:...). For each response, the type matches the HTTP status.
    Enum: "urn:qubs:integrations:unauthorized"

  - `title` (null,string)
    Short, human-readable summary of the error.
    Example: "Example title"

  - `status` (integer)
    HTTP status code for this error response.
    Example: 401

  - `detail` (null,string)
    Detailed description of the error.
    Example: "Example detail"

  - `instance` (null,string)
    Request path for this error.
    Example: "Example instance"

  - `requestId` (string)
    Request correlation identifier for support. Also returned as the X-Correlation-Id response header.
    Example: "4b7f0a91b4f54f2a"

## Response 403 fields (application/problem+json):

  - `type` (string)
    Stable error type identifier (urn:qubs:integrations:...). For each response, the type matches the HTTP status.
    Enum: "urn:qubs:integrations:forbidden"

  - `title` (null,string)
    Short, human-readable summary of the error.
    Example: "Example title"

  - `status` (integer)
    HTTP status code for this error response.
    Example: 403

  - `detail` (null,string)
    Detailed description of the error.
    Example: "Example detail"

  - `instance` (null,string)
    Request path for this error.
    Example: "Example instance"

  - `requestId` (string)
    Request correlation identifier for support. Also returned as the X-Correlation-Id response header.
    Example: "4b7f0a91b4f54f2a"

## Response 429 fields (application/problem+json):

  - `type` (string)
    Stable error type identifier (urn:qubs:integrations:...). For each response, the type matches the HTTP status.
    Enum: "urn:qubs:integrations:too-many-requests"

  - `title` (null,string)
    Short, human-readable summary of the error.
    Example: "Example title"

  - `status` (integer)
    HTTP status code for this error response.
    Example: 429

  - `detail` (null,string)
    Detailed description of the error.
    Example: "Example detail"

  - `instance` (null,string)
    Request path for this error.
    Example: "Example instance"

  - `requestId` (string)
    Request correlation identifier for support. Also returned as the X-Correlation-Id response header.
    Example: "4b7f0a91b4f54f2a"

## Response 500 fields (application/problem+json):

  - `type` (string)
    Stable error type identifier (urn:qubs:integrations:...). For each response, the type matches the HTTP status.
    Enum: "urn:qubs:integrations:server-error"

  - `title` (null,string)
    Short, human-readable summary of the error.
    Example: "Example title"

  - `status` (integer)
    HTTP status code for this error response.
    Example: 500

  - `detail` (null,string)
    Detailed description of the error.
    Example: "Example detail"

  - `instance` (null,string)
    Request path for this error.
    Example: "Example instance"

  - `requestId` (string)
    Request correlation identifier for support. Also returned as the X-Correlation-Id response header.
    Example: "4b7f0a91b4f54f2a"