API reference / API reference

Read the benefits one or more instruments carry

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's.

View as .md

The call

GET/v1/availabilityCallable today

The key presents the availability.read scope.

The get started page shows how a platform gets a key.

The parameters

instruments: Required. The instruments to read: one or more, at most 200 in one read, each an ISIN such as US0000000009 or a CAIP-19 instrument id such as eip155:88880/erc20:0x0000000000000000000000000000000000000000. It sits in the query.
country: Required. The market whose stored policy shapes the answer: its two-letter country code, such as PT. It sits in the query.

What it answers

The instruments the request named, each once in the order it named them, keyed by its security's ISIN: an instrument the registry does not resolve and a company with no benefit to offer are left out. Each row names the market display policy its shape stands under - full carries the benefits, badge_only the count alone - and the market the ask names shapes every row, full when that market stores no policy.

instruments
Required. A list of objects with the fields below. It carries at most 200 items.
- Each item
  Required. An object with the fields below.
  - isin
    The instrument's ISIN, in the registry's canonical spelling.
    Required. A string.
  - display
    full lists the benefits, badge_only carries the count alone.
    Required. A string that is one of the values below.
    - full
    - badge_only
  - count
    How many benefits the company offers in the caller's country.
    Required. A whole number, from 1 to 500.
  - illustrative
    True when every benefit the count counts is illustrative, meaning an example Yutai made up rather than a real offer.
    Required. True or false.
  - benefits
    The benefits the count counts, present on a full row and absent on a badge_only row.
    Optional. A list of objects with the fields below. It carries at most 500 items.
    - Each item
      Required. An object with the fields below.
      - name
        The benefit's name as the company writes it.
        Required. A string. It carries at least 1 and at most 128 characters.
      - requirement
        What the holder must do to reach the benefit, in the company's own short words.
        Required. A string. It carries at least 1 and at most 512 characters.
      - fulfilment
        How the benefit reaches the holder: CODE for a discount code or voucher, POINTS_CREDIT for points, VENUE_REDEMPTION for access at the venue, CHAIN_MINT for a digital collectible, TOKEN_TRANSFER for a token sent to the holder's wallet, and REWARD_FULFILMENT for a merchant reward ordered with a fulfilment provider.
        Required. A string that is one of the values below.
        CODE
        POINTS_CREDIT
        VENUE_REDEMPTION
        CHAIN_MINT
        TOKEN_TRANSFER
        REWARD_FULFILMENT
      - illustrative
        True when the benefit is an example Yutai made up, not an offer a real company has agreed to.
        Required. True or false.
      - scope
        Who the offer is shown to: base for every distributor, distributor for the distributors it names.
        Required. A string that is one of the values below.
        base
        distributor
      - funder
        Who funds the offer: Yutai, its issuer, a distributor or a brand.
        Required. A string that is one of the values below.
        YUTAI
        ISSUER
        DISTRIBUTOR
        BRAND
      - plus
        The Yutai Plus facts, present only on a distributor-scoped offer the calling key's own distributor may see; absent on every base offer and on every other distributor's answer.
        Optional. An object with the fields below.
        distributorName
        The distributor's own name from Yutai's member record, the name the Plus offer stands under.
        Required. A string. It carries at least 1 and at most 128 characters.
        progress
        The wallet's streak toward the tier that asks days; present only on an eligibility answer and only when that tier asks days.
        Optional. An object with the fields below.
        streakDays
        Whole days the wallet has held the security, the one clock the tier reads.
        Required. A whole number, at least 0.
        requiredDays
        The whole days the tier asks for.
        Required. A whole number.
        rewardTiers
        The programme's reward tiers in ladder order, each with the one short requirement sentence.
        Required. A list of objects with the fields below. It carries at most 64 items.
        Each item
        Required. An object with the fields below.
        name
        The tier's name as the programme carries it.
        Required. A string. It carries at least 1 and at most 128 characters.
        requirement
        The one short sentence the tier's holding and days read as.
        Required. A string. It carries at least 1 and at most 512 characters.

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.

The errors the call for GET /v1/availability answers
Status	What it answers
400	The query could not be read.
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.
503	The data source this read needs is not live yet, so the read is refused. Nothing was read.

The errors and limits page carries every refusal status the document declares, each in its own words, beside the calls that answer it.

The call, as a reader copies it: the key it presents stands where your own key stands, and the values are the sample answer's own.

curl "https://api.yutai.com/v1/availability?instruments=US0000000009&country=PT" \
  -H "Authorization: Bearer ytk_your-key"

The sample answer for GET /v1/availability

{
  "instruments": [
    {
      "isin": "US0000000009",
      "display": "full",
      "count": 1,
      "illustrative": true,
      "benefits": [
        {
          "name": "Sample lounge access",
          "requirement": "Hold 15 shares of the programme for 30 days.",
          "fulfilment": "VENUE_REDEMPTION",
          "illustrative": true,
          "scope": "base",
          "funder": "YUTAI"
        }
      ]
    },
    {
      "isin": "US0000000007",
      "display": "badge_only",
      "count": 2,
      "illustrative": true
    }
  ]
}