Supercede API V2

Welcome to the Supercede API reference. This API lets you to programmatically access the Supercede platform.

With the API, you can do things like create layers, publish deals, and market those deals to lists of underwriters on the platform.

Access

Supercede uses API keys to allow access to the API. Access is currently only granted to select organisations. If you do not have an API key and you believe you should, please contact support.

Pagination

Some endpoints are paginated, meaning they do not return the full list of responses on the first request. To query for the next page, copy the contents of the response header Next-Range into the request header Range. If there is no Next-Range header in the response, that means the response contained the final page.

Terminology

To ensure API stability, resources may have a different name in the API than they do in the Supercede web UI. In particular, "risk" and "deal" both refer to what is known as "placement" in the Supercede web UI.

Changelog

The following is a reverse chronological list of changes made to this API since it was first published. The API is evolving through the principle of backwards compatibility, meaning endpoints may be added, and response objects may have fields added to them.

If we need to perform backwards incompatible changes, such as removing fields from response objects, or adding mandatory fields to request objects, both old and new schemata will be supported during a deprecation period, to allow clients time to be updated. Backwards-incompatible changes may be performed with a shorter deprecation period if we are able to verify that no customer relies on that functionality. Such changes will be listed here for reference.

2026-10-30

• A deal's program_name and a layer's name are now trimmed, and a name that is blank or longer than 100 characters is rejected with 400. This affects /risks, /risks/historical and /layers endpoints.
• Added optional reinstatement_brokerage field to ledger layers: the brokerage percentage applying to reinstatement premium where it differs from the main percentage. It requires brokerage_percentage and only applies to non-proportional layers, so a proportional layer with it is rejected. This affects the /ledgers/{ledger_id}/programs/{program_id}/layers and /ledgers/{ledger_id}/programs/{program_id}/layers/{ledger_layer_id} endpoints.

2026-10-29

• Added optional as_to_amount and as_to_time fields to each reinstatement, stating how its premium is scaled on the two dimensions the market states separately: "100% additional premium, pro rata as to amount, full as to time". Each takes pro_rata or full, and all four combinations occur, so the percentage alone did not say what a reinstatement costs. This affects /layers, /layers-v2, /layers/{layer_id} and /risks/historical endpoints.

2026-10-28

• Added optional indexation object to non-proportional layer data, recording an indexation (stability) clause: the index the figures float with, the dead band the parties ignore, and which figures it adjusts -- a treaty commonly indexes its per-loss limit and excess while leaving its annual aggregate limit unindexed.
• Added optional minimum_original_risks and aggregate_erosion_order fields to non-proportional layer data. A cover can warrant that a loss involves at least so many original risks before it attaches at all, and a contract settles whether losses erode the annual aggregate deductible in loss date order or in an order the cedent elects.
• Added optional unlimited_for list to non-proportional layer data, naming the slices of the business the stated limits do not cap at all. A motor programme can run a capped top layer for most classes while leaving Third Party Bodily Injury unlimited under the same layer.
• Added optional cession_base field to proportional layer data, stating what the cession's percentage applies to: each whole risk (the default), the part of the gross line above gross_line_threshold, or the line the cedent retains. The same percentage otherwise describes three different covers.
• Added optional max_cession_bases list to proportional layer data, naming the bases on which an original policy may express the limit max_cession_any_one_risk caps -- each and every loss, each policy or coverage, or in the aggregate. A treaty can cap the cession at one amount whichever of these the original policy uses. This affects /layers, /layers-v2, /layers/{layer_id} and /risks/historical endpoints.
• Added optional premium_reserve object to the deal contractual terms, recording premium the cedent retains for the reinsurer's account and releases in a later period: the share retained, any interest it earns, and the terms on which it is held and released. This affects the /deals/{deal_id}/contractual-terms endpoints.
• Shared limit group membership is now unique per kind rather than overall: a layer may be named by one group stating a shared limit and another stating a shared deductible, since a cover's cap and its inner aggregate deductible commonly span different layer sets. This affects the /risks/{risk_id}/shared-limit-groups endpoints.
• Added optional brokerage.as_percent.reinstatement_amount field to the pricing feature object: the brokerage percentage applying to reinstatement premium. It only applies to non-proportional layers, so a proportional pricing feature with it is rejected. This affects /risks/{deal_id}/pricing-features (GET) and /risks/{deal_id}/pricing-features/{company_id}/{stamp_name}/{layer_id} (PUT).

2026-10-27

• Added optional aggregate_recovery_caps and aggregate_deductible_bands lists to non-proportional layer data: aggregate recovery caps and parallel aggregate deductibles banded by the contract's own slices of the business, each band stating its figure in one or more alternative currencies. This affects /layers, /layers-v2, /layers/{layer_id} and /risks/historical endpoints.
• Added optional cancellation object to the deal contractual terms, recording a mid-term cancellation: its effective date, the premium returned (one entry per currency), and the terms the endorsement states. This affects the /deals/{deal_id}/contractual-terms endpoints.

2026-10-26

• Added optional shared_deductible field to shared limit groups: an aggregate deductible the member layers erode between them, one entry per currency. A group may state a shared limit, a shared deductible, or both. This affects the /risks/{risk_id}/shared-limit-groups endpoints.
• Cession cap bands are now unique per (band, per_unit) pair rather than per band name alone, so one class may be capped on two bases -- per person and per occurrence -- without artificial name suffixes.
• Added optional reinstatement_value field to the layer brokerage object: the brokerage percentage applying to reinstatement premium where it differs from the main percentage -- commonly 0, for contracts stating brokerage as nil on reinstatements.
• Added optional aggregate_exposure_caps list to proportional layer data: aggregate caps on ceded exposure banded by the contract's own slices of the business, commonly a peril per domiciled territory. Each band carries the same cap in one or more alternative currencies. This affects /layers, /layers-v2, /layers/{layer_id} and /risks/historical endpoints.
• Added optional rates_of_exchange list to the deal contractual terms. Each entry states a fixed rate the contract binds two of its currencies at (from, to, rate), tying a multi-currency premium or limit into one amount expressed several ways. This affects the /deals/{deal_id}/contractual-terms endpoints.
• Added optional franchise_trigger field to monetary limit entries: the ground-up loss at which a franchise cover begins to pay, distinct from the excess it then pays from. Requires excess_type "franchise". This affects /layers, /layers-v2, /layers/{layer_id} and /risks/historical endpoints.
• Added optional loss_additional_premium_amount field to non-proportional layer data, for contingent premiums stated as (or capped at) a monetary amount rather than the percentage loss_additional_premium carries.
• Added optional premium_cession field to proportional layer data: the share of premium ceded where it differs from the loss cession.
• Added optional gross_line_threshold and cession_is_maximum fields to proportional layer data, recording the two ways a variable quota share's cession varies: only risks whose gross line exceeds the threshold are ceded, and the stated share may be a ceiling the cedent elects up to per cession.
• Added optional class field to facultative limit entries, naming the class of original policy a limit applies to. Facultative limits are now unique per currency and class rather than per currency alone, and limit entries read back with a class key on every monetary limit collection. This affects /layers, /layers-v2, /layers/{layer_id} and /risks/historical endpoints.
• Added optional limit_in_shared_group field to non-proportional layer data. A layer carrying premium but no limit of its own may declare that its limit is the one a shared-limit group records across the placement's sections; omitting limits without the declaration remains an error. This affects /layers, /layers-v2, /layers/{layer_id} and /risks/{risk_id}/shared-limit-groups endpoints.

2026-10-20

• Added optional limit_maximum_amount and excess_minimum_amount fields to percent limit entries. A stop loss states each half of its cover twice: the limit is the lesser of the percentage of the subject premium and the monetary amount, the attachment the greater. This affects /layers, /layers-v2, /layers/{layer_id} and /risks/historical endpoints.
• The documentation no longer claims percent_limit and percent_excess are at most 100. The API has always accepted larger values, and a stop loss routinely attaches above its subject premium.

2026-10-19

• Added optional fein_code field to Stamp object schema.

2026-10-15

• Added GNWPI (Gross Net Written Premium Income) to the premium basis enum, everywhere a premium basis is accepted.
• Added /risks/{deal_id}/documents/{document_id}/download, which redirects to a temporary link to download a document using an API key. The download_link_url of documents listed by /risks/{deal_id}/documents now points to it.

2026-10-12

• Section and subsection fields the schema declares optional no longer require their keys to be present: premium, premium_basis and territorial_scope on subsections, and additional_info, exclusions and subsections on sections, may now be omitted instead of sent as null. This affects /risks and /risks/historical endpoints.

2026-09-21

• Added optional programme_reference field to Deal object schema. This affects /risks and /risks/{risk_id} endpoints.

2026-09-11

• Added optional layer_expense_caps field to the Risk Accounting object, carrying TPA, LAE, and other expense caps per layer. Each cap can be expressed as a percentage, as monetary amounts in one or more currencies, or both.

2026-09-10

• Added optional programme_dua field to Deal object schema. This affects /risks and /risks/{risk_id} endpoints.

2026-09-02

• Risk Accounting now accepts and returns multiple layer_internal_references values for one layer.
• Historical deal load accepts an optional internal_references array on each layer. The existing internal_reference field remains supported.

2026-08-28

• Added optional excess_type and percent_excess_type fields to excess data. This affects /layers/{layer_id}/coverage endpoint.

2026-08-27

• Added optional fet_exempt_info field to stamp object schema.

2026-08-24

• Added optional basis field to risk layer and pricing features schemas. This affects /layers-v2, /layers/{layer_id}, /risks/{risk_id}/pricing-features endpoints.

2026-08-21

• Added optional renewed_from field to Deal object schema. This affects /risks and /risks/{risk_id} endpoints.

2026-08-20

• Removed order_estimated_premium_income, brokerage_estimated_premium_income, loss_ratio_cap_estimated_premium_income and no_claim_bonus_estimated_premium_income fields from layer data.
• Added adjustable_rate_estimated_premium_income field to layer data.
• Removed brokerage_estimated_premium_income and loss_ratio_cap_estimated_premium_income fields from proportional pricing features.
• Removed no_claim_bonus_estimated_premium_income and brokerage_estimated_premium_income fields from non-proportional pricing features.
• Added adjustable_rate_estimated_premium_income field to proportional and non-proportional pricing features.

2026-08-17

• Added optional rationale field to Deal object schema. This affects /risks, /risks/{risk_id} and /risks/historical endpoints.

2026-08-15

• Added ceding_commission_estimated_premium_income, overriding_commission_estimated_premium_income, loss_ratio_cap_estimated_premium_income and no_claim_bonus_estimated_premium_income fields to layer data.

2026-08-14

• Added quoting_closed status for Deal and Layer objects, replacing retracted. Note that retracted is deprecated and will be removed in the next API version; please use quoting_closed instead. This affects the status field of the Deal and Layer objects, and the status query param on /risks, /layers, /layers-v2 and /layers/{layer_id} endpoints.
• Changed the risk_options.status field representation of the Deal object. Please use new archived/draft/quoting/quoting_closed/fot/bound values instead of the deprecated OptionArchived/OptionDraft/OptionQuoting/OptionRetracted/OptionInMarket/OptionBound values. This affects /risks and /risks/{risk_id} endpoints.

2026-08-13

• Added optional programme_id, programme_name, inuring_benefits_from_risks, inuring_benefits_to_risks and co_brokered_risks fields to Deal object schema. This affects /risks and /risks/{risk_id} endpoints.

2026-08-12

• Added optional reinsured_basis field to layer object schema. This affects POST /layers endpoint.
• Added reinsured_basis field to historical layer object schemas. This affects POST /risks/historical endpoint.

2026-08-11

• Added optional custom_name field to subsection object schema. This affects /risks, /risks/{risk_id}, /layers, /layers-v2 and /layers/{layer_id} endpoints.
• Added optional custom_name field to ledger program product and ledger layer product object schemas. This affects /ledgers/{ledger_id}/programs, /ledgers/{ledger_id}/programs/{program_id}, /ledgers/{ledger_id}/programs/{program_id}/layers and /ledgers/{ledger_id}/programs/{program_id}/layers/{ledger_layer_id} endpoints.
• Added risk_options.layers field to Deal object schema. This affects /risks and /risks/{risk_id} endpoints.

2026-08-10

• Added order_estimated_premium_income and brokerage_estimated_premium_income fields to layer data.
• Added ceding_commission_estimated_premium_income, overriding_commission_estimated_premium_income, brokerage_estimated_premium_income and loss_ratio_cap_estimated_premium_income fields to proportional pricing features.
• Added no_claim_bonus_estimated_premium_income and brokerage_estimated_premium_income fields to non-proportional pricing features.

2026-08-06

• Added optional premium_incomes field to layer and layer coverage object schemas. This affects GET /layers, /layers-v2, /layers/{layer_id} and /layers/{layer_id}/coverage endpoints.
• Added optional premium_incomes field to create layer and create layer coverage data schemas. This affects POST /layers and /layers/{layer_id}/coverage endpoints.
• Added optional premium_incomes field to deal, create deal, subsection, create subsection and historical deal/layer object schemas. This affects /risks, /risks/{risk_id}, POST /risks and /risks/historical endpoints.

2026-07-08

• Added optional sliding_scale_commission_calculation_type fields to Deal layer object schema. This affects /layers, /layers-v2, /layers/{layer_id}, /risks/{deal_id}/pricing-features and /risks/{deal_id}/pricing-features/{company_id}/{stamp_name}/{layer_id}.

2026-07-06

• Added new endpoint /layers/{layer_id}/coverage, where coverage can have multiple amounts in different currencies.

2026-06-25

• Added optional territorial_scope and perils fields to layer coverage schema. This affects /layers, /layers-v2 and /layers/{layer_id} endpoints.
• Added optional layer_aggregate_limits, facultative_limits and industry_loss_warranty fields to layer coverage schema. This affects /layers, /layers-v2, /layers/{layer_id} and /risks/historical endpoints.

2026-06-24

• Added optional monetary field to layer brokerage object schema. This affects /layers, /layers-v2, /layers/{layer_id} and /risks/historical endpoints.
• BREAKING: the layer rate is a discriminated object whose type field is required (rate_on_line, adjustable_rate, monetary_amount, or the combined rate_on_line_and_adjustable_rate and rate_on_line_and_monetary_amount), and each type requires its own fields and rejects the others' -- see the Layer rate schema. Deposits moved into the premiums array. This entry was added retrospectively on 2026-10-26; the change shipped with the reinsurance_premium items below. This affects /layers, /layers-v2, /layers/{layer_id} and /risks/historical endpoints.
• Added reinsurance_premium and reinsurance_premium_description fields to layer rate object schema. The custom_premium field is removed and rate.reinsurance_premium + rate.reinsurance_premium_description fields are intended to be used instead. This affects /layers, /layers-v2, /layers/{layer_id} and /risks/historical endpoints.

2026-06-22

• Added optional fronting_capacity field to /risks/{risk_id}/accounting schemas.

2026-06-19

• Added optional premium_income.data.percentage_us, sections.subsections.premium_percentage_us and sections.subsections.total_insured_value fields to /risks and /risks/{risk_id} schemas.

2026-06-17

• Added optional subject_premium_percentage_us, total_insured_value, coverages.estimated_premium_income and coverages.total_insured_value fields. This affects /layers-v2 and /layers/{layer_id} endpoints.

2026-06-12

• Added coverages.surplus_line, coverages.peril_coverages.surplus_line and product_data.data.surplus_line fields. This affects /layers, /layers-v2 and /layers/{layer_id} endpoints.

2026-06-10

• Added lors_code to accounting information.

2026-06-09

• Added description field to layer.

2026-05-28

• Added loss_ratio_cap field to proportional pricing features. This affects /risks/{deal_id}/pricing-features (GET) and /risks/{deal_id}/pricing-features/{company_id}/{stamp_name}/{layer_id} (PUT).

2026-05-22

• Added trigger_type and payout_basis fields to loss warranty. This affects /layers, /layers-v2 and /layers/{layer_id}.

2025-12-30

• Added signing_date field to lines. This affects GET /lines. This new field records the date(s) when the reinsurer added their signature to the final reinsurance contracts.

2025-12-17

• Added optional boolean is_not_taken_up query parameter to GET /risks.

2025-12-08

• Added brokerage field to pricing features. This affects /risks/{deal_id}/pricing-features and /risks/{deal_id}/pricing-features/{company_id}/{stamp_name}/{layer_id}. This new brokerage field consists of both monetary brokerage, which may have 1 amount per currency, and brokerage as a percentage, for which a single amount and basis may be specified.

2025-11-14

• Added industry_loss_warranty to layer data.

2025-11-10

• Added /risks/{deal_id}/documents endpoint.

2025-11-07

• Removed deprecated collateral field from layer data.

2025-11-03

• Added layer_aggregate_limits to layer data.

2025-10-30

• Added not_taken_up_reason field to layer and deal data.

2025-10-24

• Made the limit field optional in limit-and-excess and loss warranty data.
• Made the percent_limit field optional in percent limit-and-excess data.

2025-09-29

• Added endpoint /risks/{risk_id}/last-changed.

2025-09-18

• Added /layers-v2 endpoint. The difference in the new version is that the status field indicates the stage of the layer (draft, quoting, retracted, fot, bound), and there is a new field is_archived containing the information held in the status field of the old /layers endpoint.

2025-06-18

• Deprecated fields brokerage_rebate and collateral. Users of these fields should use accounting market information instead.

2025-06-04

• Added market_info field to deal accounting data.
• Added accounting_market_info field to historical risk endpoint.

2025-05-23

• Added layer_reporting_requirements field to deal accounting data.

2025-05-20

• Added premium_basis field to deal subsection data.

2025-05-19

• Added premium_payment_warranty to deal accounting data.

2025-05-15

• Added cash_layer_loss_limit field to deal accounting data.

2025-05-06

• Added new premium basis values: GEP, NEP, and AFP.

2025-03-31

• Added perils field to layer and coverage data.

2025-03-27

• Added territorial_scope field to layer and coverage data.

2025-03-21

• Added subject_premium_basis field to layer data.

2025-02-11

• Increased detail in custom premium data.

2025-02-04

• Removed comment field from quote endpoints.

2024-11-15

• Added endpoints for managing subjectivities, comments, and pricing features.

2024-10-19

• Added endpoint /risks/{risk_id}/audit-trail.
• Added endpoint /risks/historical to backfill with historical risks.

2024-05-13

• Added layer_original_acquisition_cost to risk accounting data.

2024-05-09

• Added fot, archived, and bound risk statuses.

2024-04-25

• Replaced in_market with fot, both as a field and a filter.

2023-11-24

• Added field duplicates to the risk object, containing risk duplicate information. Limited duplicates visibility to users with the Client role.
• Added brokerage_splits to the risk accounting object.

2023-11-21

• Added cover_note_status mandatory field to risk objects.
• Added cover_note_status as a filter to the risk listing endpoint.

2023-11-06

• The risk_options/{risk_option_id}/brokerage_rebate endpoint was removed. This functionality has been moved to risks/{risk_id}/accounting

2023-10-31

• Fields internal_expenses, premium_payment_schedule, cedent_participations, internal_reference were removed. This information has been moved to a new Risk Accounting endpoint and is available only to risk cedent users at the FOT/Bound stages.
• Field target_premium was renamed to target_reinsurance_premium.
• Field max_recoverable was removed.

2023-10-13

• When creating new risks, the following fields have been removed and are no longer accepted: id and cedent_participations.
• The type of loss_additional_premium was changed to number.

2023-10-10

• It is now prohibited to specify line_of_business_id for new layers, this information instead being derived from the subline of business.

2023-09-29

• The /territories endpoint was added.
• The /perils endpoint was added.
• The geography field was replaced with an optional territorial_scope field, which holds two territory codes. This applies to the top-level risk data, subsection data within a risk, and layers.
• The cession_basis field was added to layer data.
• Non-proportional layers have new possible values of product: industry_loss_warranty and clash_excess_of_loss.
• Values of brokerage_basis were changed.
• The fields annual_aggregate_deductible, annual_aggregate_limit, and occurrence_limit were removed from proportional product data.
• Non-proportional product data had the following optional fields added: loss_warranties, agg_percent_limits, per_risk_percent_limits, occurrence_agg_percent_limits, and facultative_limits.
• The type of some optional fields in non-proportional product data was changed from a plain number to a limit object with two fields. This affects agg_limits, catastrophe_agg_limits, clash_agg_limits, occurrence_agg_limits, and per_risk_limits.
• The premium_payment_schedule field was changed to a list of premium payment schedule objects.
• A required perils field was added to layer subsection data.
• An optional field internal_expenses was added to layer data.
• An optional field peril_coverages was added to coverage data.