Open an outcome

An outcome is a live instance of a task for one customer. You create it, then send events against it.

Before creating an outcome, you need a customer and a task. The customer must have a rate card assigned with an entry for that task.

What is an outcome?

An outcome tracks whether a real-world event happened and whether it met the conditions for billing. You open it with a single create call, then send events against it. It resolves to confirmed or missed after the settlement window closes.

Examples of when you open an outcome: a support ticket is created, a document is sent for signature, a job is posted, a task is started.

The outcome key

Every outcome has a key. You choose this string. It must be globally unique across all accounts and between 8 and 255 characters.

You use the key on the create call and in every event you send for that outcome. Pick something that includes your own system identifiers:

support:ticket:1001
contract:acme:2024-01
job:hire:req-4821

The key cannot be changed after the outcome is created. It must be globally unique across all accounts, not just your own.

Opening an outcome

Create the outcome. This binds it to a task and a customer.

curl -X POST https://api.thewitn.com/v1/outcomes \
  -H "Authorization: Bearer $WITN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "support:ticket:1001",
    "task_key": "support",
    "customer_key": "acme"
  }'

Returns 202 Accepted. witn snapshots the task contract for this customer and starts evaluating the billable condition. A repeated create for the same key is ignored.

task_key is the key of the task. Find it in the dashboard.

customer_key is the customer's key, not an ID.

What happens next

Send events as things happen in your system. Each event names the outcome by outcome_key. witn evaluates the billable condition after each event and resets the settlement timer. Events for an outcome that does not exist are discarded, so create the outcome first.

When the timer expires, the outcome resolves:

Confirmed: condition was met. You receive a notification and an invoice line is created.
Missed: condition was not met. You receive a notification.

See Notifications to set up a webhook for these events.

Errors

Code	Status	When
`VALIDATION_ERROR`	400	`key`, `task_key`, or `customer_key` is missing or invalid.
`TOKEN_INVALID`	401	Token missing or not recognised.