# Read a person's Connect outcomes

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](https://docs.yutai.com/identifiers)'s.

## The call

GET `/v1/connect/outcomes` Callable today

The key presents the `connect.read` scope.

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

## The parameters

`externalRef`: Required. Your own opaque id for the person, the one the session was created with. It sits in the query.

## What it answers

Whether the person's link stands, the day the consent ends, and for each company the person holds whether they are also its customer, from which month, and the benefits that opens. Outcomes only: no purchase, amount, merchant, count or day is ever answered, and a company the person shops at but does not hold never appears.

- `externalRef`

  Required. A string.
- `linked`

  Whether the person's link to Yutai stands.

  Required. True or false.
- `consentExpiresAt`

  The day the person's consent ends, or null when no link stands.

  Required. A string. It may also be null.
- `companies`

  Required. A list of objects with the fields below.
  - `Each item`

    Required. An object with the fields below.
    - `companyId`

      The registry's id of a company the holder holds.

      Required. A string.
    - `isin`

      The ISIN of the company's security the holder holds.

      Required. A string.
    - `ownerCustomer`

      Whether the holder is also the company's customer inside the consent window.

      Required. True or false.
    - `since`

      The month the holder became an owner-customer, or null when not one.

      Required. A string. It may also be null.
    - `benefitsUnlocked`

      The benefits the owner-customer standing opens, by id.

      Required. A list of strings.
    - `illustrative`

      Whether the programme behind the benefits is illustrative.

      Required. True or false.

## The errors

Every refused call answers one object with three fields: message, the plain sentence that says what did not happen; code, the closed refusal code the call log records beside the call; and requestId, the id to quote when asking Yutai about the call. The message carries 1 to 512 characters, the code 1 to 64 characters, and the request id 1 to 64 characters. Every answer carries the same id on its X-Request-Id header.

| Status | What it answers |
| --- | --- |
| 400 | The reference is missing or is not an opaque id. |
| 401 | The key is missing, malformed, unknown, revoked or expired. |
| 403 | The key does not carry the scope. 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. |
| 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. Nothing was changed. |

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