curatedapi
Browse the docs

Guides

Finance

Excel functions

Late payments

E-invoices

Accounting

Number checks

VAT and GST

Billing and pricing

Money and currencies

Dates and time

Math

Unit conversion

Everyday

Health

Yield to call API

The yield of a callable bond if the issuer redeems it on the call date at the call price, found as a proven root of the price equation.

POST https://api.curatedapi.com/v1/calc/finance/yield-to-call

A callable bond can be repaid early at a set price. Yield to call is the yield the buyer earns if that happens: the rate at which the coupons up to the call date and the call price are worth today's price. It is the same equation as yield to maturity (Excel's YIELD) with the call date in place of maturity and the call price in place of the redemption value. Compare it with the yield to maturity; the lower of the two is the yield to worst.

Formula

the y with PRICE(settlement, call date, coupon, y, call price, frequency, basis) = price
  • The result is Excel's YIELD for the same dates with the call price as redemption, to the digits shown.
  • Coupon dates are counted back from the call date, so the call date should be a coupon date.

Inputs

Send numbers as strings to keep every digit. options sets precision and rounding (see numbers and rounding).

InputTypeDescription
settlement required date (YYYY-MM-DD) Settlement date (when the buyer gets the bond).
call_date required date (YYYY-MM-DD) The date the bond can be called.
coupon_rate_percent required decimal (string) Annual coupon rate in percent of face value. Allowed: >= 0 and <= 1000. Unit: percent.
price required decimal (string) Clean price paid per 100 of face value. Allowed: > 0 and <= 1000000.
call_price required decimal (string) Amount paid per 100 of face value if the bond is called. Allowed: > 0 and <= 1000000.
frequency integer
default 2
Coupons per year: 1, 2 or 4. Allowed: >= 1 and <= 4.
day_count 30/360 | actual/actual | actual/360 | actual/365 | 30e/360
default 30/360
How days are counted for accrued interest. Options: 30/360: US (NASD) 30/360; actual/actual: actual days over the actual length of the coupon period; actual/360: actual days over a 360-day year; actual/365: actual days over a 365-day year; 30e/360: European 30/360
options.rounding half_even | half_up | half_down | up | down | ceiling | floor Rounding mode applied once to each result. Default half_even.
options.decimals integer Round results to this many digits after the decimal point.
options.significant_digits integer Round results to this many significant digits.

Result

Under result in the answer, next to exactness, precision, inputs, formula, references and warnings.

ResultTypeDescription
yield_to_call_percentdecimal (string)Annual yield to the call date. Unit: percent.
coupons_until_callintegerCoupons from settlement to the call date.

Examples

A 5% bond bought at 104, callable in five years at 102

Requestcurl
curl https://api.curatedapi.com/v1/calc/finance/yield-to-call \
  -H "Authorization: Bearer $CURATEDAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "settlement": "2026-03-15",
    "call_date": "2031-03-15",
    "coupon_rate_percent": "5",
    "price": "104",
    "call_price": "102"
  }'
200 OKResponse
{
  "calculator": "finance/yield-to-call@1",
  "result": {
    "yield_to_call_percent": "4.460115",
    "coupons_until_call": 10
  },
  "exactness": {
    "yield_to_call_percent": "rounded"
  },
  "precision": {
    "rounding": "half_even",
    "decimals": 6
  },
  "inputs": {
    "settlement": "2026-03-15",
    "call_date": "2031-03-15",
    "coupon_rate_percent": "5",
    "price": "104",
    "call_price": "102",
    "frequency": 2,
    "day_count": "30/360"
  },
  "formula": "the y with PRICE(settlement, call date, coupon, y, call price, frequency, basis) = price",
  "references": [
    {
      "title": "FINRA: Bond yield and return (yield to maturity and yield to call)",
      "url": "https://www.finra.org/investors/insights/bond-yield-return"
    },
    {
      "title": "Microsoft Excel YIELD function",
      "url": "https://support.microsoft.com/en-us/excel/functions/yield-function"
    }
  ],
  "warnings": []
}

References

Results follow each calculator's documented rules and the sources listed. They are not financial, tax or legal advice. Check that the rules fit your case before you rely on a result. See the terms.

Errors share one format; see errors. Billing, retries and batches work the same for every endpoint.