> ## Documentation Index > Fetch the complete documentation index at: https://docs.terrapinfinance.com/llms.txt > Use this file to discover all available pages before exploring further. # Bond Search > This endpoint returns a list of bonds matching the search filters. Each bond in the response includes fields such as ISIN, Issuer name, coupon, maturity date, currency, and ticker. ## OpenAPI ````yaml post /api/v1/bond_search openapi: 3.0.0 info: title: Terrapin API version: 1.0.0 servers: - url: https://terrapinfinance.com variables: {} security: - authorization: [] tags: [] paths: /api/v1/bond_search: post: tags: [] summary: Government and corporate bond search description: |- This endpoint returns a list of bonds matching the search filters. Each bond in the response includes fields such as ISIN, Issuer name, coupon, maturity date, currency, and ticker. operationId: post_bond_search parameters: [] requestBody: content: application/json: example: country_codes: - IT coupon_max: 4 coupon_min: 3 maturity_date_max: '2028-11-01' maturity_date_min: '2028-10-22' schema: additionalProperties: false properties: asset_classes: description: > 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. items: enum: - asset-backed security - bond - bond with warrants attached - convertible note - depository receipt on debt instruments - medium-term note - money market - mortgage-backed security - structured product nullable: false type: string x-struct: null x-transform: downcase x-validate: null type: array x-struct: null x-validate: null country_codes: description: > Countries of issuing entity (ISO 3166-1 alpha-2 country codes): **Examples:** - `DE`: Country of issue is Germany. - `FR`: Country of issue is France. - `US`: Country of issue is United States of America. items: example: DE maxLength: 2 minLength: 2 nullable: false type: string x-struct: null x-transform: upcase x-validate: null type: array x-struct: null x-validate: null coupon_max: description: Maximum coupon of the bond. type: number x-struct: null x-validate: null coupon_min: description: Minimum coupon of the bond. type: number x-struct: null x-validate: null currencies: description: | Bond currencies, 3-letter ISO 4217 code. items: example: EUR maxLength: 3 minLength: 3 nullable: false type: string x-struct: null x-transform: upcase x-validate: null type: array x-struct: null x-validate: null full_reference_data: description: >- Return full reference data as in from /api/v1/bond_reference. This option requires a special account tier. type: boolean x-struct: null x-validate: null handles: description: >+ Bond handles - predefined categories for filtering bonds by type and characteristics. **Available options by country:** **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. **Spanish Bonds (ES):** - `es_bill`: Spanish short-term government bills. - `es_bond`: Spanish government bonds. - `es_ilb_bond`: Spanish inflation-linked government bonds. - `es_zr_bond`: Spanish zero-coupon government bonds. - `es_vr_bond`: Spanish variable-rate government bonds. **Chinese Bonds (CN):** - `cn_bill`: Chinese government short-term bills. - `cn_bond`: Chinese government bonds. - `cn_bond_vr`: Chinese government variable-rate bonds. - `cn_bond_zr`: Chinese government zero-coupon bonds. **US Treasury Bonds (US):** - `us_tips`: US Treasury Inflation-Protected Securities (TIPS). - `us_frn`: US Treasury Floating Rate Notes (FRN). - `us_bill`: US Treasury Bills (short-term securities). - `us_cmb`: US Treasury Cash Management Bills (CMB). - `us_note`: US Treasury Notes (medium-term securities). - `us_bond`: US Treasury Bonds (long-term securities). **Thai Bonds (TH):** - `th_bill`: Thai short-term government bills. - `th_bond`: Thai government bonds. - `th_ilb_bond`: Thai inflation-linked government bonds. - `th_green_bond`: Thai green government bonds. - `th_zr_bond`: Thai zero-coupon government bonds. - `th_vr_bond`: Thai variable-rate government bonds. items: enum: - ca_bill - ca_bond - ca_cmb - ca_green - ca_rrbond - ca_ulbond - ch_bond - cn_bill - cn_bond - cn_bond_vr - cn_bond_zr - cz_bill - cz_bond - cz_fr_bond - cz_zr_bond - de_bobl - de_bubill - de_bund - de_green - de_ilb - de_schatz - es_bill - es_bond - es_ilb_bond - es_vr_bond - es_zr_bond - fr_btf - fr_oat - fr_oatei - fr_oati - nl_dsl - nl_dtc - uk_bill - uk_gilt - uk_green_gilt - uk_il_gilt - us_bill - us_bond - us_cmb - us_frn - us_note - us_tips nullable: false type: string x-struct: null x-validate: null type: array x-struct: null x-transform: downcase x-validate: null include_callable: description: > Whether to include callable bonds, bonds that can be redeemed by the issuer before maturity. type: boolean x-struct: null x-validate: null include_non_outstanding: default: false description: > Whether to include non-outstanding bonds (matured or redeemed bonds), vastly increases results. type: boolean x-struct: null x-validate: null include_puttable: description: > Whether to include puttable bonds, bonds that can be sold back to the issuer before maturity. type: boolean x-struct: null x-validate: null interest_types: description: > Types of interest: - `zero rate / discount rate`: A bond that does not 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. items: enum: - at maturity - cash payment - dividend payments - fixed interest payments - fixed rate - misc. - no payments - payment in kind - reset rate - variable interest payments - variable rate - zero rate / discount rate nullable: false type: string x-struct: null x-transform: downcase x-validate: null type: array x-struct: null x-validate: null isins: description: >- International Securities Identification Number (ISIN), unique 12-character code for the security. items: example: CH0282526133 maxLength: 12 minLength: 12 nullable: false type: string x-struct: null x-validate: null type: array x-check: valid_check_digit x-check-error: Invalid ISIN check digit x-struct: null x-transform: upcase x-validate: null issue_rating_group: description: | 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) enum: - high_yield - investment_grade nullable: true type: string x-struct: null x-validate: null issued_amount_max: description: Maximum size of total amount issued (in nominal value). minimum: 0 type: integer x-struct: null x-validate: null issued_amount_min: description: Minimum size of total amount issued (in nominal value). minimum: 0 type: integer x-struct: null x-validate: null issuer_name: description: Name of the issuing entity. nullable: true type: string x-struct: null x-validate: null issuer_rating_group: description: > 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) enum: - high_yield - investment_grade nullable: true type: string x-struct: null x-validate: null issuer_types: items: enum: - corporate - government - government_linked - international_organization - municipal - state nullable: false type: string x-struct: null x-validate: null type: array x-struct: null x-validate: null last_trade_date_min: description: >- Include only bonds that have traded since this date in ISO-8601 format (YYYY-MM-DD). format: date type: string x-struct: null x-validate: null leis: description: > 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. items: example: 213800KGF4EFNUQKAT69 maxLength: 20 minLength: 20 nullable: false type: string x-struct: null x-validate: null type: array x-struct: null x-transform: upcase x-validate: null leis_direct_parent: description: > 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. items: example: 549300LBOHZ4QSIWU288 maxLength: 20 minLength: 20 nullable: false type: string x-struct: null x-validate: null type: array x-struct: null x-transform: upcase x-validate: null leis_ultimate_parent: description: > 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. items: example: 1IE8VN30JCEQV1H4R804 maxLength: 20 minLength: 20 nullable: false type: string x-struct: null x-validate: null type: array x-struct: null x-validate: null limit: default: 100 description: >- 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. A limit of 0 returns no results but still includes the total count, which is useful for checking how many results match the given filters. minimum: 0 type: integer x-struct: null x-validate: null maturity_date_max: description: >- Maximum maturity date of the bond in ISO-8601 format (YYYY-MM-DD). format: date type: string x-struct: null x-validate: null maturity_date_min: description: >- Minimum maturity date of the bond in ISO-8601 format (YYYY-MM-DD). format: date type: string x-struct: null x-validate: null maturity_types: description: > 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. items: enum: - amortized - extendible - fixed - perpetual nullable: false type: string x-struct: null x-transform: downcase x-validate: null type: array x-struct: null x-validate: null offset: default: 0 description: >- Offset for query pagination. E.g. limit of 100 with offset of 50 would return the results 50 to 150. minimum: 0 type: integer x-struct: null x-validate: null sort: description: Sort order. Prefix with '-' for descending order. items: enum: - '-country' - '-country_code' - '-coupon' - '-currency' - '-isin' - '-issue_rating_group' - '-issuer_name' - '-issuer_rating_group' - '-maturity_date' - '-ticker' - country - country_code - coupon - currency - isin - issue_rating_group - issuer_name - issuer_rating_group - maturity_date - ticker type: string x-struct: null x-validate: null type: array x-struct: null x-transform: downcase x-validate: null yield_to_maturity_max: description: Maximum yield to maturity of the bond. type: number x-struct: null x-validate: null yield_to_maturity_min: description: Minimum yield to maturity of the bond. type: number x-struct: null x-validate: null type: object x-struct: null x-validate: null required: true responses: '200': content: application/json: example: data: - country: Italy country_code: IT 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 schema: additionalProperties: false properties: data: description: List of response data objects, often capped to 1000. items: additionalProperties: false properties: country: description: > Country 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. example: Germany nullable: true type: string x-struct: null x-validate: null country_code: description: > Country code of issuing entity (ISO 3166-1 alpha-2 country codes): example: DE nullable: true type: string x-struct: null x-validate: null coupon: description: Interest rate or coupon of the bond. nullable: true type: number x-struct: null x-validate: null currency: description: | Bond currency, 3-letter ISO 4217 code. example: EUR maxLength: 3 minLength: 3 nullable: true type: string x-struct: null x-validate: null isin: description: >- International Securities Identification Number (ISIN), unique 12-character code for the security. example: CH0282526133 maxLength: 12 minLength: 12 nullable: false type: string x-check: valid_check_digit x-check-error: Invalid ISIN check digit x-struct: null x-transform: upcase x-validate: null issue_rating_group: description: > 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) enum: - high_yield - investment_grade nullable: true type: string x-struct: null x-validate: null issuer_name: description: Name of the issuing entity. example: EUROBANK SA nullable: true type: string x-struct: null x-validate: null issuer_rating_group: description: > 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) enum: - high_yield - investment_grade nullable: true type: string x-struct: null x-validate: null maturity_date: description: >- Date when the bond principal is due to be repaid in ISO-8601 format (YYYY-MM-DD). format: date nullable: false type: string x-struct: null x-validate: null ticker: description: Bond ticker symbol. example: EUROB V5.875 11/28/29 EMTN nullable: true type: string x-struct: null x-validate: null required: - country - country_code - coupon - currency - isin - issue_rating_group - issuer_name - issuer_rating_group - maturity_date - ticker type: object x-struct: null x-validate: null type: array x-struct: null x-validate: null total: description: >- Total number of results in the database that match the query filters. type: integer x-struct: null x-validate: null required: - data - total title: BondSearchResponse type: object x-struct: null x-validate: null description: Partial reference data '401': content: application/json: schema: additionalProperties: false properties: errors: items: additionalProperties: false properties: detail: example: Unauthorized type: string x-struct: null x-validate: null reason: example: >- Your account tier does not allow this operation. Contact team@terrapinfinance.com for an upgrade. type: string x-struct: null x-validate: null required: - detail type: object x-struct: null x-validate: null type: array x-struct: null x-validate: null required: - errors type: object x-struct: null x-validate: null description: Unauthorized '402': content: application/json: schema: additionalProperties: false properties: errors: items: additionalProperties: false properties: detail: example: Payment Required type: string x-struct: null x-validate: null reason: example: >- You have run out of your granted quota for this resource as defined by your account tier. Contact team@terrapinfinance.com for an upgrade. type: string x-struct: null x-validate: null required: - detail type: object x-struct: null x-validate: null type: array x-struct: null x-validate: null required: - errors type: object x-struct: null x-validate: null description: Payment Required '403': content: application/json: schema: additionalProperties: false properties: errors: items: additionalProperties: false properties: detail: example: Forbidden type: string x-struct: null x-validate: null reason: example: >- Your account tier does not allow this operation. Contact team@terrapinfinance.com for an upgrade. type: string x-struct: null x-validate: null required: - detail type: object x-struct: null x-validate: null type: array x-struct: null x-validate: null required: - errors type: object x-struct: null x-validate: null description: Forbidden '422': content: application/json: schema: properties: errors: items: properties: detail: example: 'Invalid string. Got: integer' type: string x-struct: null x-validate: null source: properties: pointer: example: /isins/0 type: string x-struct: null x-validate: null required: - pointer type: object x-struct: null x-validate: null title: example: Invalid value type: string x-struct: null x-validate: null required: - detail - source - title type: object x-struct: null x-validate: null type: array x-struct: null x-validate: null required: - errors type: object x-struct: null x-validate: null description: Unprocessable Entity '429': content: application/json: schema: additionalProperties: false properties: errors: items: additionalProperties: false properties: detail: example: Too Many Requests type: string x-struct: null x-validate: null reason: type: string x-struct: null x-validate: null required: - detail type: object x-struct: null x-validate: null type: array x-struct: null x-validate: null required: - errors type: object x-struct: null x-validate: null description: Too Many Requests '500': content: application/json: schema: additionalProperties: false properties: errors: items: additionalProperties: false properties: detail: example: Internal Server Error type: string x-struct: null x-validate: null reason: type: string x-struct: null x-validate: null required: - detail type: object x-struct: null x-validate: null type: array x-struct: null x-validate: null required: - errors type: object x-struct: null x-validate: null description: Internal Server Error callbacks: {} components: securitySchemes: authorization: scheme: bearer type: http ````