# Confirm one fulfilment waiting on this distributor

One call of the distributor API, read from the interface description Yutai publishes. Every sample answer on this page is simulated: no real holder's data stands behind it. The formats every value travels in are the [identifiers page](/docs/identifiers)'s.

## The call

POST `/v1/fulfilments/{id}/confirm` Callable today

The key presents the `claims.write` scope.

The get started page shows [how a platform gets a key](/docs/get-started#key-heading).

## The parameters

`id`: Required. The fulfilment's own id, the one the poll's answer carried: a ful_ prefixed ULID. It sits in the call's address.

## The body

`venueReference`: Required. The reference the credit carries: the words the distributor can point back at in its own records.

## What it answers

The fulfilment's own facts after the confirm: the claim it opens beside, the benefit it credits and the instant it was opened, the credited state, the distributor's own reference for the credit and the instant the confirm recorded. Nothing personal rides the answer.

- `fulfilmentId` The fulfilment's own opaque id, the address its confirm answers at. Required. A string.
- `claimId` The claim this fulfilment opens beside, by its own opaque id. Required. A string.
- `benefitId` The benefit this fulfilment credits, by its own opaque id. Required. A string.
- `benefitName` The benefit's name as the programme carries it, so a fulfilment reads without a second lookup. Required. A string. It carries at least 1 and at most 128 characters.
- `state` Where the fulfilment stands in plain words: waiting on the venue until its confirm lands, then credited by the venue. Required. A string that is one of the values below. `waiting on the venue` `credited by the venue`
- `createdAt` The instant the fulfilment was opened, the moment the credit began waiting on the venue. Required. An instant in the ISO 8601 form.
- `venueReference` The venue's own reference for the credit, one to the stored maximum characters; present only once credited. Optional. A string. It carries at least 1 and at most 256 characters.
- `confirmedAt` The instant the venue's confirm was recorded; present only once the row is credited by the venue. Optional. An instant in the ISO 8601 form.

## The errors

Every refused call answers one object with one field, message: the plain sentence that says what did not happen. The sentence carries 1 to 512 characters, so a refusal never carries an id, a code or an exception's text.

| Status | What it answers |

| --- | --- |

| 400 | The request body could not be read. |

| 401 | The key is missing, malformed, unknown, revoked or expired. |

| 403 | The key does not carry the scope, or the fulfilment was already confirmed: the confirm that stands is the one that landed first. The call is also refused with 403, nothing read, when the distributor is paused, suspended or closed, when the key is paused, or when the key presents from an origin it does not allow. |

| 404 | No fulfilment answers this id under this distributor's key: an unknown id, or one another distributor's key recorded. The answer is the same for both, so no fulfilment id can be probed. |

| 429 | The key made too many calls this minute. The Retry-After header names the seconds until the next window opens. Nothing was read. |

| 500 | The read failed inside Yutai. Nothing was changed. |

The errors and limits page carries [every refusal status the document declares](/docs/errors#statuses-heading), each in its own words, beside the calls that answer it.