POST
/
api
/
v1
/
bond_search
Government and corporate bond search
curl --request POST \
  --url https://terrapinfinance.com/api/v1/bond_search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "countries": [
    "Italy"
  ],
  "coupon_max": 4,
  "coupon_min": 3,
  "maturity_date_max": "2028-11-01",
  "maturity_date_min": "2028-10-22"
}'
{
  "data": [
    {
      "country": "Italy",
      "coupon": 3.75,
      "currency": "EUR",
      "isin": "IT0005571952",
      "issue_rating_group": null,
      "issuer_name": "BPER BANCA SPA",
      "issuer_rating_group": "investment_grade",
      "maturity_date": "2028-10-22",
      "ticker": "BPEIM 3.75 10/22/28 EMTN"
    }
  ],
  "total": 1
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
asset_classes
enum<string>[]

Asset classes:

  • structured product: Structured debt instrument.
  • medium-term note: Bond with medium-term maturity.
  • money market: Short-term debt instrument.
  • bond: Standard debt security.
  • asset-backed security: Securitized debt backed by assets.
  • mortgage-backed security: Securitized debt backed by mortgages.
  • convertible note: Can be converted to equity.
​
countries
string[]

Countries of issuing entity:

Examples:

  • Germany: Country of issue is Germany.
  • United Kingdom: Country of issue is United Kingdom.
  • United States of America: Country of issue is United States of America.
​
coupon_max
number

Maximum coupon of the bond.

​
coupon_min
number

Minimum coupon of the bond.

​
currencies
string[]

Bond currencies, 3-letter ISO 4217 code.

​
full_reference_data
boolean

Return full reference data as in from /api/v1/bond_reference. This option requires a special account tier.

​
handles
enum<string>[]

Bond handles - predefined categories for filtering bonds by type and characteristics.

Available options by country (examples):

German Bonds (DE):

  • de_bund: German long-term government bonds (Bundesanleihen)
  • de_bobl: German medium-term government bonds (Bundesobligationen)
  • de_schatz: German short-term government bonds (Bundesschatzanweisungen)
  • de_bubill: German short-term government bills (Bundesschatzanweisungen)
  • de_ilb: German inflation-linked government bonds
  • de_green: German green government bonds

UK Bonds (GB):

  • uk_gilt: UK government bonds (Gilts)
  • uk_green_gilt: UK green government bonds
  • uk_il_gilt: UK inflation-linked government bonds
  • uk_bill: UK short-term government bills

French Bonds (FR):

  • fr_oat: French long-term government bonds (Obligations Assimilables du Trésor)
  • fr_oatei: French inflation-linked government bonds (OATi)
  • fr_oati: French inflation-linked government bonds (alternative naming)
  • fr_btf: French short-term government bills (Bons du Trésor à taux fixe)
  • fr_bond: French government bonds (general category)

Dutch Bonds (NL):

  • nl_dsl: Dutch government loans (Dutch State Loans)
  • nl_dtc: Dutch short-term government securities (Dutch Treasury Certificates)

Canadian Bonds (CA):

  • ca_bond: Canadian government bonds
  • ca_bill: Canadian short-term government bills
  • ca_cmb: Canadian mortgage-backed securities (Canada Mortgage Bonds)
  • ca_ulbond: Canadian ultra-long government bonds (>30 years)
  • ca_rrbond: Canadian inflation-linked bonds (Real Return Bonds)
  • ca_green: Canadian green government bonds

Swiss Bonds (CH):

  • ch_bond: Swiss government bonds

Czech Bonds (CZ):

  • cz_bond: Czech government bonds
  • cz_bill: Czech short-term government bills
  • cz_fr_bond: Czech floating-rate government bonds
  • cz_zr_bond: Czech zero-coupon government bonds
​
include_callable
boolean

Whether to include callable bonds, bonds that can be redeemed by the issuer before maturity.

​
include_non_outstanding
boolean
default:false

Whether to include non-outstanding bonds (matured or redeemed bonds), vastly increases results.

​
include_puttable
boolean

Whether to include puttable bonds, bonds that can be sold back to the issuer before maturity.

​
interest_types
enum<string>[]

Types of interest:

  • zero rate / discount rate: A bond that does pay or accrue interest.
  • fixed rate: Pays a fixed coupon throughout the bond's life.
  • variable rate: Coupon varies with a reference rate (e.g., SOFR, SONIA, Inflation indexes, etc.).
  • misc.: Miscellaneous interest types.
  • payment in kind: Interest paid in additional securities.
  • dividend payments: Interest paid as dividends.
  • cash payment: Interest paid in cash.
  • at maturity: Interest paid at maturity.
​
isins
string[]

International Securities Identification Number (ISIN), unique 12-character code for the security.

​
issue_rating_group
enum<string> | null

Issue rating group, based on TP composite long-term ratings:

  • investment_grade: High credit quality (BBB- and above)
  • high_yield: Lower credit quality (BB+ and below)
Available options:
investment_grade,
high_yield
​
issued_amount_max
integer

Maximum size of total amount issued (in nominal value).

Required range: x >= 0
​
issued_amount_min
integer

Minimum size of total amount issued (in nominal value).

Required range: x >= 0
​
issuer_rating_group
enum<string> | null

Issuer rating group, based on TP composite long-term ratings:

  • investment_grade: High credit quality (BBB- and above)
  • high_yield: Lower credit quality (BB+ and below)
Available options:
investment_grade,
high_yield
​
issuer_types
enum<string>[]
​
issuers
string[]

Names of bond issuers, such as state or local governments, agencies, or districts.

Enter a full or partial name to match any issuer containing that text (e.g., 'Santander' matches 'Santander Bank').

​
last_trade_date_min
string<date>

Include only bonds that have traded since this date in ISO-8601 format (YYYY-MM-DD).

​
leis
string[]

Legal Entity Identifiers (LEI) of the issuer:

A 20-character, alpha-numeric code based on the ISO 17442 standard used to uniquely identify legal entities in financial transactions. Most LEIs follow this structure, but there are exceptions that use local national standards.

​
leis_direct_parent
string[]

LEIs of the direct parent of the issuer:

A 20-character, alpha-numeric code based on the ISO 17442 standard used to uniquely identify legal entities in financial transactions. Most LEIs follow this structure, but there are exceptions that use local national standards.

​
leis_ultimate_parent
string[]

LEIs of the ultimate parent of the issuer:

A 20-character, alpha-numeric code based on the ISO 17442 standard used to uniquely identify legal entities in financial transactions. Most LEIs follow this structure, but there are exceptions that use local national standards.

​
limit
integer
default:100

Result count limit. E.g. if total number of results is 1450, limit of 100 with offset of 0 would return the first 100 results. Use limit of -1 to opt out of limits.

Required range: x >= -1
​
maturity_date_max
string<date>

Maximum maturity date of the bond in ISO-8601 format (YYYY-MM-DD).

​
maturity_date_min
string<date>

Minimum maturity date of the bond in ISO-8601 format (YYYY-MM-DD).

​
maturity_types
enum<string>[]

Maturity types:

  • fixed: Principal repaid at maturity.
  • amortized: Principal repaid gradually before maturity.
  • perpetual: No maturity date; principal is never repaid.
  • extendible: Maturity date can be extended by issuer or holder.
​
offset
integer
default:0

Offset for query pagination. E.g. limit of 100 with offset of 50 would return the results 50 to 150.

Required range: x >= 0
​
sort
enum<string>[]

Sort order. Prefix with '-' for descending order.

​
yield_to_maturity_max
number

Maximum yield to maturity of the bond.

​
yield_to_maturity_min
number

Minimum yield to maturity of the bond.

Response

Partial reference data

​
data
object[]
required

List of response data objects, often capped to 1000.

​
total
integer
required

Total number of results in the database that match the query filters.