POST /v1/outcomes


Call	`POST /v1/outcomes`
Price	free
Scope	`outcomes:write`
Operation id	`createOutcome`

What it does

Tell Verdict what happened after a decision (bounced, replied, meeting_booked, approved, skipped, or custom:<slug>). Outcomes calibrate p and move your thresholds. Free and unlimited. Idempotent on (decision_id, outcome, observed_at): a repeat returns 200 with the stored outcome. The SDK reports approved and skipped for you and tags sends with the X-Verdict-Decision email header (or a vendor custom field) so the vendor receivers can report the rest. Scope: outcomes:write.

Example request

Copy it as curl. Set VERDICT_API_KEY first; uuidgen makes a fresh Idempotency-Key.

curl -X POST 'https://api.askverdict.io/v1/outcomes' \
  -H "Authorization: Bearer $VERDICT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "decision_id": "dec_01JC3Z4Y8R9K2M5N7P1Q3S5T7V",
  "outcome": "meeting_booked",
  "observed_at": "2026-11-09T16:30:00Z",
  "meta": {
    "channel": "email"
  }
}'

Example response

200: The same outcome was already recorded; nothing changed.

{
  "id": "out_01JC3Z4Y8R9K2M5N7P1Q3S5T7V",
  "decision_id": "dec_01JC3Z4Y8R9K2M5N7P1Q3S5T7V",
  "outcome": "meeting_booked",
  "observed_at": "2026-11-09T16:30:00Z",
  "meta": {
    "channel": "email"
  },
  "created_at": "2026-11-09T16:30:02Z"
}

201: The outcome was recorded.

{
  "id": "out_01JC3Z4Y8R9K2M5N7P1Q3S5T7V",
  "decision_id": "dec_01JC3Z4Y8R9K2M5N7P1Q3S5T7V",
  "outcome": "meeting_booked",
  "observed_at": "2026-11-09T16:30:00Z",
  "meta": {
    "channel": "email"
  },
  "created_at": "2026-11-09T16:30:02Z"
}

Parameters

Name	In	Type	Required	Description
`idempotency-key`	header	string (uuid)	yes	A UUID you generate per logical request. Required on every POST. Repeating it within 24 hours returns the stored response and bills nothing; reusing it with a different body returns 409 `idempotency_conflict`.
`x-verdict-version`	header	string	no	API version to use, a date. Defaults to the version current when the key was created. The current version is `2026-11-01`.

Request body

Schema CreateOutcomeRequest. The outcome.

Field	Type	Required	Description
`decision_id`	string	yes	The decision the outcome belongs to.
`outcome`	enum: “bounced”, “delivered”, “replied”, “interested”, “not_interested”, “meeting_booked”, “meeting_held”, “approved”, “skipped”, “reopened”, “converted” or string	yes	The outcome: a built-in type or `custom:<slug>`.
`observed_at`	string (date-time)	yes	When the outcome happened.
`meta`	object	no	Optional metadata: up to 20 keys of at most 64 characters, scalar values. No personal data.

Response fields (200)

Schema Outcome.

Field	Type	Required	Description
`id`	string	yes	The outcome id.
`decision_id`	string	yes	The decision it belongs to.
`outcome`	enum: “bounced”, “delivered”, “replied”, “interested”, “not_interested”, “meeting_booked”, “meeting_held”, “approved”, “skipped”, “reopened”, “converted” or string	yes	The outcome: a built-in type or `custom:<slug>`.
`observed_at`	string (date-time)	yes	When the outcome happened.
`meta`	object or null	yes	Optional metadata: up to 20 keys of at most 64 characters, scalar values. No personal data.
`created_at`	string (date-time)	yes	When Verdict recorded it.

Response fields (201)

Schema Outcome.

Field	Type	Required	Description
`id`	string	yes	The outcome id.
`decision_id`	string	yes	The decision it belongs to.
`outcome`	enum: “bounced”, “delivered”, “replied”, “interested”, “not_interested”, “meeting_booked”, “meeting_held”, “approved”, “skipped”, “reopened”, “converted” or string	yes	The outcome: a built-in type or `custom:<slug>`.
`observed_at`	string (date-time)	yes	When the outcome happened.
`meta`	object or null	yes	Optional metadata: up to 20 keys of at most 64 characters, scalar values. No personal data.
`created_at`	string (date-time)	yes	When Verdict recorded it.

Errors

Errors are RFC 9457 problem details and are never billed. Branch on type. See Errors.

Status	Meaning
`400`	Invalid request: malformed JSON, an unknown field, a failed constraint or a size limit (`invalid_request`).
`401`	Missing, malformed, revoked or expired API key, or a bad webhook signature (`unauthorized`).
`403`	The key lacks the scope this operation needs (`forbidden_scope`).
`404`	The resource does not exist in this organization (`not_found`).
`409`	The `Idempotency-Key` was reused with a different request, or the first request is still running (`idempotency_conflict`).
`429`	Rate limited (`rate_limited`). Wait `Retry-After` seconds.
`500`	Unexpected server error (`internal`). Not billed; retry with the same `Idempotency-Key`.

Try it

Open the interactive reference to send this request from the browser. The full document is at /openapi.json.