> ## 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. # Reference Data > Get full US agency bond reference data for given ISINs. ## OpenAPI ````yaml post /api/v1/agency_reference openapi: 3.0.0 info: title: Terrapin API version: 1.0.0 servers: - url: https://terrapinfinance.com variables: {} security: - authorization: [] tags: [] paths: /api/v1/agency_reference: post: tags: [] summary: US agency bond reference description: Get full US agency bond reference data for given ISINs. operationId: post_agency_reference parameters: [] requestBody: content: application/json: example: isins: - US3134HCZH51 schema: additionalProperties: false properties: isins: description: >- International Securities Identification Number (ISIN), unique 12-character code for the security. items: example: US3134HCZH51 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 required: - isins type: object x-struct: null x-validate: null required: true responses: '200': content: application/json: example: data: - asset_class: null call_type: bermudan cfi_code: DBFNGR composite_issue_rating: AA+ composite_issuer_rating: AAA country: United States of America country_code: US coupon: 5.2 coupon_frequency: 2 coupon_payment_day: 16 coupon_payment_months: - 3 - 9 currency: USD figi: BBG020WFFJW5 figi_name: FREDDIE MAC first_call_date: '2028-03-16' first_interest_payment_date: '2026-09-16' inserted_at: null integral_multiple: 1000 interest_accrual_convention: 30/360 interest_accrual_date: '2026-03-16' interest_payment_schedule: - interest_type: regular payment_date: day: 16 month: 9 year: 2026 periodic_schedule: period_amount: 6 period_type: month until: null interest_rate: 5.2 interest_rate_schedule: - determination_period: null from_date: null interest_rate: 5.2 interest_type: fixed rate_mode_name: null until_date: null interest_type: fixed rate is_144a: false is_callable: true is_covered: false is_green: false is_inflation_linked: false is_outstanding: true is_prod_ready: null is_puttable: false is_regs: false isin: US3134HCZH51 issue_date: '2026-03-16' issue_price: 100 issued_amount: 50000000 issuer_name: FEDERAL HOME LOAN MORTGAGE CORPORATION lei: S6XOOCT0IEG5ABCC6L87 lockout_period: null lt_issue_ratings: null lt_issuer_ratings: null maturity_date: '2056-03-16' maturity_type: fixed minimum_denomination: 1000 next_call_date: '2028-03-16' next_call_price: 100 next_coupon_date: '2026-09-16' odd_first_coupon: regular odd_last_coupon: regular optional_redemption_schedule: - call_date: '2028-03-16' call_price: spread_in_bps: 0 type: principal includes_accrued_interest: true is_periodic: true period_amount: 3 period_type: month until: null previous_coupon_date: null rank: senior registration_type: registered sector: null st_issue_ratings: null st_issuer_ratings: null standard_day_of_settlement: 0 ticker: FHLMC 5.2 03/16/56 underwriters: - MESIROW FINANCIAL updated_at: null total: 1 schema: additionalProperties: false properties: data: description: List of response data objects, often capped to 1000. items: additionalProperties: false properties: call_type: description: > Type of call provision on the bond: - `european`: Callable only on a single specified date. - `american`: Callable on any date after the lockout period. - `bermudan`: Callable on a set of predetermined dates. enum: - american - bermudan - european nullable: true type: string x-struct: null x-validate: null cfi_code: description: > Classification of Financial Instruments (CFI) code: The CFI code is a six-letter code that classifies a financial instrument by its type and key features (e.g., fixed/floating rate, registered/bearer, secured/unsecured). example: DTFUFB nullable: true type: string x-struct: null x-validate: null composite_issue_rating: description: | Composite rating of the issue. enum: - A - A+ - A- - AA - AA+ - AA- - AAA - B - B+ - B- - BB - BB+ - BB- - BBB - BBB+ - BBB- - C - CC - CCC - CCC+ - CCC- - D nullable: true type: string x-struct: null x-validate: null composite_issuer_rating: description: | Composite rating of the issuer. enum: - A - A+ - A- - AA - AA+ - AA- - AAA - B - B+ - B- - BB - BB+ - BB- - BBB - BBB+ - BBB- - C - CC - CCC - CCC+ - CCC- - D nullable: true type: string x-struct: null x-validate: null country: description: > Country of issuing entity: - `United States of America`: Country of issue is United States of America. enum: - United States of America nullable: false type: string x-struct: null x-validate: null country_code: description: >- ISO 3166-1 alpha-2 country code (2-letter code) of the country of issue. maxLength: 2 minLength: 2 nullable: false 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 coupon_frequency: description: | Number of coupon payments per year. minimum: 0 nullable: true type: integer x-struct: null x-validate: null coupon_payment_day: description: Day of the month when coupon payments are made. nullable: true type: integer x-struct: null x-validate: null coupon_payment_months: description: > Months when coupon payments are made (1-12). **Examples:** - `[2, 8]`: Coupon payments are made on February and August. items: maximum: 12 minimum: 1 nullable: true type: integer x-struct: null x-validate: null type: array x-struct: null x-validate: null currency: description: > Currency in which the bond is denominated (3-letter ISO 4217 code). example: USD nullable: false type: string x-struct: null x-validate: null figi: description: >- Financial Instrument Global Identifier (FIGI), a unique 12-character alphanumeric code for financial instruments. example: BBG01K89S0G8 maxLength: 12 minLength: 12 nullable: true type: string x-struct: null x-validate: null figi_name: description: >- Name associated with the FIGI (Financial Instrument Global Identifier). nullable: true type: string x-struct: null x-validate: null first_call_date: description: >- Date of the first call option in ISO-8601 format (YYYY-MM-DD). format: date nullable: true type: string x-struct: null x-validate: null first_interest_payment_date: description: >- Date of the first interest payment in ISO-8601 format (YYYY-MM-DD). format: date nullable: false type: string x-struct: null x-validate: null integral_multiple: description: Integral multiple for bond denominations. nullable: true type: number x-struct: null x-validate: null interest_accrual_convention: description: > Day count convention for interest accrual: - `act/act (ICMA)`: Uses actual number of days in period and year. - `30/360`: Assumes 30 days per month, 360 days per year. - `act/360`: Uses actual days in period, 360 days per year. - `act/365`: Uses actual days in period, 365 days per year. - `act/act`: Uses actual number of days in period and year. - `act/act (ISDA)`: ISDA convention for actual/actual. - `act/act (AFB)`: AFB convention for actual/actual. enum: - 30/360 - 30/365 - act/360 - act/365 - act/act - act/act (AFB) - act/act (ICMA) - act/act (ISDA) nullable: true type: string x-struct: null x-validate: null interest_accrual_date: description: >- Date in ISO-8601 format (YYYY-MM-DD) from which interest accrues. format: date nullable: true type: string x-struct: null x-validate: null interest_payment_schedule: description: > The interest payment schedule specifies the schedule of interest payments, which may be periodic or deferred until maturity (for CABs, notes or deferred interest bonds). It is represented as an array of objects with the following schema: items: additionalProperties: false description: >- Schema for each interest payment date or period in the interest payment schedule. properties: interest_type: enum: - accreting - regular nullable: false type: string x-struct: null x-validate: null payment_date: nullable: false oneOf: - additionalProperties: false nullable: false properties: day: maximum: 31 minimum: -1 type: integer x-struct: null x-validate: null month: maximum: 12 minimum: 1 type: integer x-struct: null x-validate: null year: maximum: 2100 minimum: 1900 nullable: true type: integer x-struct: null x-validate: null required: - day - month - year type: object x-struct: null x-validate: null - additionalProperties: false properties: business_day: maximum: 23 minimum: 1 type: integer x-struct: null x-validate: null month: maximum: 12 minimum: 1 type: integer x-struct: null x-validate: null year: maximum: 2100 minimum: 1900 nullable: true type: integer x-struct: null x-validate: null required: - business_day - month - year type: object x-struct: null x-validate: null - additionalProperties: false properties: day_of_week: maximum: 7 minimum: 1 type: integer x-struct: null x-validate: null month: maximum: 12 minimum: 1 type: integer x-struct: null x-validate: null week_of_month: maximum: 5 minimum: 1 type: integer x-struct: null x-validate: null year: maximum: 2100 minimum: 1900 nullable: true type: integer x-struct: null x-validate: null required: - day_of_week - month - week_of_month - year type: object x-struct: null x-validate: null x-struct: null x-validate: null periodic_schedule: additionalProperties: false nullable: true properties: period_amount: type: integer x-struct: null x-validate: null period_type: enum: - month - week type: string x-struct: null x-validate: null until: format: date nullable: true type: string x-struct: null x-validate: null required: - period_amount - period_type - until type: object x-struct: null x-validate: null required: - interest_type - payment_date - periodic_schedule type: object x-struct: null x-validate: null maxItems: 20 nullable: true type: array x-struct: null x-validate: null interest_rate: description: > Interest rate or coupon of the bond, expressed as a percentage of the bond's face value. nullable: true oneOf: - nullable: true type: number x-struct: null x-validate: null - properties: benchmark: type: string x-struct: null x-validate: null pct_of_benchmark: nullable: true type: number x-struct: null x-validate: null spread_in_bps: nullable: true type: number x-struct: null x-validate: null type: object x-struct: null x-validate: null x-struct: null x-validate: null interest_rate_schedule: description: > The interest rate structure specifies the applicable interest rate for a given period and defines how it is set and adjusted over the bond’s term, including periodic adjustments for variable rate bonds. It is represented as an array of objects with the following schema: items: additionalProperties: false properties: determination_period: nullable: true properties: period_length: minimum: 1 type: integer x-struct: null x-validate: null period_type: enum: - day - month - week type: string x-struct: null x-validate: null required: - period_length - period_type type: object x-struct: null x-validate: null from_date: description: Can be null if it applies from issue format: date nullable: true type: string x-struct: null x-validate: null interest_rate: nullable: false oneOf: - description: >- Interest rate/accretion rate when it is a fixed or known number. The rate for capital appreciation bonds is sometimes cited as the yield to maturity. minimum: 0 type: number x-struct: null x-validate: null - description: >- Interest properties when it is a spread over a benchmark or determined by a calculation agent properties: benchmark: enum: - auction - cpi - federal-funds-rate - libor - mmd - remarketing-agent - sifma - sofr - treasury nullable: false type: string x-struct: null x-validate: null pct_of_benchmark: maximum: 300 minimum: 0 nullable: true type: number x-struct: null x-validate: null spread_in_bps: nullable: true type: number x-struct: null x-validate: null required: - benchmark - pct_of_benchmark - spread_in_bps type: object x-struct: null x-validate: null x-struct: null x-validate: null interest_type: enum: - compounding - fixed - variable - zero nullable: false type: string x-struct: null x-validate: null rate_mode_name: description: The name of the rate mode. enum: - 15-day - adjustable - auction - bank-purchase - bi-weekly - cpi - daily - fixed - flexible - floating - frn - index - libor - long-term - medium-term - monthly - multiannual - pass-through - permanent - quarterly - r-floats - remarketing-agent - reset - short-term - sifma - sofr - term - term-floater - two-day - unit_price - weekly - window nullable: true type: string x-struct: null x-validate: null until_date: description: >- Can be null if it applies until maturity. Range is exclusive, i.e. means until but not including. format: date nullable: true type: string x-struct: null x-validate: null required: - determination_period - from_date - interest_rate - interest_type - rate_mode_name - until_date type: object x-struct: null x-validate: >- Elixir.TpData.DocX.Fields.InterestRateSchedule.ItemLevelValidators nullable: true type: array x-struct: null x-validate: >- Elixir.TpData.DocX.Fields.InterestRateSchedule.ArrayLevelValidators interest_type: description: > Type of interest: - `fixed rate`: The bond pays a fixed interest rate throughout its life. - `zero rate / discount rate`: A bond that does not pay or accrue interest. - `variable rate`: The bond's interest rate can change over time, typically based on a reference rate or formula (e.g., SOFR, CPI). - `step rate`: The bond's interest rate increases ("steps up") at predetermined intervals. enum: - fixed rate - step rate - variable rate - zero rate / discount rate nullable: true type: string x-struct: null x-validate: null is_144a: description: > Whether the bond is Rule 144A compliant,can be sold to qualified US institutional buyers. nullable: true type: boolean x-struct: null x-validate: null is_callable: description: | Whether the bond is callable before maturity. nullable: true type: boolean x-struct: null x-validate: null is_covered: description: | Whether the bond is secured by collateral. nullable: true type: boolean x-struct: null x-validate: null is_green: description: | Whether the bond is a green bond. nullable: true type: boolean x-struct: null x-validate: null is_inflation_linked: description: > Whether the bond is inflation-linked, its payments are linked to an inflation index. nullable: true type: boolean x-struct: null x-validate: null is_outstanding: description: > Whether the bond is currently outstanding, has not matured, been called, or otherwise redeemed. nullable: true type: boolean x-struct: null x-validate: null is_puttable: description: | Whether the bond is puttable before maturity. nullable: true type: boolean x-struct: null x-validate: null is_regs: description: > Whether the bond is Regulation S (RegS) compliant, can be sold to non-US investors. nullable: true type: boolean x-struct: null x-validate: null isin: description: >- International Securities Identification Number (ISIN), unique 12-character code for the security. example: US3134HCZH51 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_date: description: >- Date the bond was issued in ISO-8601 format (YYYY-MM-DD). format: date nullable: true type: string x-struct: null x-validate: null issue_price: description: > Price at which the bond was issued (percentage of par), the price is expressed as a percentage of the bond's face value. nullable: true type: number x-struct: null x-validate: null issued_amount: description: >- Total amount issued (face value) in the bond's currency. nullable: true type: number x-struct: null x-validate: null issuer_name: description: Name of the issuing agency. enum: - FEDERAL HOME LOAN MORTGAGE CORPORATION - FEDERAL NATIONAL MORTGAGE ASSOCIATION nullable: false type: string x-struct: null x-validate: null lei: description: > Legal Entity Identifier (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. example: 213800KGF4EFNUQKAT69 maxLength: 20 minLength: 20 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 maturity_type: description: > Maturity type: - `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. enum: - amortized - extendible - fixed - perpetual nullable: true type: string x-struct: null x-validate: null minimum_denomination: description: >- Minimum denomination in which the bond can be purchased. nullable: true type: number x-struct: null x-validate: null next_call_date: description: >- Date of the next call option in ISO-8601 format (YYYY-MM-DD). format: date nullable: true type: string x-struct: null x-validate: null next_call_price: description: >- Price at the nearest call date from today, if exists. nullable: true type: number x-struct: null x-validate: null next_coupon_date: description: >- Date of the next coupon payment in ISO-8601 format (YYYY-MM-DD). format: date nullable: true type: string x-struct: null x-validate: null odd_first_coupon: description: > Indicates whether the first coupon payment is odd: - `regular`: First coupon payment follows the standard interval. - `short`: First coupon period is shorter than the typical payment interval. - `long`: First coupon period is longer than the typical payment interval. enum: - long - regular - short nullable: true type: string x-struct: null x-validate: null odd_last_coupon: description: > Indicates whether the last coupon payment is odd: - `regular`: Last coupon payment follows the standard interval. - `short`: Last coupon period is shorter than the typical payment interval. - `long`: Last coupon period is longer than the typical payment interval. enum: - long - regular - short nullable: true type: string x-struct: null x-validate: null optional_redemption_schedule: description: > The optional redemption schedule defines the periods for which a bond is callable with a fixed, accreted value (for CABs) and make-whole price. It is represented as an array of objects with the following schema: ```json [ { "until": "", "call_date": "", "call_price": { "type": "principal | accreted-value | make-whole", "spread_in_bps": "", // spread above par for principal or accreted-value; spread above benchmark for make-whole "benchmark": "mmd | treasury" // benchmark only applies when it's make-whole }, "is_periodic": "true | false", "period_type": "day | month", "period_amount": "", // period_amount=1 and period_type="day" means continuously callable "includes_accrued_interest": "true | false" }, ... ] ``` items: nullable: false properties: {} type: object x-struct: null x-validate: null type: array x-struct: null x-validate: null previous_coupon_date: description: >- Date of the previous coupon payment in ISO-8601 format (YYYY-MM-DD). format: date nullable: true type: string x-struct: null x-validate: null rank: description: >+ Seniority or rank of the bond: - `senior unsecured`: Highest priority among unsecured debt. - `senior`: Standard senior debt. - `secured`: Backed by collateral. - `government / state`: Government or state-issued debt. - `subordinated`: Lower priority, paid after senior debt. - `supranational`: Issued by supranational entities. - `senior subordinated`: Senior within subordinated class. - `junior secured`: Junior secured debt. - `junior subordinated`: Junior within subordinated class. - `junior`: Junior debt. enum: - government / state - junior - junior secured - junior subordinated - mezzanine - secured - senior - senior subordinated - senior unsecured - subordinated - supranational nullable: true type: string x-struct: null x-validate: null registration_type: description: > Registration type: - `bearer`: Ownership is determined by physical possession. - `registered`: Ownership is recorded and tracked by issuer or agent. - `misc.`: Miscellaneous registration types. - `bearer / registered`: Hybrid registration type. enum: - bearer - bearer / registered - misc. - registered nullable: true type: string x-struct: null x-validate: null standard_day_of_settlement: description: >- Standard number of days between trade date and settlement date. nullable: true type: integer x-struct: null x-validate: null ticker: description: Bond ticker symbol. example: FHLMC 5.2 03/16/56 nullable: true type: string x-struct: null x-validate: null underwriters: description: >- Financial institutions that facilitate the issuance and sale of bonds by purchasing them from the issuer and reselling them to investors. items: nullable: false type: string x-struct: null x-validate: null type: array x-struct: null x-validate: null required: - call_type - cfi_code - composite_issue_rating - composite_issuer_rating - country - country_code - coupon - coupon_frequency - coupon_payment_day - coupon_payment_months - currency - figi - figi_name - first_call_date - first_interest_payment_date - integral_multiple - interest_accrual_convention - interest_accrual_date - interest_payment_schedule - interest_rate - interest_rate_schedule - interest_type - is_144a - is_callable - is_covered - is_green - is_inflation_linked - is_outstanding - is_puttable - is_regs - isin - issue_date - issue_price - issued_amount - issuer_name - lei - maturity_date - maturity_type - minimum_denomination - next_call_date - next_call_price - next_coupon_date - odd_first_coupon - odd_last_coupon - optional_redemption_schedule - previous_coupon_date - rank - registration_type - standard_day_of_settlement - ticker - underwriters 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: AgencyReferenceResponse type: object x-struct: null x-validate: null description: 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 ````