Skip to content

Create a comment for a pending reporting appointment

Request

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

Idempotency: supports the Idempotency-Key header. Best-effort process-local deduplication only, with a cache lifetime of up to 24 hours. A cached identical request replays its response; a cached key with a different payload returns 409. Eviction, restarts, different instances or concurrent requests can still create duplicates. Verify existing comments after an uncertain outcome before retrying; retain the original key and payload.

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

Security
Bearer
Path
domainstringrequired

Partner domain identifier for the organisation/tenant. Your bearer token is scoped to one or more domains and requests outside that scope are rejected.

Example:acme
appointmentIdstringrequired

Opaque appointment identifier within the specified domain. Preserve the value exactly as returned; values may look numeric but are not guaranteed to be numeric, so do not parse as an integer.

Example:200006
Headers
X-Correlation-Idstring

Request correlation identifier. Echoes the incoming X-Correlation-Id header when provided.

Example:4b7f0a91b4f54f2a
Idempotency-Keystring

Optional key for best-effort process-local deduplication. Reuse the original key and payload, but duplicates remain possible after eviction, restarts, on another instance or with concurrent requests. See endpoint notes for cache lifetimes and recovery guidance.

Example:cd4a859c7a1f4b44b765a8fe17bb44c1
Bodyapplication/jsonrequired
commentTextstring, non-emptyrequired

Comment text. Required; blank values are rejected.

Example:"Example commentText"
commentTypenull or 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"
Example:"AC"
isAlertnull or boolean

Whether this comment should be treated as an alert.

Example:true
commentDateTimenull or string, (date-time)

When the comment was created (UTC) when available.

Example:"2020-01-01T00:00:00Z"
curl -i -X POST \
  https://partnerdocs.qubs.io/_mock/openapi/integrations/v1/acme/reporting/appointments/200006/comments \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cd4a859c7a1f4b44b765a8fe17bb44c1' \
  -H 'X-Correlation-Id: 4b7f0a91b4f54f2a' \
  -d '{
    "commentText": "Please prioritize this study.",
    "commentType": "AA",
    "isAlert": true,
    "commentDateTime": "2025-01-10T02:03:04Z"
  }'

Responses

Created

Headers
X-Correlation-Idstring

Request correlation identifier. Echoes the incoming X-Correlation-Id header when provided.

Example:"4b7f0a91b4f54f2a"
Bodyapplication/json
guidstringrequired

Comment GUID.

Example:"123"
commentTypestringrequired

Comment type. One of: AC (Appointment Comment), AA (Appointment Alert), PC (Patient Comment), PA (Patient Alert).

Enum:"AC""AA""PC""PA"
Example:"AC"
appointmentIdstring

Opaque appointment identifier for appointment comments; empty for patient-level comments.

Example:"123"
patientIdstring

Patient identifier associated with the comment when available.

Example:"123"
commentTextstring

Comment text.

Example:"Example commentText"
commentDateTimenull or string, (date-time)

When the comment was created (UTC) when available.

Example:"2020-01-01T00:00:00Z"
isAlertboolean

Whether this comment should be treated as an alert.

Example:true
commentByobject(UserSummaryResponse)

Who created the comment when available.

lastModifiedDateTimenull or string, (date-time)

When the comment was last modified (UTC).

Example:"2020-01-01T00:00:00Z"
Response
{
  "guid": "ed6ef45a-4e3d-41b2-8049-7aec53bb9ab1",
  "commentType": "AA",
  "appointmentId": "200006",
  "patientId": "220000",
  "commentText": "Please prioritize this study.",
  "commentDateTime": "2025-01-10T02:03:04Z",
  "isAlert": true,
  "commentBy": {
    "username": "mbrown",
    "firstName": "Maya",
    "initials": "MB",
    "lastName": "Brown",
    "role": "Reception"
  },
  "lastModifiedDateTime": "2025-01-10T02:03:04Z"
}