# List operational appointments by status for referrers and specialists

Returns operational appointments 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/operational/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)
    Operational appointments 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"

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

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

  - `items.arrivalDateTime` (null,string)
    Example: "2020-01-01T00:00:00Z"

  - `items.scanStartDateTime` (null,string)
    Example: "2020-01-01T00:00:00Z"

  - `items.scanEndDateTime` (null,string)
    Example: "2020-01-01T00:00:00Z"

  - `items.scanTotalTime` (null,number)
    Example: 1.23

  - `items.waitingTotalTime` (null,number)
    Example: 1.23

  - `items.examCodes` (array)
    Exam codes attached to the appointment.

  - `items.examCodes.examCodeId` (string, required)
    Unique exam code identifier.
    Example: "123"

  - `items.examCodes.key` (string, required)
    QUBS internal key for the exam code record.
    Example: "Example key"

  - `items.examCodes.site` (string, required)
    Site this exam code belongs to.
    Example: "Example site"

  - `items.examCodes.description` (string, required)
    Human-readable exam description.
    Example: "Example description"

  - `items.examCodes.domain` (string)
    Example: "Example domain"

  - `items.examCodes.category` (string)
    Example: "Example category"

  - `items.examCodes.colour` (string)
    Example: "Example colour"

  - `items.examCodes.totalDuration` (integer)
    Configured duration in minutes.
    Example: 1

  - `items.examCodes.showOnline` (boolean)
    Whether this exam is visible/available online.
    Example: true

  - `items.examCodes.lastModifiedDateTime` (null,string)
    Example: "2020-01-01T00:00:00Z"

  - `items.examCodes.extraInfo` (null,string)
    Example: "Example extraInfo"

  - `items.examCodes.onlineInfo` (null,string)
    Example: "Example onlineInfo"

  - `items.examCodes.preparations1` (null,string)
    Example: "Example preparations1"

  - `items.examCodes.order` (integer)
    Example: 1

  - `items.examCodes.worksheetId` (null,string)
    Example: "123"

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