Submit a ValidatorDecision
curl --request POST \
--url https://api.usecleff.com/v1/payouts/{payoutId}/decisions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"decision_id": "<string>",
"reasons": [
{
"message": "<string>",
"details": {}
}
],
"evaluated_at": "2023-11-07T05:31:56Z",
"evaluated_by": {},
"policy_version": "<string>",
"agent_version": "<string>",
"confidence": 123
}
'import requests
url = "https://api.usecleff.com/v1/payouts/{payoutId}/decisions"
payload = {
"decision_id": "<string>",
"reasons": [
{
"message": "<string>",
"details": {}
}
],
"evaluated_at": "2023-11-07T05:31:56Z",
"evaluated_by": {},
"policy_version": "<string>",
"agent_version": "<string>",
"confidence": 123
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
decision_id: '<string>',
reasons: [{message: '<string>', details: {}}],
evaluated_at: '2023-11-07T05:31:56Z',
evaluated_by: {},
policy_version: '<string>',
agent_version: '<string>',
confidence: 123
})
};
fetch('https://api.usecleff.com/v1/payouts/{payoutId}/decisions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.usecleff.com/v1/payouts/{payoutId}/decisions",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'decision_id' => '<string>',
'reasons' => [
[
'message' => '<string>',
'details' => [
]
]
],
'evaluated_at' => '2023-11-07T05:31:56Z',
'evaluated_by' => [
],
'policy_version' => '<string>',
'agent_version' => '<string>',
'confidence' => 123
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.usecleff.com/v1/payouts/{payoutId}/decisions"
payload := strings.NewReader("{\n \"decision_id\": \"<string>\",\n \"reasons\": [\n {\n \"message\": \"<string>\",\n \"details\": {}\n }\n ],\n \"evaluated_at\": \"2023-11-07T05:31:56Z\",\n \"evaluated_by\": {},\n \"policy_version\": \"<string>\",\n \"agent_version\": \"<string>\",\n \"confidence\": 123\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.usecleff.com/v1/payouts/{payoutId}/decisions")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"decision_id\": \"<string>\",\n \"reasons\": [\n {\n \"message\": \"<string>\",\n \"details\": {}\n }\n ],\n \"evaluated_at\": \"2023-11-07T05:31:56Z\",\n \"evaluated_by\": {},\n \"policy_version\": \"<string>\",\n \"agent_version\": \"<string>\",\n \"confidence\": 123\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.usecleff.com/v1/payouts/{payoutId}/decisions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"decision_id\": \"<string>\",\n \"reasons\": [\n {\n \"message\": \"<string>\",\n \"details\": {}\n }\n ],\n \"evaluated_at\": \"2023-11-07T05:31:56Z\",\n \"evaluated_by\": {},\n \"policy_version\": \"<string>\",\n \"agent_version\": \"<string>\",\n \"confidence\": 123\n}"
response = http.request(request)
puts response.read_body{
"decision": {
"id": "<string>",
"decision_id": "<string>",
"payout_id": "<string>",
"status": "approved",
"reasons": [
{
"code": "MANUAL_APPROVAL",
"message": "<string>",
"details": {}
}
],
"evaluated_by": {},
"evaluated_at": "2023-11-07T05:31:56Z",
"submitted_at": "2023-11-07T05:31:56Z"
}
}{
"error": {
"code": "validation_failed",
"message": "Request validation failed",
"request_id": "req_abc123",
"occurred_at": "2026-07-07T12:00:00.000Z",
"actor": {
"user_id": "usr_...",
"membership_id": "mem_...",
"role": "business_admin",
"environment": "sandbox"
},
"details": [
{
"field": "decision_id",
"code": "invalid_format",
"message": "decision_id must be a Crockford ULID (26 chars)"
}
],
"docs_url": "https://docs.usecleff.com/errors#validation_failed"
}
}{
"error": {
"code": "unauthorized",
"message": "Unauthorized",
"request_id": "req_abc123",
"occurred_at": "2026-07-07T12:00:00.000Z",
"actor": null,
"docs_url": "https://docs.usecleff.com/errors#unauthorized"
}
}{
"error": {
"code": "forbidden",
"message": "Forbidden resource",
"request_id": "req_abc123",
"occurred_at": "2026-07-07T12:00:00.000Z",
"actor": {
"user_id": "usr_...",
"membership_id": "mem_...",
"role": "business_read_only",
"environment": "sandbox"
},
"docs_url": "https://docs.usecleff.com/errors#forbidden"
}
}{
"error": {
"code": "PAYOUT_NOT_FOUND",
"message": "Payout 7c9e6679-7425-40de-944b-e07fc1f90ae7 not found",
"request_id": "req_abc123",
"occurred_at": "2026-07-07T12:00:00.000Z",
"actor": {
"user_id": "usr_...",
"membership_id": "mem_...",
"role": "business_admin",
"environment": "sandbox"
},
"docs_url": "https://docs.usecleff.com/errors#payout_not_found"
}
}{
"error": {
"code": "INVALID_STATE_TRANSITION",
"message": "Cannot transition Payout from rejected via approve",
"request_id": "req_abc123",
"occurred_at": "2026-07-07T12:00:00.000Z",
"actor": {
"user_id": "usr_...",
"membership_id": "mem_...",
"role": "business_admin",
"environment": "sandbox"
},
"docs_url": "https://docs.usecleff.com/errors#invalid_state_transition"
}
}{
"error": {
"code": "BUSINESS_BLOCKED",
"message": "This Business is blocked from authorising payouts; contact Cleff to resolve it. Payouts awaiting approval can still be rejected.",
"request_id": "req_abc123",
"occurred_at": "2026-07-07T12:00:00.000Z",
"actor": {
"user_id": "usr_...",
"membership_id": "mem_...",
"role": "business_admin",
"environment": "production"
},
"docs_url": "https://docs.usecleff.com/errors#business_blocked"
}
}{
"error": {
"code": "RATE_LIMITED",
"message": "Rate limit exceeded. Slow down and retry after the window.",
"request_id": "req_abc123",
"occurred_at": "2026-07-07T12:00:00.000Z",
"actor": null,
"docs_url": "https://docs.usecleff.com/errors#rate_limited"
}
}Payouts
Submit a Decision
Records a verdict on a Payout. approved and rejected apply only to a Payout in pending_approval, moving it to approved (queued for disbursement) or rejected, while pending_review leaves its state unchanged. Resending a decision_id with the same verdict returns the original Decision; see Idempotency and, for each refusal, Errors.
POST
/
v1
/
payouts
/
{payoutId}
/
decisions
Submit a ValidatorDecision
curl --request POST \
--url https://api.usecleff.com/v1/payouts/{payoutId}/decisions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"decision_id": "<string>",
"reasons": [
{
"message": "<string>",
"details": {}
}
],
"evaluated_at": "2023-11-07T05:31:56Z",
"evaluated_by": {},
"policy_version": "<string>",
"agent_version": "<string>",
"confidence": 123
}
'import requests
url = "https://api.usecleff.com/v1/payouts/{payoutId}/decisions"
payload = {
"decision_id": "<string>",
"reasons": [
{
"message": "<string>",
"details": {}
}
],
"evaluated_at": "2023-11-07T05:31:56Z",
"evaluated_by": {},
"policy_version": "<string>",
"agent_version": "<string>",
"confidence": 123
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
decision_id: '<string>',
reasons: [{message: '<string>', details: {}}],
evaluated_at: '2023-11-07T05:31:56Z',
evaluated_by: {},
policy_version: '<string>',
agent_version: '<string>',
confidence: 123
})
};
fetch('https://api.usecleff.com/v1/payouts/{payoutId}/decisions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.usecleff.com/v1/payouts/{payoutId}/decisions",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'decision_id' => '<string>',
'reasons' => [
[
'message' => '<string>',
'details' => [
]
]
],
'evaluated_at' => '2023-11-07T05:31:56Z',
'evaluated_by' => [
],
'policy_version' => '<string>',
'agent_version' => '<string>',
'confidence' => 123
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.usecleff.com/v1/payouts/{payoutId}/decisions"
payload := strings.NewReader("{\n \"decision_id\": \"<string>\",\n \"reasons\": [\n {\n \"message\": \"<string>\",\n \"details\": {}\n }\n ],\n \"evaluated_at\": \"2023-11-07T05:31:56Z\",\n \"evaluated_by\": {},\n \"policy_version\": \"<string>\",\n \"agent_version\": \"<string>\",\n \"confidence\": 123\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.usecleff.com/v1/payouts/{payoutId}/decisions")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"decision_id\": \"<string>\",\n \"reasons\": [\n {\n \"message\": \"<string>\",\n \"details\": {}\n }\n ],\n \"evaluated_at\": \"2023-11-07T05:31:56Z\",\n \"evaluated_by\": {},\n \"policy_version\": \"<string>\",\n \"agent_version\": \"<string>\",\n \"confidence\": 123\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.usecleff.com/v1/payouts/{payoutId}/decisions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"decision_id\": \"<string>\",\n \"reasons\": [\n {\n \"message\": \"<string>\",\n \"details\": {}\n }\n ],\n \"evaluated_at\": \"2023-11-07T05:31:56Z\",\n \"evaluated_by\": {},\n \"policy_version\": \"<string>\",\n \"agent_version\": \"<string>\",\n \"confidence\": 123\n}"
response = http.request(request)
puts response.read_body{
"decision": {
"id": "<string>",
"decision_id": "<string>",
"payout_id": "<string>",
"status": "approved",
"reasons": [
{
"code": "MANUAL_APPROVAL",
"message": "<string>",
"details": {}
}
],
"evaluated_by": {},
"evaluated_at": "2023-11-07T05:31:56Z",
"submitted_at": "2023-11-07T05:31:56Z"
}
}{
"error": {
"code": "validation_failed",
"message": "Request validation failed",
"request_id": "req_abc123",
"occurred_at": "2026-07-07T12:00:00.000Z",
"actor": {
"user_id": "usr_...",
"membership_id": "mem_...",
"role": "business_admin",
"environment": "sandbox"
},
"details": [
{
"field": "decision_id",
"code": "invalid_format",
"message": "decision_id must be a Crockford ULID (26 chars)"
}
],
"docs_url": "https://docs.usecleff.com/errors#validation_failed"
}
}{
"error": {
"code": "unauthorized",
"message": "Unauthorized",
"request_id": "req_abc123",
"occurred_at": "2026-07-07T12:00:00.000Z",
"actor": null,
"docs_url": "https://docs.usecleff.com/errors#unauthorized"
}
}{
"error": {
"code": "forbidden",
"message": "Forbidden resource",
"request_id": "req_abc123",
"occurred_at": "2026-07-07T12:00:00.000Z",
"actor": {
"user_id": "usr_...",
"membership_id": "mem_...",
"role": "business_read_only",
"environment": "sandbox"
},
"docs_url": "https://docs.usecleff.com/errors#forbidden"
}
}{
"error": {
"code": "PAYOUT_NOT_FOUND",
"message": "Payout 7c9e6679-7425-40de-944b-e07fc1f90ae7 not found",
"request_id": "req_abc123",
"occurred_at": "2026-07-07T12:00:00.000Z",
"actor": {
"user_id": "usr_...",
"membership_id": "mem_...",
"role": "business_admin",
"environment": "sandbox"
},
"docs_url": "https://docs.usecleff.com/errors#payout_not_found"
}
}{
"error": {
"code": "INVALID_STATE_TRANSITION",
"message": "Cannot transition Payout from rejected via approve",
"request_id": "req_abc123",
"occurred_at": "2026-07-07T12:00:00.000Z",
"actor": {
"user_id": "usr_...",
"membership_id": "mem_...",
"role": "business_admin",
"environment": "sandbox"
},
"docs_url": "https://docs.usecleff.com/errors#invalid_state_transition"
}
}{
"error": {
"code": "BUSINESS_BLOCKED",
"message": "This Business is blocked from authorising payouts; contact Cleff to resolve it. Payouts awaiting approval can still be rejected.",
"request_id": "req_abc123",
"occurred_at": "2026-07-07T12:00:00.000Z",
"actor": {
"user_id": "usr_...",
"membership_id": "mem_...",
"role": "business_admin",
"environment": "production"
},
"docs_url": "https://docs.usecleff.com/errors#business_blocked"
}
}{
"error": {
"code": "RATE_LIMITED",
"message": "Rate limit exceeded. Slow down and retry after the window.",
"request_id": "req_abc123",
"occurred_at": "2026-07-07T12:00:00.000Z",
"actor": null,
"docs_url": "https://docs.usecleff.com/errors#rate_limited"
}
}Agents: fetch this page as plain markdown at
https://docs.usecleff.com/api-reference/payouts-decisions-create.md.Authorizations
Cleff API key, created in the dashboard under Settings → API keys
Path Parameters
Body
application/json
Caller-provided ULID; idempotency key
Available options:
approved, rejected, pending_review Show child attributes
Show child attributes
Ignored. Cleff stamps the evaluation time when it records the Decision.
The actor recording the decision. Defaults to the authenticated caller when omitted.
Response
Show child attributes
Show child attributes