Structured Note Conditions: API

We extract a structured note's terms from its offering document. The outcomes of those terms change with the market on any trading day: the underlier passes or breaches a coupon barrier, an autocall trigger fires, a floating rate fixes, or the note matures and settles. The conditions API returns the note's current condition state and the full ordered log of its condition events since issuance.

Condition data is computed. After the close on business days, the engine takes the note's observation schedule and barriers from its reference record, compares them with the day's underlier levels and rate fixings, and recomputes the note from inception. The data comes entirely from our calculation over the reference terms and market data.

The API base URL is https://api.sqx.com/v1/. Requests authenticate with an API key in the x-api-key header. Contact us for a key.

Like the pricing API, and unlike the reference-data API with its job handles and 202 responses, the conditions API is synchronous: the response contains the full result. A second read is useful after we repair a refused note (see "Repairing a refused note" below), and the first read in that case also returns 200.

Quick start

curl -H "x-api-key: $API_KEY" \
    "https://api.sqx.com/v1/conditions/byIsin?isin=US17332URD09"

The response is 200 with the note's condition state and its full event history, or 404 when the ISIN lacks condition state.

Successful response

All responses, successful or failed, use the v1 API envelope: a data object, an errors array (empty on success), and a meta block with a request ID and the server's as_of timestamp. On a 200, data contains four keys: the requested isin, a state object, an events array, and a reextraction block, which is null on almost all calls (see "Repairing a refused note").

This real response shows only the state block and the first event:

{
    "data": {
        "isin": "US17332URD09",
        "state": {
            "evaluable": "TRUE",
            "ineligible_reason": null,
            "status": "AUTOCALLED",
            "autocall_date": "2026-05-27",
            "last_observation_evaluated": "2026-05-27",
            "next_observation_date": null,
            "pending_data_observations": 0,
            "missed_coupons_in_memory": 0,
            "settlement_ineligible_reason": null,
            "last_evaluated_at": "2026-07-24 23:46:32",
            "changed_date": "2026-07-25 04:46:33"
        },
        "events": [
            {
                "observation_date": "2026-03-27",
                "event_type": "COUPON_EARNED",
                "payment_date": "2026-04-01",
                "threshold_pct": "70.0000",
                "worst_underlier": "Nasdaq-100 Index®",
                "observed_level": "23132.769531",
                "initial_level": "24960.040000",
                "performance_pct": "92.6792",
                "measurement_basis": "LEVEL",
                "coupon_rate_pct": "13.800000",
                "recovered_missed_coupons": null,
                "rate_code_1": null,
                "rate_value_1": null,
                "rate_code_2": null,
                "rate_value_2": null,
                "payment_pct_of_notional": null,
                "changed_date": "2026-07-24 01:36:10"
            },
            { "...": "three more events" }
        ],
        "reextraction": null
    },
    "errors": [],
    "meta": {
        "request_id": "3f1c8a2e-9b04-4e77-bd1a-0c2f5e6a7d10",
        "as_of": "2026-07-25T20:00:00+00:00",
        "page": null
    }
}

Both objects always contain the full key set for all notes. A field that is inapplicable to a note or event comes back as JSON null, the API's only placeholder value.

Decimal fields are JSON strings, for example "70.0000". The engine compares these decimal values with decimal thresholds, and converting them to floating point can change the result several decimal places out. Parse them with a decimal type. Integer counters (pending_data_observations, missed_coupons_in_memory, recovered_missed_coupons) are JSON numbers. Dates use YYYY-MM-DD; timestamps use YYYY-MM-DD HH:MM:SS in UTC.

The OpenAPI 3.1 spec (openapi.yaml) is the authoritative contract for all keys, enums, status codes, and the response envelope. This page is a narrative guide; the spec is the source of truth.

The state block

state is the note's current position. We rewrite it whenever we re-evaluate the note.

• status: ACTIVE, AUTOCALLED, or MATURED. ACTIVE means the note is still live; the other two values are terminal conditions.
• evaluable: "TRUE" or "FALSE", as a string. "TRUE" means we can evaluate the note's conditions precisely. See "Evaluate or refuse" below.
• ineligible_reason: null when evaluable is "TRUE", with an exception. A fixed-then-floating note whose floating-leg coupon rate is uncomputable (the extraction lacks the reference rate, or the index is unmapped) stays "TRUE", because its fixed-leg coupons and barrier verdicts are exact. That note reports unknown_rate_index here to explain why its floating-period events lack a coupon_rate_pct. When evaluable is "FALSE", the field contains a stable reason token, optionally followed by a colon and free-text detail (unresolved_underlier: S&P 500 Futures Excess Return Index). Filter on the token and display the detail.
• autocall_date: the observation date on which the note met the autocall trigger. null unless status is AUTOCALLED.
• last_observation_evaluated: the most recent scheduled observation date that we decided. Later dates are in the future or waiting for data.
• next_observation_date: the next scheduled observation date, on evaluable and refused notes alike. null on a terminated note and on an ACTIVE note whose schedule has ended.
• pending_data_observations: the count of scheduled observations awaiting an underlier level or rate fixing. A non-zero value means the engine will retry: it re-selects these notes on all later runs until the data arrives.
• missed_coupons_in_memory: on a memory note, the count of missed coupons currently banked for release at the next passing observation. 0 on notes without a memory feature.
• settlement_ineligible_reason: the reason a MATURED note lacks a MATURITY_SETTLEMENT event. null when we computed the settlement, and null on a note before maturity. See "Maturity settlement" below.
• last_evaluated_at: when the engine last recomputed the note, including recomputes that left the result unchanged.
• changed_date: when the state row last changed.

The two timestamps serve different purposes. To detect a transition, such as a decided coupon or a fired autocall, watch changed_date. We re-evaluate notes far more often than their results change, so last_evaluated_at would signal many recomputes with identical results. To detect that we have re-evaluated the note since a given time, watch last_evaluated_at. Use it when you wait for a repair (described below): a recompute that confirms the previous verdict is a valid result, and changed_date stays unchanged in that case.

The events log

events is a sparse log of transitions in order of observation_date, and then of event_type within a date. It records only decisions. A fixed unconditional coupon is certain and produces zero events, so a plain fixed-rate note can return an empty events array with a valid state.

The five event types:

Event fields:

• observation_date: the scheduled observation date under decision. Together with event_type, it identifies the event uniquely.
• payment_date: the payment date of the resulting cash flow, when the schedule records a payment date.
• threshold_pct: the barrier or trigger for the observation, as a percentage of the initial level: the coupon barrier on coupon events, and the autocall trigger on AUTOCALL. On rate-range barriers, it gives the top of the range.
• worst_underlier: the underlier that decided the observation. On a worst-of basket, this value can change between dates and shows which leg determined the verdict. null on a weighted-average basket, where the combined basket level decides.
• observed_level, initial_level, performance_pct: the observed level, the note's initial fixing level, and their ratio as a percentage. Weighted-average baskets are rebased to 100 at inception and report an initial_level of 100.
• measurement_basis: the source of the observed level. LEVEL is the underlier's own series, which we match to the note's printed initial fixing level on the fixing date, in the filing's units. PROXY_RETURN is the return of the underlier's price proxy over the matching period, in the proxy's currency. It is an approximation, typical for index underliers that lack a directly quotable price series. MIXED is a weighted-average basket whose legs use different bases.
• coupon_rate_pct: the annualized coupon rate for the period.
• recovered_missed_coupons: the count of memory coupons released by the COUPON_EARNED event. null on notes without a memory feature.
• rate_code_1 / rate_value_1, rate_code_2 / rate_value_2: the rate fixings that determine the period's rate, by benchmark code (SOFR, CMT_10Y, and so on). The second pair gives the other leg of a spread or steepener formula. A USD swap rate (CMS, ISDAFIX, ICE Swap Rate) on a note issued before 2022 is the USD LIBOR ICE Swap Rate. For a code that refers to SOFR, the cutoff is 2021-11-08, the launch date of the SOFR ICE Swap Rate. A note without an issue date takes the date of its first observation. Fixings of a LIBOR-era note through 2023-06-30 read USD_LIBOR_ISR_30Y and so on; later fixings read USD_LIBOR_ISR_FB_30Y, the ARRC/ISDA fallback computed from the SOFR swap rate (published by IBA as the USD SOFR Spread-Adjusted ICE Swap Rate). USD_LIBOR_ISR_FB_ codes refer to the computed rate instead of a stored series. A note issued after the cutoff reads the SOFR swap rate (SOFR_SWAP_30Y). Our LIBOR swap fixings run from 2000-07-03 to 2016-10-28, so a LIBOR-era period that fixes between 2016-10-29 and 2023-06-30 has a null rate value.
• payment_pct_of_notional: cash redeemed per 100 notional. Populated only on AUTOCALL and MATURITY_SETTLEMENT, and null on those events when the extracted terms are insufficient to establish the amount. In that case we report null instead of an estimate.
• changed_date: when the event row last changed. We recompute events against revised market data, so use this field to detect revisions.

The API reports coupon rates and leaves the per-period coupon cash amount to the client. coupon_rate_pct is annualized, and day-count conventions are unreliable to extract from term sheets, so a cash figure would be a guess. Approximate the amount as coupon_rate_pct times the period fraction, using consecutive payment_date values for the period.

Example

US17332URD09 is a worst-of autocallable on the Nasdaq-100 and the Energy Select Sector SPDR Fund: a 13.8% contingent coupon observed monthly, a 70% coupon barrier and a 100% autocall trigger, without a memory feature. Its four events cover the full life of the note.

The example shows four behaviors.

Performance below 100% can still earn the coupon. On March 27 the worst leg was down 7.3% from its initial fixing, and the note earned the coupon, because 92.68% is above the 70% barrier. Use event_type to determine the outcome, and treat performance_pct as the measurement only.

The worst leg can change. The Nasdaq-100 decided the March observation, and the Energy SPDR decided the next two. worst_underlier is a per-observation value, so it appears on the event rather than in the state block.

A date can pass two thresholds. On May 27 the worst leg was at 101.89% of initial, above both the 70% coupon barrier and the 100% autocall trigger. The two tests are independent and produce two events.

Redemption and coupon are separate events. May 27 has two rows: the AUTOCALL, with a payment_pct_of_notional of 100.0000 (par, because the note lacks a call premium), and the call-date coupon as a separate COUPON_EARNED. To total the cash flows, add both. payment_pct_of_notional is principal only, on autocall and at maturity alike.

Memory coupons

A memory note banks a missed coupon and releases the full backlog at the next passing observation. The API shows both steps: COUPON_MISSED rows accumulate, state.missed_coupons_in_memory gives the current backlog, and the COUPON_EARNED event that releases the backlog reports the count in recovered_missed_coupons.

US09711NES53 shows a full cycle against an 80% barrier: a miss at 75.75%, then a recovery at 85.22% with recovered_missed_coupons: 1 (two coupons paid on the date), then three more misses. The note is still live, with missed_coupons_in_memory at 3. The misses include a reading of 79.9910% against a threshold of 80.0000%, a shortfall of nine thousandths of a percent. The API returns decimals as strings to preserve differences of this size.

Maturity settlement

At maturity, we evaluate the note's piecewise payoff profile at the final observed performance and emit a MATURITY_SETTLEMENT event with the redemption in payment_pct_of_notional. We interpolate the profile linearly between recorded breakpoints and only within their range.

US48134XYY56 is a Russell 2000 note with a capped payoff. Its final performance was 143.7478%, and the note redeemed at the cap of 118.5000.

As with autocall, the figure is principal only. A final coupon appears as a separate COUPON_EARNED row.

When we are unable to establish the settlement precisely, we omit the MATURITY_SETTLEMENT event, and state.settlement_ineligible_reason gives the reason:

A settlement refusal affects only the settlement. The API still returns the note's full coupon and autocall history.

Evaluate or refuse

The endpoint refuses a note whose conditions we are unable to evaluate precisely. A refused note has evaluable of "FALSE", a reason, and an empty events array. We report a refusal in preference to a coupon verdict computed from an underlier we identified with low confidence.

Reason tokens are stable strings for filtering:

Refusals are temporary in most cases and clear automatically. When we validate an underlier mapping or backfill a missing level series, the engine re-selects the note on the next daily run and clears the refusal before its next observation date.

Repairing a refused note

Some refusals come from a gap in the extracted terms instead of a gap in market data. We extracted the note before the extractor could capture the field the verdict needs. We keep a manifest that maps notes to the extraction capabilities they lack.

A request for a refused note checks the manifest. If the ISIN is on the manifest, the call starts the re-extraction and reports the request in the reextraction block:

{
    "isin": "US0000000000",
    "state": {
        "evaluable": "FALSE",
        "ineligible_reason": "missing_initial_fixing: Nasdaq-100 Index®",
        "...": "..."
    },
    "events": [],
    "reextraction": {
        "tables": "r_note_underlying_link",
        "command_id": "8f3c0b1e-2a55-4c07-9d18-6b2e1f0a4c73"
    }
}

tables lists the term sections we are re-extracting from the filing. command_id is our internal identifier for the run, for reference when you contact us about the repair. To detect the result, use the method below.

Detecting the corrected verdict

The first read returns 200 and the current verdict immediately. The repair runs in the background, and when the re-extraction completes, we recompute the note at once, ahead of the overnight batch.

Re-read the endpoint and watch state.last_evaluated_at:

• Save the timestamp from the first read. That read returned the refusal and a reextraction block; its state.last_evaluated_at is the baseline.
• Re-read in a loop. While last_evaluated_at matches the baseline, the repair is still pending and the response shows the old verdict.
• Stop when the timestamp advances. We have recomputed the note against the re-extracted terms. Treat the new verdict as the result of the repair, even when it matches the old verdict.

before=$(curl -s -H "x-api-key: $API_KEY" "$url" | jq -r .data.state.last_evaluated_at)
deadline=$(( $(date +%s) + 180 ))
while [ "$(date +%s)" -lt "$deadline" ]; do
    sleep 15
    now=$(curl -s -H "x-api-key: $API_KEY" "$url" | jq -r .data.state.last_evaluated_at)
    [ "$now" != "$before" ] && break      # recomputed — read the verdict
done

Analysis runs on a pipeline separate from the API, so frequent polling leaves its speed unchanged: poll at 15-second intervals. Set a time limit on the loop. If a failure occurs on our side, a loop that stops and reports the failure is more useful than an endless loop.

Re-extraction of a term section usually completes in under a minute; several sections take longer. If the repair is unable to run promptly, it moves to the overnight batch, and the next business-day read shows the corrected note.

reextraction returns null after the refusal is resolved.

Scope of the repair

The repair runs alongside a 200 response. The reference-data API withholds its payload behind a poll handle when a newer filing supersedes the record on file, because the old terms would be stale. A condition state is a current evaluate-or-refuse verdict, so the API returns 200 and the verdict immediately while the repair runs.

The repair can leave the verdict unchanged. A re-extraction supplies only terms that we can extract from the filing. If last_evaluated_at has advanced and the refusal remains, the filing lacks the term or our extractor is still unable to capture the term. Further reads will show the refusal until our extraction improves. Refusals that depend on market data, such as initial_level_unverifiable, require a price, which re-extraction is unable to supply.

The repair runs only for notes with an unresolved refusal. Candidates have an ineligible_reason, or a settlement refusal other than the transient final_observation_pending (a re-extraction is unable to supply a missing market close). reextraction is null on an evaluable note, even if the manifest lists the note for a capability, and on a note whose repair requires a full re-analysis rather than a targeted re-extraction.

The block is best-effort: if we are unable to dispatch the repair, the read still returns 200 with reextraction as null. A conditions read succeeds regardless of background repair work.

Update schedule

The engine runs after the close on business days, after the day's prices load. The nightly run produces almost all changes. The exception is a repair recompute, which updates only the note whose terms we just re-extracted. Watch state.changed_date and the changed_date on events; they change only when the data changes.

Plan for two consequences.

Events can change. We recompute a selected note from inception, so a revised or corrected market print can change a past event's performance_pct, reverse a verdict, or add an event where a pending observation was. changed_date shows these revisions. If you cache results, key the cache on changed_date instead of the fetch time.

Conditions and the reference record are separate endpoints. Reference terms from /reference/byIsin change rarely and can be cached for a long time, while condition state changes daily. Combining them would make the terms uncacheable. Fetch terms rarely and conditions often.

Coverage

We compute conditions from the reference record, so a note requires extracted terms before it can have condition state. The coverage below is the upper limit for this endpoint and for /reference/byIsin. A note in the "On request" column needs an extraction first (request the ISIN from /reference/byIsin) before the nightly engine includes the note.

To check a list of ISINs free of charge, POST the list to /reference/coverage.

What we cover, by issuer

Structured notes in our security master, and the response to a request for a note.

Terms ready: we have extracted the payoff curve, underliers and coupon mechanics, and /reference/byIsin returns the terms immediately.

On request: we have identified the offering document and extract the document on request. A request for the ISIN starts the extraction and returns a poll URL; the terms arrive a few minutes later. Advance arrangement is unnecessary.

The remainder are securities without an offering document. They return reference_scope: security_master_only, and that response is free: it leaves your distinct-ISIN limit unchanged. To check a list before requesting the ISINs, POST the list to /v1/reference/coverage, also free.

Issuers with fewer than 5,000 notes are omitted. Coverage depends on offering documents: we extract terms from the offering document, so an issuer whose US notes are unregistered with the SEC shows low coverage here. A distributor feed is the only route to those terms, and work on our SEC pipeline leaves the figure unchanged.

Counts as of 2026-08-14.

Input errors

Invalid input returns 400 with a structured error in the errors array, in the ErrorDetailV2 format used across the v1 API: a numeric messageCode, a category, a machine-readable type, and a human-readable message:

{
    "data": null,
    "errors": [
        {
            "category": "VALIDATION_ERROR",
            "type": "INVALID_INPUT",
            "messageCode": 1010,
            "message": "Invalid ISIN: checksum invalid",
            "messageValues": { "isin": "US06370EDU90" }
        }
    ],
    "meta": { "...": "..." }
}

Filter on messageCode. The codes are stable, and the message wording can change. Platform-wide codes:

The API converts lowercase identifiers to uppercase, so identifiers pasted from a spreadsheet work as entered.

The table above covers the full platform. This endpoint accepts only an ISIN, so its input errors are limited to 1010 and 1040; 1011 and 1012 apply to CUSIP and date parameters, which this endpoint lacks.

Two responses have a narrower meaning here than on the other endpoints.

A 404 means the ISIN lacks condition state: the security is outside our condition tracking, or the daily engine has yet to process the note. The security can still exist in our data elsewhere: an ISIN with full reference and pricing coverage can return 404 here.

A refused note returns 200, a full state with evaluable of "FALSE" and a reason, and an empty events array.

Endpoint reference

You can also browse the payload for a covered ISIN on this site, at https://sqxnotes.com/api/conditions/US17332URD09.json. Its isin, state, and events keys match the live API's data payload. The static file also contains timeline-overlay keys for the Explorer's charts (schedule, underliers, composite, scope, maturity_date, as_of). These keys are site rendering data and fall outside the API contract.

Authentication & versioning

All requests except /version require a valid API key in the x-api-key header. Keys are scoped per client. A key can also have an expiry, a lifetime distinct-ISIN quota (a cap on the total distinct ISINs the key can retrieve), a monthly distinct-ISIN cap per product or across a chosen set of products, and a per-second request rate. A key whose grant has lapsed receives 403 (messageCode 1033). A key over a quota, a monthly cap, or its rate receives 429 (messageCode 1050, with the limit and window in messageValues).

The v1 base path is stable. Field additions are non-breaking and ship in place. Breaking changes (renames, removals, and changes of meaning) ship as a new major version on a new stage. /version reports minor and patch updates.

Two details apply to this endpoint. Access comes through the structured-note reference scope: a key entitled to reference.structured_note, or to the broader reference, can call the endpoint. Metering is separate: conditions bill on their own ledger, independent of reference and pricing, so an ISIN counts separately for conditions, reference, and pricing.

The event-type and reason enums above are open. New tokens can appear within a major version, so treat an unrecognized reason token as a refusal rather than a parse error.