# Create a comment for a pending reporting appointment

Creates an appointment comment/alert for a pending reporting appointment.

Idempotency: supports the Idempotency-Key header. Reuse the same key with the same payload to receive the original response; reuse with a different payload returns 409 Conflict. Keys are retained for 24 hours. Without the header, retries can create duplicate comments.

Returns 404 when the appointment is not found or is not in the PENDING REPORTING status.

Endpoint: POST /integrations/v1/{domain}/reporting/appointments/{appointmentId}/comments
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"

  - `appointmentId` (string, required)
    Appointment identifier within the specified domain.
    Example: "A123456"

## Header parameters:

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

  - `Idempotency-Key` (string)
    Idempotency key for safely retrying POST requests. Use a stable ASCII token (recommend a UUID) up to 128 characters. Reuse the same key with the same request payload to receive the original response; reuse with a different payload returns 409 Conflict. For timeouts or transient errors, retry with the same key and exponential backoff.
    Example: "cd4a859c7a1f4b44b765a8fe17bb44c1"

## Request fields (application/json):

  - `commentText` (string, required)
    Comment text. Required; blank values are rejected.
    Example: "Example commentText"

  - `commentType` (null,string)
    Optional comment type. One of: AC (Appointment Comment), AA (Appointment Alert), PC (Patient Comment), PA (Patient Alert). Defaults to AA when isAlert is true, otherwise AC.
    Enum: "AC", "AA", "PC", "PA"

  - `isAlert` (null,boolean)
    Whether this comment should be treated as an alert.
    Example: true

  - `commentDateTime` (null,string)
    When the comment was created (UTC) when available.
    Example: "2020-01-01T00:00:00Z"

## Response 201 fields (application/json):

  - `guid` (string, required)
    Comment GUID.
    Example: "123"

  - `commentType` (string, required)
    Comment type. One of: AC (Appointment Comment), AA (Appointment Alert), PC (Patient Comment), PA (Patient Alert).
    Enum: "AC", "AA", "PC", "PA"

  - `appointmentId` (string)
    Appointment identifier for appointment comments; empty for patient-level comments.
    Example: "123"

  - `patientId` (string)
    Patient identifier associated with the comment when available.
    Example: "123"

  - `commentText` (string)
    Comment text.
    Example: "Example commentText"

  - `commentDateTime` (null,string)
    When the comment was created (UTC) when available.
    Example: "2020-01-01T00:00:00Z"

  - `isAlert` (boolean)
    Whether this comment should be treated as an alert.
    Example: true

  - `commentBy` (object)
    Who created the comment when available.

  - `commentBy.username` (string, required)
    User's unique username.
    Example: "Example Name"

  - `commentBy.firstName` (string)
    User's first name.
    Example: "Example Name"

  - `commentBy.initials` (string)
    User's initials when available.
    Example: "Example initials"

  - `commentBy.lastName` (string)
    User's last name.
    Example: "Example Name"

  - `commentBy.role` (string)
    User role when available.
    Example: "Example role"

  - `lastModifiedDateTime` (null,string)
    When the comment was last modified (UTC).
    Example: "2020-01-01T00:00:00Z"

## 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 404 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:not-found"

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

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

  - `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 409 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:conflict"

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

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

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