---
title: "Record the outcome of a claimed downstream commit attempt"
method: POST
path: "/v1/authority/grants/{grantId}/receipts"
---

# Record the outcome of a claimed downstream commit attempt

`POST /v1/authority/grants/{grantId}/receipts`

## Request

- Base URL: `https://api.decionis.com`
- URL: `https://api.decionis.com/v1/authority/grants/{grantId}/receipts`
- Auth: HTTP bearer

The handler of the deprecated alias `POST /v1/execution/finalize-token`,
with the same body, rules and responses: COMMITTED, FAILED or
INDETERMINATE, effect confirmation only from accepted digest-bound
`effect_evidence`, a verifying provider's `effect_receipt` recorded as
presented, and lease-expiry recorded as INDETERMINATE. The verified
token's `jti` must be `{grantId}`; otherwise the answer is 409
`GRANT_ID_MISMATCH` and nothing is recorded.

A permit-style platform may add `native_receipt`, what the platform
itself recorded when it carried the action out. It is recorded as
`downstream_evidence.native_receipt`, so the claim and its commit
evidence carry it; it is the executor's report of the attempt and
never effect confirmation by itself.

## Request body

- ExecutionFinalizeRequest
  - `execution_token` string, required
  - `claim_token` string, required
  - `outcome` 'COMMITTED' | 'FAILED' | 'INDETERMINATE', required
  - `commit_correlation_id` string, required
  - `downstream_evidence` object: Free-form legacy evidence; never interpreted as effect confirmation.
  - `native_receipt` NativeReceipt: What a permit-style platform recorded when it carried the action out (a posted journal, an acknowledged order). Recorded as `downstream_evidence.native_receipt`, replacing any value the executor put there; the executor's report of the attempt, never effect confirmation by itself.
    - `platform` string, required
    - `kind` string, required
    - `reference` string, required
    - `status` string, required
    - `observed_at` string, date-time, required
    - `digest` string
  - `effect_evidence` union: When effect evidence is present for a Protocol 1.1 grant it must use the Protocol 1.1 shape. Effect confirmation remains optional. The legacy shape remains accepted only for historical grants and keeps its original verification semantics.
    - EffectEvidence: Optional Protocol 1.1 observation evidence. COMMITTED remains an executor-reported finalization state and is not CONFIRMED without a qualifying record. Raw provider responses should remain outside the evidence artifact; use commitments and immutable references.
      - `version` '1.0', required
      - `status` 'CONFIRMED' | 'UNCONFIRMED', required
      - `observation_method` 'DOWNSTREAM_ACK' | 'READ_AFTER_WRITE' | 'EVENT_CONFIRMATION' | 'STATE_RECONCILIATION' | 'SIGNED_RECEIPT' | 'EXTERNAL_ATTESTATION' | 'HUMAN_VALIDATION', required: Versioned identifier for how the downstream effect was observed. DOWNSTREAM_ACK is weak evidence and cannot independently confirm an effect.
      - `observer` object, nullable, required
        - `id` string, required
        - `version` string, nullable, required
      - `expected_effect_digest` string, required
      - `observed_effect_digest` string, nullable, required: For CONFIRMED evidence, must equal expected_effect_digest.
      - `observed_at` string, date-time, nullable, required
      - `evidence_digest` string, nullable, required
      - `evidence_reference` string, nullable, required
      - `execution_correlation_id` string, required: Must exactly equal the bound commit correlation identifier.
    - ExecutionEffectEvidence: Deployed pre-Protocol-1.1 effect record. It remains accepted and verifiable for grants issued under its original request/outcome-binding rules. Protocol 1.1 grants reject this shape to prevent an evidence semantics downgrade. New integrations should emit EffectEvidence.
      - `effect_schema_version` '1.0', required
      - `status` 'CONFIRMED' | 'FAILED' | 'INDETERMINATE', required: CONFIRMED means the execution gate directly observed a digestible response.
      - `request_digest` string, required: Must equal the execution payload digest signed into the grant.
      - `response_digest` string, nullable, required: Required when status is CONFIRMED; null otherwise.
      - `digest_algorithm` 'SHA-256', required
      - `canonicalization_profile` string, required: Canonicalization profile for the response digest when present; otherwise the request digest profile.
      - `external_reference` string, nullable, required
      - `observation_mode` 'GATE_OBSERVED' | 'RUNTIME_REPORTED', required
      - `observer` object, required
        - `id` string, required
        - `version` string, required
      - `observed_at` string, date-time, required
      - `metadata_digest` string, nullable, required
  - `effect_receipt` string: A verifying provider's effect receipt, forwarded by the executor exactly as the provider returned it: a compact EdDSA JWS whose protected header `typ` is `decionis-effect-receipt+jwt` and whose payload is `EffectReceiptClaims`. Verified against the organisation's registered provider keys and recorded whatever the verdict; never a reason to refuse the finalization.

## Response `200`

Claim finalized and commit evidence recorded or queued for recovery

- ExecutionFinalizeResponse
  - `finalized` boolean, required
  - `outcome` 'COMMITTED' | 'FAILED' | 'INDETERMINATE'
  - `evidence_recorded` boolean: Compatibility field reporting immediate Decision Chain acknowledgement.
  - `evidence_durably_queued` boolean: True when commit evidence was persisted transactionally with the terminal claim state, including lease-expiry INDETERMINATE.
  - `decision_chain_evidence_recorded` boolean: True when the Protocol Decision Chain had already acknowledged the commit evidence when this response was formed; false is delivered asynchronously from the durable outbox.
  - `effect_evidence_recorded` boolean
  - `effect_confirmation` 'CONFIRMED' | 'UNCONFIRMED'
  - `effect_receipt` object: Present when the request carried an `effect_receipt`.
    - `verified` boolean, required: True when the receipt's signature verified under a registered provider key and its claims describe this grant and this claim.
    - `verification_code` 'EFFECT_RECEIPT_VERIFIED' | 'EFFECT_RECEIPT_MALFORMED' | 'EFFECT_RECEIPT_KEY_UNKNOWN' | 'EFFECT_RECEIPT_SIGNATURE_INVALID' | 'EFFECT_RECEIPT_BINDING_MISMATCH' | 'EFFECT_RECEIPT_KEYS_UNAVAILABLE', required
    - `provider_key_id` string, nullable, required: The `kid` the receipt named, when it named one.
    - `recorded` boolean, required: True when the receipt was persisted in the commit evidence, which is whenever the claim finalized.
  - `reason_codes` string[], required

## Other responses

- `400`: Invalid finalization, native receipt or effect-evidence shape
- `401`: Structured API error
- `403`: Structured API error
- `409`: Invalid, replayed, non-claimed, or lease-expired authorization, or GRANT_ID_MISMATCH. An expired claim reports outcome INDETERMINATE and CLAIM_LEASE_EXPIRED.

---

[API](https://skmtc.dev/decionis/apis/decionis-policy-evaluation-api.md) · [All operations](https://skmtc.dev/decionis/apis/decionis-policy-evaluation-api/llms.txt) · [OpenAPI document](https://skmtc.dev/decionis/apis/decionis-policy-evaluation-api/revisions/357f5e459d0c?raw)