POSTpartial

Validate or execute the authorized settlement action

Requires a credential with the dedicated settlement:execute capability bound to the exact adapter. The action is derived from the served evaluation outcome, never supplied by the caller. Dry runs append a validated receipt; live calls append an immutable caller attempt linked to one server-derived business-operation journal. Different caller idempotency keys cannot resubmit the same binding, operative Award revision/hash, and action. Unknown provider outcomes require reconciliation before any terminal result is reported.

/api/cases/{id}/settlement-executionsexecuteSettlementCanonical

Authentication and authority

Use one listed account-session, scoped OAuth, or partner credential alternative. Account tokens retain the approving account’s authority. Cookie-authenticated writes require same-origin authorization. Alternatives are OR; schemes in one alternative are AND.

settlementAdapterBearer

Credential carrying only settlement:execute and bound to one exact adapter resource.

CanonicalPartnerBearer

CanonicalSession

AccountOAuth

Account tokens authorize only their approving account and case scope. S256 PKCE is mandatory on the code flow. Explicit reacceptance is required after Rules/disclosure changes.

Parameters

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

Request body

Required request body.

application/json

{
  "oneOf": [
    {
      "$ref": "#/components/schemas/PartnerSettlementExecutionInput",
      "type": "object",
      "additionalProperties": false,
      "required": [
        "bindingDigest"
      ],
      "properties": {
        "bindingDigest": {
          "type": "string",
          "pattern": "^[a-f0-9]{64}$"
        },
        "dryRun": {
          "type": "boolean",
          "default": false
        }
      }
    },
    {
      "$ref": "#/components/schemas/AwardExecutionCommand",
      "discriminator": {
        "propertyName": "action"
      },
      "oneOf": [
        {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "action",
            "awardHash"
          ],
          "properties": {
            "action": {
              "type": "string",
              "enum": [
                "initialize"
              ]
            },
            "awardHash": {
              "type": "string"
            }
          }
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "action",
            "awardHash"
          ],
          "properties": {
            "action": {
              "type": "string",
              "enum": [
                "request_release"
              ]
            },
            "awardHash": {
              "type": "string"
            }
          }
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "action",
            "awardHash",
            "description"
          ],
          "properties": {
            "action": {
              "type": "string",
              "enum": [
                "report_performance"
              ]
            },
            "awardHash": {
              "type": "string"
            },
            "description": {
              "type": "string",
              "minLength": 1,
              "maxLength": 4000
            },
            "reference": {
              "type": "string",
              "minLength": 1,
              "maxLength": 500
            }
          }
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "action",
            "awardHash",
            "reportId"
          ],
          "properties": {
            "action": {
              "type": "string",
              "enum": [
                "acknowledge"
              ]
            },
            "awardHash": {
              "type": "string"
            },
            "reportId": {
              "type": "string",
              "minLength": 1,
              "maxLength": 100
            },
            "reason": {
              "type": "string",
              "minLength": 1,
              "maxLength": 4000
            }
          }
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "action",
            "awardHash",
            "reportId"
          ],
          "properties": {
            "action": {
              "type": "string",
              "enum": [
                "dispute"
              ]
            },
            "awardHash": {
              "type": "string"
            },
            "reportId": {
              "type": "string",
              "minLength": 1,
              "maxLength": 100
            },
            "reason": {
              "type": "string",
              "minLength": 1,
              "maxLength": 4000
            }
          }
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "action",
            "awardHash",
            "reason"
          ],
          "properties": {
            "action": {
              "type": "string",
              "enum": [
                "will_not_execute"
              ]
            },
            "awardHash": {
              "type": "string"
            },
            "reason": {
              "type": "string",
              "minLength": 1,
              "maxLength": 4000
            }
          }
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "action",
            "awardHash",
            "reference"
          ],
          "properties": {
            "action": {
              "type": "string",
              "enum": [
                "partner_receipt"
              ]
            },
            "awardHash": {
              "type": "string"
            },
            "reference": {
              "type": "string",
              "minLength": 1,
              "maxLength": 500
            }
          }
        }
      ]
    }
  ]
}

Responses

201

Legacy digest input returns an immutable attempt; action input returns the canonical Award execution resource.

application/json

{
  "type": "object",
  "required": [
    "data",
    "requestId"
  ],
  "properties": {
    "data": {
      "oneOf": [
        {
          "$ref": "#/components/schemas/PartnerSettlementAttempt",
          "type": "object",
          "additionalProperties": false,
          "required": [
            "id",
            "partnerId",
            "caseId",
            "bindingId",
            "bindingDigest",
            "evaluationDigest",
            "dispositionId",
            "awardRevision",
            "awardHash",
            "outcomeCode",
            "action",
            "amountMinorUnits",
            "allocations",
            "currency",
            "dryRun",
            "status",
            "createdAt"
          ],
          "properties": {
            "id": {
              "type": "string"
            },
            "partnerId": {
              "type": "string"
            },
            "caseId": {
              "type": "string"
            },
            "bindingId": {
              "type": "string"
            },
            "operationId": {
              "type": "string"
            },
            "operationKey": {
              "type": "string",
              "pattern": "^[a-f0-9]{64}$"
            },
            "bindingDigest": {
              "type": "string",
              "pattern": "^[a-f0-9]{64}$"
            },
            "evaluationDigest": {
              "type": "string",
              "pattern": "^[a-f0-9]{64}$"
            },
            "dispositionId": {
              "type": "string"
            },
            "awardRevision": {
              "type": "integer",
              "minimum": 0
            },
            "awardHash": {
              "type": "string",
              "pattern": "^[a-f0-9]{64}$"
            },
            "outcomeCode": {
              "type": "string"
            },
            "action": {
              "type": "string",
              "enum": [
                "release_to_claimant",
                "release_to_respondent",
                "allocate_by_award",
                "none"
              ]
            },
            "amountMinorUnits": {
              "type": "string",
              "pattern": "^(0|[1-9][0-9]{0,77})$"
            },
            "allocations": {
              "type": "array",
              "maxItems": 2,
              "items": {
                "$ref": "#/components/schemas/PartnerSettlementAllocation",
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "recipient",
                  "principalId",
                  "amountMinorUnits"
                ],
                "properties": {
                  "recipient": {
                    "type": "string",
                    "enum": [
                      "claimant",
                      "respondent"
                    ]
                  },
                  "principalId": {
                    "type": "string"
                  },
                  "amountMinorUnits": {
                    "type": "string",
                    "pattern": "^(0|[1-9][0-9]{0,77})$"
                  }
                }
              }
            },
            "currency": {
              "type": "string",
              "const": "USD"
            },
            "dryRun": {
              "type": "boolean"
            },
            "status": {
              "type": "string",
              "enum": [
                "validated",
                "manual_action_required",
                "callback_required",
                "completed",
                "failed",
                "blocked",
                "unknown_outcome"
              ]
            },
            "adapterReceipt": {
              "type": "object",
              "additionalProperties": {
                "type": "string"
              }
            },
            "failureCode": {
              "type": "string"
            },
            "createdAt": {
              "type": "string",
              "format": "date-time"
            }
          }
        },
        {
          "$ref": "#/components/schemas/AwardExecutionResource",
          "type": "object",
          "required": [
            "id",
            "caseId",
            "awardId",
            "awardHash",
            "mode",
            "status",
            "paymentConfirmed",
            "executedBy",
            "receipt",
            "reports",
            "links"
          ],
          "properties": {
            "provider": {
              "type": "string"
            },
            "providerOperation": {
              "type": "object",
              "required": [
                "id",
                "status",
                "attempts"
              ],
              "properties": {
                "id": {
                  "type": "string"
                },
                "status": {
                  "enum": [
                    "prepared",
                    "submitting",
                    "unknown",
                    "confirmed",
                    "needs_action"
                  ]
                },
                "attempts": {
                  "type": "integer",
                  "minimum": 0
                }
              }
            },
            "reconciliation": {
              "type": "object",
              "required": [
                "state",
                "checkedAt",
                "recovery"
              ],
              "properties": {
                "state": {
                  "enum": [
                    "pending",
                    "unknown",
                    "confirmed",
                    "needs_action",
                    "reversed"
                  ]
                },
                "checkedAt": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "format": "date-time"
                },
                "recovery": {
                  "type": [
                    "object",
                    "null"
                  ],
                  "properties": {
                    "reason": {
                      "enum": [
                        "vacated",
                        "superseded",
                        "provider_reversal"
                      ]
                    },
                    "status": {
                      "enum": [
                        "pending",
                        "reversed",
                        "needs_action"
                      ]
                    },
                    "detail": {
                      "type": "string"
                    },
                    "requestedAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "updatedAt": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            },
            "providerReceipts": {
              "type": "array",
              "items": {
                "type": "object",
                "required": [
                  "step",
                  "id",
                  "object",
                  "amount",
                  "currency",
                  "livemode",
                  "status"
                ],
                "properties": {
                  "step": {
                    "enum": [
                      "debit",
                      "transfer",
                      "reverse_transfer",
                      "refund_debit"
                    ]
                  },
                  "id": {
                    "type": "string"
                  },
                  "object": {
                    "enum": [
                      "charge",
                      "payment",
                      "transfer",
                      "transfer_reversal",
                      "refund"
                    ]
                  },
                  "amount": {
                    "type": "integer",
                    "minimum": 1
                  },
                  "currency": {
                    "const": "usd"
                  },
                  "livemode": {
                    "type": "boolean"
                  },
                  "source": {
                    "type": "string"
                  },
                  "destination": {
                    "type": "string"
                  },
                  "status": {
                    "type": "string"
                  }
                }
              }
            },
            "id": {
              "type": "string"
            },
            "caseId": {
              "type": "string"
            },
            "awardId": {
              "type": "string"
            },
            "awardHash": {
              "type": "string"
            },
            "mode": {
              "type": "string",
              "enum": [
                "partner_executed",
                "court_escrow",
                "external_provider",
                "decision_only"
              ]
            },
            "status": {
              "type": "string",
              "enum": [
                "decision_delivered",
                "execution_pending",
                "overdue",
                "will_not_execute",
                "not_automatically_executed",
                "performance_reported",
                "performance_acknowledged",
                "performance_disputed",
                "not_requested",
                "pending",
                "unknown_outcome",
                "needs_action",
                "blocked",
                "executed",
                "simulated",
                "reversal_pending",
                "reversed",
                "reversal_needs_action"
              ]
            },
            "paymentConfirmed": {
              "type": "boolean"
            },
            "executedBy": {
              "type": [
                "string",
                "null"
              ],
              "enum": [
                "partner",
                "peoples_court",
                "provider",
                null
              ]
            },
            "receipt": {
              "oneOf": [
                {
                  "$ref": "#/components/schemas/ExecutionReceipt",
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "adapter",
                    "action",
                    "txHashes",
                    "at"
                  ],
                  "properties": {
                    "adapter": {
                      "type": "string"
                    },
                    "action": {
                      "type": "string",
                      "enum": [
                        "capture",
                        "void",
                        "capture_partial",
                        "refund",
                        "refuse",
                        "complete",
                        "reject",
                        "distribute",
                        "partner_execute"
                      ]
                    },
                    "txHashes": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "detail": {
                      "type": "string"
                    },
                    "provenance": {
                      "$ref": "#/components/schemas/ExecutionReceiptProvenance"
                    }
                  }
                },
                {
                  "type": "null"
                }
              ]
            },
            "reports": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/ExecutionPerformanceReport",
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "id",
                  "by",
                  "description",
                  "reportedAt",
                  "responses"
                ],
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "by": {
                    "type": "string",
                    "enum": [
                      "claimant",
                      "respondent",
                      "partner"
                    ]
                  },
                  "description": {
                    "type": "string"
                  },
                  "reference": {
                    "type": "string"
                  },
                  "reportedAt": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "responses": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/ExecutionPerformanceResponse"
                    }
                  }
                }
              }
            },
            "attestation": {
              "oneOf": [
                {
                  "$ref": "#/components/schemas/ExecutionNonPerformanceAttestation",
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "reason",
                    "at"
                  ],
                  "properties": {
                    "reason": {
                      "type": "string"
                    },
                    "at": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                },
                {
                  "type": "null"
                }
              ]
            },
            "submissionAttempts": {
              "type": [
                "integer",
                "null"
              ],
              "minimum": 0,
              "description": "Durable adapter invocations, excluding reconciliation reads. Historical counts are null when unavailable. An invocation may stop before provider submission."
            },
            "deliveredAt": {
              "type": "string",
              "format": "date-time"
            },
            "overdueAt": {
              "type": [
                "string",
                "null"
              ],
              "format": "date-time"
            },
            "nextReconcileAt": {
              "type": [
                "string",
                "null"
              ],
              "format": "date-time"
            },
            "reminders": {
              "type": "integer",
              "minimum": 0
            },
            "createdAt": {
              "type": "string",
              "format": "date-time"
            },
            "updatedAt": {
              "type": "string",
              "format": "date-time"
            },
            "links": {
              "type": "object",
              "required": [
                "self",
                "case"
              ],
              "properties": {
                "self": {
                  "type": "string"
                },
                "case": {
                  "type": "string"
                }
              }
            }
          }
        }
      ]
    },
    "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"
    }
  }
}

Example response

Successful response

{
  "data": {
    "id": "id_test",
    "partnerId": "partner_test_123",
    "caseId": "pcase_test_123",
    "bindingId": "bindingId_test",
    "bindingDigest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "evaluationDigest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "dispositionId": "dispositionId_test",
    "awardRevision": 1,
    "awardHash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "outcomeCode": "outcomeCode_test",
    "action": "release_to_claimant",
    "amountMinorUnits": "12500",
    "allocations": [
      {
        "recipient": "claimant",
        "principalId": "principal_test_123",
        "amountMinorUnits": "12500"
      }
    ],
    "currency": "USD",
    "dryRun": false,
    "status": "validated",
    "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.