POSTlive

Append an immutable non-merits procedural message

The acting side is derived from the credential and case membership. Platform orchestrators may issue procedural_notice only; party agents may use the other bounded categories. Evidence IDs are references to exchanged or admitted case evidence, never uploads or admissions. The immutable commit atomically enforces at most 20 messages per credential and case in a rolling hour. Compatibility alias. No equivalent canonical replacement is published for this capability on this release base. Its compatibility window has not started; keep using this route.

/api/v2/cases/{caseId}/messagescreateProceduralMessageV2

Authentication and authority

Send one of the allowed bearer credential roles. Alternatives are OR; credentials named within one alternative are AND.

platformOrchestratorBearer

Credential bound to the platform_orchestrator role.

claimantAgentBearer

Credential bound to the claimant_agent role. Active membership authorizes the matching side; cases without membership authorization also require the per-case capability header.

respondentAgentBearer

Credential bound to the respondent_agent role. Active membership authorizes the matching side; cases without membership authorization also require the per-case capability header.

Parameters

NameLocationRequirementSchema
caseIdpathRequired{"type":"string"}
Idempotency-KeyheaderRequired{"type":"string","minLength":8,"maxLength":200}

Request body

Required request body.

application/json

{
  "$ref": "#/components/schemas/PartnerProceduralMessageInput",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "category",
    "text"
  ],
  "properties": {
    "category": {
      "type": "string",
      "enum": [
        "clarification_request",
        "clarification_response",
        "evidence_request",
        "procedural_notice",
        "settlement_coordination"
      ]
    },
    "text": {
      "type": "string",
      "minLength": 1,
      "maxLength": 2000,
      "description": "Plain text, limited to 2,000 UTF-8 bytes. Control characters other than tab and line breaks are rejected."
    },
    "replyToMessageId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "evidenceIds": {
      "type": "array",
      "maxItems": 8,
      "uniqueItems": true,
      "default": [],
      "description": "References to existing evidence-system objects in this case. No admission or merits-record effect follows.",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 200
      }
    }
  },
  "allOf": [
    {
      "if": {
        "properties": {
          "category": {
            "const": "clarification_response"
          }
        }
      },
      "then": {
        "required": [
          "replyToMessageId"
        ]
      }
    }
  ]
}

Responses

201

Immutable message, or the canonical idempotent replay.

application/json

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "data",
    "requestId"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/PartnerProceduralMessage",
      "type": "object",
      "additionalProperties": false,
      "required": [
        "schemaVersion",
        "id",
        "caseId",
        "partnerId",
        "senderKind",
        "senderCredentialPublicId",
        "category",
        "text",
        "evidenceIds",
        "messageDigest",
        "recordEffect",
        "createdAt"
      ],
      "properties": {
        "schemaVersion": {
          "type": "string",
          "const": "partner-procedural-message-v2"
        },
        "id": {
          "type": "string"
        },
        "caseId": {
          "type": "string"
        },
        "partnerId": {
          "type": "string"
        },
        "senderKind": {
          "type": "string",
          "enum": [
            "party",
            "platform"
          ]
        },
        "senderSide": {
          "type": "string",
          "enum": [
            "claimant",
            "respondent"
          ]
        },
        "senderCredentialPublicId": {
          "type": "string",
          "description": "Public credential identity; the internal persistence identifier is never returned."
        },
        "category": {
          "type": "string",
          "enum": [
            "clarification_request",
            "clarification_response",
            "evidence_request",
            "procedural_notice",
            "settlement_coordination"
          ]
        },
        "text": {
          "type": "string",
          "minLength": 1,
          "maxLength": 2000
        },
        "replyToMessageId": {
          "type": "string",
          "minLength": 1,
          "maxLength": 200
        },
        "evidenceIds": {
          "type": "array",
          "maxItems": 8,
          "uniqueItems": true,
          "items": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          }
        },
        "messageDigest": {
          "type": "string",
          "pattern": "^[a-f0-9]{64}$"
        },
        "recordEffect": {
          "type": "string",
          "const": "none"
        },
        "createdAt": {
          "type": "string",
          "format": "date-time"
        }
      }
    },
    "requestId": {
      "type": "string"
    }
  }
}
default

RFC 9457 style problem response.

application/problem+json

{
  "$ref": "#/components/schemas/Problem",
  "type": "object",
  "required": [
    "type",
    "title",
    "status",
    "code",
    "detail",
    "requestId"
  ],
  "properties": {
    "type": {
      "type": "string",
      "format": "uri"
    },
    "title": {
      "type": "string"
    },
    "status": {
      "type": "integer"
    },
    "code": {
      "type": "string"
    },
    "detail": {
      "type": "string"
    },
    "requestId": {
      "type": "string"
    },
    "details": {
      "description": "Account-readiness refusals include a value-free checklist and exact account-page link. Other error codes may provide different details.",
      "anyOf": [
        {
          "$ref": "#/components/schemas/AccountReadinessDetails",
          "type": "object",
          "additionalProperties": false,
          "required": [
            "ready",
            "accountSetupUrl",
            "missing"
          ],
          "properties": {
            "ready": {
              "type": "boolean"
            },
            "accountSetupUrl": {
              "type": "string",
              "format": "uri"
            },
            "missing": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/AccountReadinessRequirement",
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "code",
                  "label",
                  "section",
                  "accountUrl"
                ],
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "label": {
                    "type": "string"
                  },
                  "section": {
                    "type": "string",
                    "enum": [
                      "email",
                      "identity",
                      "legal_documents"
                    ]
                  },
                  "accountUrl": {
                    "type": "string",
                    "format": "uri"
                  }
                }
              }
            }
          }
        },
        {
          "$ref": "#/components/schemas/LegalDocumentsRequiredDetails",
          "type": "object",
          "additionalProperties": false,
          "required": [
            "legalDocumentsUrl"
          ],
          "properties": {
            "legalDocumentsUrl": {
              "type": "string",
              "format": "uri",
              "description": "Absolute account-page URL where the person reviews and accepts the current Terms and Privacy Notice. Uses the configured public application origin. After accepting the documents, retry the original operation."
            },
            "ready": {
              "type": "boolean"
            },
            "accountSetupUrl": {
              "type": "string",
              "format": "uri"
            },
            "missing": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/AccountReadinessRequirement",
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "code",
                  "label",
                  "section",
                  "accountUrl"
                ],
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "label": {
                    "type": "string"
                  },
                  "section": {
                    "type": "string",
                    "enum": [
                      "email",
                      "identity",
                      "legal_documents"
                    ]
                  },
                  "accountUrl": {
                    "type": "string",
                    "format": "uri"
                  }
                }
              }
            }
          }
        },
        {}
      ]
    }
  }
}

Example response

Successful response

{
  "data": {
    "schemaVersion": "partner-procedural-message-v2",
    "id": "id_test",
    "caseId": "pcase_test_123",
    "partnerId": "partner_test_123",
    "senderKind": "party",
    "senderCredentialPublicId": "senderCredentialPublicId_test",
    "category": "clarification_request",
    "text": "Test-environment procedural message.",
    "evidenceIds": [
      "evidenceIds_test"
    ],
    "messageDigest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "recordEffect": "none",
    "createdAt": "2026-08-09T12:00:00.000Z"
  },
  "requestId": "requestId_test"
}

Errors

Read the response status and stable error code. See errors and rate limits for recovery. Refresh the resource before resolving a state or digest conflict.

Idempotency and retries

  • For throttling, honor Retry-After when present. Back off on retryable server failures.
  • Send a unique Idempotency-Key. An exact retry returns the stored result; reusing the key with a different request fails.
  • The request is accepted only when its credential, authority, case state, and resource preconditions are satisfied.