Settlement jobs
Agree on acceptance conditions, inspect evidence and record a reproducible verdict before anyone executes a payment.
What this API does
A committed job records what would count as delivery before the provider begins.
Elpis stores that condition and its canonical hash. When evidence arrives, the evaluator returns release, refund or hold. A job verdict is an application record; it is not the same as an on-chain transfer.
job commitment → delivered evidence → decision record
decision + escrow authority → chain transaction → receiptCommitments cannot silently change
A job can have one or more acceptance checks. The condition is hashed when committed; verification recalculates that hash and refuses a mismatched stored condition.
A unique idempotency key can protect creation retries. Reusing it with different conditions or provider details now produces 409 idempotency_conflict.
The full request body and a reproducible SHA-256 example are in Your first verified job.
Three possible decisions
| Verdict | Meaning | Money movement |
|---|---|---|
release | Presented evidence satisfies the checks for this evaluator. | Requires separate authorized execution. |
refund | The condition contradicted evidence or an applicable deadline rule returned refund. | An actual refund requires the underlying escrow flow. |
hold | A required check is incomplete, pending or cannot be trusted. | No release. |
External attestations
Signature, witness and oracle checks require authentication of the claimed source. Strings such as signers: ["0x..."] or arbitrary oracleValues are only assertions, not verified inputs.
The public preview and standalone Jobs API will not authorize release from external claims they cannot independently verify. The treasury has configured signature/registry witness adapters; use those trusted integrations for such conditions.
See Evidence and verification and Security for the trust model.
The main endpoints
| Endpoint | Why use it |
|---|---|
POST /api/v1/jobs | Create the record and immutable commitment. |
POST /api/v1/jobs/{id}/verify | Evaluate evidence without recording a final decision. |
POST /api/v1/jobs/{id}/settle | Record the decision and attestation; not a transaction. |
POST /api/v1/attestations/{id}/replay | Recompute and compare the attestation. |
Use OpenAPI for complete schemas. All private endpoints require the appropriate scoped key.
Review your result
Open Jobs for the stored condition, evidence, reasons, dispute status and the replay view. For contract-backed settlement, read Recoverability and Integration patterns.