> For the complete documentation index, see [llms.txt](https://peoplescourt.ai/llms.txt). This page is also available as Markdown.

# Bind a case to one external settlement corpus

A platform orchestrator registers the USD-only binding only after bilateral authorization and while the dispute is in awaiting_submissions or awaiting_validation, with no Award. The server atomically checks the current dispute revision/status, derives immutable actor and authority-grant metadata, and binds that metadata with the evaluation digest, action subset, participant identities, adapter, and corpus limits. An exact idempotent replay remains valid after the registration window closes.

Reference

Execution

POST

partial

`/api/cases/{id}/settlement-binding`

`registerSettlementBindingCanonical`

## 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.

## Parameters

Name

Location

Requirement

Schema

`id`

path

Required

{"type":"string"}

`Idempotency-Key`

header

Required

{"type":"string","minLength":8,"maxLength":200}

## Request body

Required request body.

application/json

```json
{
  "$ref": "#/components/schemas/PartnerSettlementBindingInput",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "evaluationDigest",
    "externalReference",
    "adapter",
    "mode",
    "allowedActions",
    "corpus"
  ],
  "properties": {
    "evaluationDigest": {
      "type": "string",
      "pattern": "^[a-f0-9]{64}$"
    },
    "externalReference": {
      "type": "string",
      "minLength": 1,
      "maxLength": 500
    },
    "adapter": {
      "type": "string",
      "pattern": "^[A-Za-z0-9._:-]{1,200}$"
    },
    "mode": {
      "type": "string",
      "enum": [
        "manual_partner",
        "partner_callback",
        "platform_adapter"
      ]
    },
    "allowedActions": {
      "type": "array",
      "minItems": 1,
      "uniqueItems": true,
      "items": {
        "type": "string",
        "enum": [
          "release_to_claimant",
          "release_to_respondent",
          "allocate_by_award",
          "none"
        ]
      }
    },
    "corpus": {
      "$ref": "#/components/schemas/PartnerSettlementCorpus",
      "type": "object",
      "additionalProperties": false,
      "required": [
        "currency",
        "amountMinorUnits",
        "claimantPrincipalId",
        "respondentPrincipalId",
        "expiresAt"
      ],
      "properties": {
        "currency": {
          "type": "string",
          "const": "USD"
        },
        "amountMinorUnits": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,77})$"
        },
        "claimantPrincipalId": {
          "type": "string"
        },
        "respondentPrincipalId": {
          "type": "string"
        },
        "expiresAt": {
          "type": "string",
          "format": "date-time"
        }
      }
    }
  }
}
```

## Responses

### 201

Immutable settlement binding created or idempotently replayed.

application/json

```json
{
  "type": "object",
  "required": [
    "data",
    "requestId"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/PartnerSettlementBinding",
      "type": "object",
      "additionalProperties": false,
      "required": [
        "id",
        "partnerId",
        "caseId",
        "evaluationDigest",
        "externalReference",
        "adapter",
        "mode",
        "allowedActions",
        "corpus",
        "authority",
        "bindingDigest",
        "status",
        "createdAt"
      ],
      "properties": {
        "id": {
          "type": "string"
        },
        "partnerId": {
          "type": "string"
        },
        "caseId": {
          "type": "string"
        },
        "evaluationDigest": {
          "type": "string",
          "pattern": "^[a-f0-9]{64}$"
        },
        "externalReference": {
          "type": "string",
          "minLength": 1,
          "maxLength": 500
        },
        "adapter": {
          "type": "string",
          "pattern": "^[A-Za-z0-9._:-]{1,200}$"
        },
        "mode": {
          "type": "string",
          "enum": [
            "manual_partner",
            "partner_callback",
            "platform_adapter"
          ]
        },
        "allowedActions": {
          "type": "array",
          "minItems": 1,
          "uniqueItems": true,
          "items": {
            "type": "string",
            "enum": [
              "release_to_claimant",
              "release_to_respondent",
              "allocate_by_award",
              "none"
            ]
          }
        },
        "corpus": {
          "$ref": "#/components/schemas/PartnerSettlementCorpus",
          "type": "object",
          "additionalProperties": false,
          "required": [
            "currency",
            "amountMinorUnits",
            "claimantPrincipalId",
            "respondentPrincipalId",
            "expiresAt"
          ],
          "properties": {
            "currency": {
              "type": "string",
              "const": "USD"
            },
            "amountMinorUnits": {
              "type": "string",
              "pattern": "^(0|[1-9][0-9]{0,77})$"
            },
            "claimantPrincipalId": {
              "type": "string"
            },
            "respondentPrincipalId": {
              "type": "string"
            },
            "expiresAt": {
              "type": "string",
              "format": "date-time"
            }
          }
        },
        "authority": {
          "$ref": "#/components/schemas/PartnerSettlementBindingAuthority",
          "type": "object",
          "additionalProperties": false,
          "required": [
            "actorCredentialPublicId",
            "actorPrincipalId",
            "representedPrincipalId",
            "actorRole",
            "authorityGrantId",
            "requiredScope",
            "authorityAct",
            "authorizedAt"
          ],
          "properties": {
            "actorCredentialPublicId": {
              "type": "string"
            },
            "actorPrincipalId": {
              "type": "string"
            },
            "representedPrincipalId": {
              "type": "string"
            },
            "actorRole": {
              "type": "string",
              "const": "platform_orchestrator"
            },
            "authorityGrantId": {
              "type": "string"
            },
            "requiredScope": {
              "type": "string",
              "const": "settlement:bindings:manage"
            },
            "authorityAct": {
              "type": "string",
              "const": "settle_dispute"
            },
            "authorizedAt": {
              "type": "string",
              "format": "date-time"
            }
          }
        },
        "bindingDigest": {
          "type": "string",
          "pattern": "^[a-f0-9]{64}$",
          "description": "SHA-256 binding the caller-supplied corpus contract and the server-derived immutable authority metadata."
        },
        "status": {
          "type": "string",
          "enum": [
            "active",
            "expired",
            "revoked"
          ]
        },
        "createdAt": {
          "type": "string",
          "format": "date-time"
        }
      }
    },
    "requestId": {
      "type": "string"
    }
  }
}
```

### default

RFC 9457 style problem response.

application/problem+json

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

```json
{
  "data": {
    "id": "id_test",
    "partnerId": "partner_test_123",
    "caseId": "pcase_test_123",
    "evaluationDigest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "externalReference": "partner_reference_123",
    "adapter": "adapter_test",
    "mode": "manual_partner",
    "allowedActions": [
      "release_to_claimant"
    ],
    "corpus": {
      "currency": "USD",
      "amountMinorUnits": "12500",
      "claimantPrincipalId": "principal_test_123",
      "respondentPrincipalId": "principal_test_123",
      "expiresAt": "2026-08-09T12:00:00.000Z"
    },
    "authority": {
      "actorCredentialPublicId": "actorCredentialPublicId_test",
      "actorPrincipalId": "principal_test_123",
      "representedPrincipalId": "principal_test_123",
      "actorRole": "platform_orchestrator",
      "authorityGrantId": "grant_test_123",
      "requiredScope": "settlement:bindings:manage",
      "authorityAct": "settle_dispute",
      "authorizedAt": "2026-08-09T12:00:00.000Z"
    },
    "bindingDigest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "status": "active",
    "createdAt": "2026-08-09T12:00:00.000Z"
  },
  "requestId": "requestId_test"
}
```

## Errors

Read the response status and stable error code. See [errors](https://peoplescourt.ai/docs/api/errors.md) and [rate limits](https://peoplescourt.ai/docs/api/rate-limits.md) 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.

**Likely next action:** [Validate the settlement action with a dry run →](https://peoplescourt.ai/docs/api/reference/executeSettlementCanonical.md)

## Request examples

Use `https://peoplescourt.ai` with the test credential issued for your integration.

```sh
curl --request POST \
  --url 'https://peoplescourt.ai/api/cases/pcase_test_123/settlement-binding' \
  --header 'Authorization: Bearer pk_test_replace_me' \
  --header 'Idempotency-Key: idem_test_12345678' \
  --header 'Content-Type: application/json' \
  --data '{
  "evaluationDigest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "externalReference": "partner_reference_123",
  "adapter": "adapter_test",
  "mode": "manual_partner",
  "allowedActions": [
    "release_to_claimant"
  ],
  "corpus": {
    "currency": "USD",
    "amountMinorUnits": "12500",
    "claimantPrincipalId": "principal_test_123",
    "respondentPrincipalId": "principal_test_123",
    "expiresAt": "2026-08-09T12:00:00.000Z"
  }
}'
```

```ts
const input = {
  "evaluationDigest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "externalReference": "partner_reference_123",
  "adapter": "adapter_test",
  "mode": "manual_partner",
  "allowedActions": [
    "release_to_claimant"
  ],
  "corpus": {
    "currency": "USD",
    "amountMinorUnits": "12500",
    "claimantPrincipalId": "principal_test_123",
    "respondentPrincipalId": "principal_test_123",
    "expiresAt": "2026-08-09T12:00:00.000Z"
  }
};

const response = await fetch("https://peoplescourt.ai/api/cases/pcase_test_123/settlement-binding", {
  method: "POST",
  headers: {
    "Authorization": "Bearer pk_test_replace_me",
    "Idempotency-Key": "idem_test_12345678",
    "Content-Type": "application/json"
  },
  body: JSON.stringify(input),
});
if (!response.ok) throw await response.json();
const result = await response.json();
```

```python
import requests

response = requests.post(
    "https://peoplescourt.ai/api/cases/pcase_test_123/settlement-binding",
    headers={
      "Authorization": "Bearer pk_test_replace_me",
      "Idempotency-Key": "idem_test_12345678",
      "Content-Type": "application/json"
    },
    json={"evaluationDigest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "externalReference": "partner_reference_123", "adapter": "adapter_test", "mode": "manual_partner", "allowedActions": ["release_to_claimant"], "corpus": {"currency": "USD", "amountMinorUnits": "12500", "claimantPrincipalId": "principal_test_123", "respondentPrincipalId": "principal_test_123", "expiresAt": "2026-08-09T12:00:00.000Z"}},
    timeout=30,
)
response.raise_for_status()
result = response.json()
```