Procedural messages

Messages let parties and the platform coordinate procedure: ask for clarification, request evidence, or give notice. They never become part of the merits record. One route, /api/cases/{id}/messages, serves two channels:

Channel	Used by	Selected with
`partner_notice`	Partner credentials	`?channel=partner_notice`. Required: omitting it returns `422 message_channel_required`.
`hosted_thread`	Account OAuth tokens and signed-in sessions	The default for accounts. Threads have their own body and visibility rules. See the message reference.

Send a partner notice

In the example dispute, the platform tells both parties that automatic refunds for the order are paused while the case is pending:

Shell

curl --fail-with-body -sS "https://peoplescourt.ai/api/cases/$CASE_ID/messages?channel=partner_notice" \
  -H "Authorization: Bearer $PLATFORM_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-1042-refund-hold-notice' \
  --data '{
    "category": "procedural_notice",
    "text": "Automatic refunds for order #1042 are paused while this case is pending."
  }'

Field	Rules
`category`	One of the categories below
`text`	Plain text, at most 2,000 UTF-8 bytes. The whole request is at most 16 KiB.
`replyToMessageId`	Optional. Required for `clarification_response`.
`evidenceIds`	Optional. Up to eight exchanged or admitted evidence items in the same case. A reference does not upload, admit, change, or reopen evidence.

Category	Sent by	Reply rule
`clarification_request`	Either party	Optional reply target
`clarification_response`	The opposing party	Must reply to a clarification request
`evidence_request`	Either party	Optional reply target
`procedural_notice`	Platform orchestrator only	Optional reply target
`settlement_coordination`	Either party	Optional reply target

The server derives the sender and side from the credential and case membership. Claimant and respondent credentials speak only for their own side. Sending requires messages:write and case access.

What a message changes

Nothing in the record. Every response carries recordEffect: "none". A message can be sent after the merits record freezes without changing the case revision, submissions, evidence, record digest, or Award inputs. Messages are immutable and are docketed without copying their text into audit events. Each one triggers a procedural_message_received webhook that carries no message text.

Limits and retries

A credential can send 20 messages per case in a rolling hour. The next one returns 429 message_rate_limit_exceeded with Retry-After. Every write requires an Idempotency-Key. After an uncertain response, resend the same body with the same key. See Errors and Rate limits.

Account threads

Account OAuth clients list threads with cases:read and post with messages:write, subject to current party access. A POST sends body, plus either threadId to reply or a thread category and visibility to open a new thread. PATCH with threadId closes a thread. Partner notice categories do not apply to account threads.