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

US APR (Truth in Lending, Regulation Z) API

The annual percentage rate of a closed-end loan the way Regulation Z Appendix J defines it (actuarial method), with odd first periods and the accuracy tolerance.

POST https://api.curatedapi.com/v1/calc/finance/apr/us-reg-z

Computes the APR that US lenders must disclose under the Truth in Lending Act, using the actuarial method of Regulation Z, Appendix J: the rate per unit-period at which the payments, discounted back to consummation, equal the amount financed, times the number of unit-periods in a year. An odd first period is counted the way Appendix J counts it: full months back from the first payment date and the remaining days divided by 30, with simple interest for the fraction. Single-payment loans use the term as the unit-period. The equation is solved exactly and the APR is correctly rounded; the response also gives the finance charge and whether the 1/8 or 1/4 percentage point tolerance applies.

Formula

A = Σ P_j / ((1 + f·i)(1 + i)^t_j); APR = i × unit-periods per year × 100
  • One advance at consummation and payments at regular intervals, with an odd first period allowed; loans with several advances or irregular intervals are not covered yet.
  • All months count as equal (Appendix J (b)(3)(iv)): an odd first period is the days counted forward from consummation to one full month before the first payment, divided by 30. When a month lacks the payment day, its last day is used.
  • A single payment is a single advance, single payment transaction: its term is the unit-period ((b)(5)(vi) and (vii)). Without dates a weekly or biweekly payment is a term of 7 or 14 days, so 365 ÷ 7 or 365 ÷ 14 unit-periods a year; a semimonthly single payment needs dates.
  • The APR is the exact solution of the Appendix J equation, rounded half up to 2 decimals by default; set options.decimals for more.
  • Fees paid before or at consummation that are finance charges belong in the finance charge: subtract them from the loan amount to get the amount financed.

Inputs

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

InputTypeDescription
amount_financed required decimal (string) The amount financed: the credit the borrower receives, after any prepaid finance charges. Allowed: > 0 and <= 1000000000000000. Unit: currency.
payment_amounts required list of decimal (string) The payments in order. Give one amount per group of equal payments and the group sizes in payment_counts, e.g. ["210.71", "220.25"] with [24, 36]; without payment_counts each amount is one payment. 1 to 100 items. Each item: >= 0 and <= 1000000000000000. Unit: currency.
payment_counts list of decimal (string) How many payments of each amount in payment_amounts (whole numbers, same order). Omit it when every amount is a single payment. Up to 100 items. Each item: >= 1 and <= 1200.
payment_frequency monthly | semimonthly | biweekly | weekly | quarterly | semiannually | annually
default monthly
How often payments are due; this is the unit-period. Options: monthly: 12 a year; semimonthly: 24 a year; biweekly: every 2 weeks, 26 a year; weekly: 52 a year; quarterly: 4 a year; semiannually: 2 a year; annually: once a year
consummation_date date (YYYY-MM-DD) When the loan is made (the finance charge starts). Give it with first_payment_date to count an odd first period; without both, the first payment is one full period after consummation.
first_payment_date date (YYYY-MM-DD) When the first payment is due. Later payments follow at the payment frequency.
month_end_payments boolean
default False
Payments are due on the last day of each month, so months are counted from month end to month end (Appendix J (b)(3)(iv)).
options.rounding half_even | half_up | half_down | up | down | ceiling | floor Rounding mode applied once to each result. Default half_up.
options.decimals integer Round results to this many digits after the decimal point.

Result

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

ResultTypeDescription
apr_percentdecimal (string)The annual percentage rate, in percent. Unit: percent.
finance_chargedecimal (string)Total of payments minus the amount financed. Unit: currency.
total_of_paymentsdecimal (string)Sum of all payments. Unit: currency.
number_of_paymentsintegerNumber of payments.
unit_periodstringThe unit-period used.
unit_periods_per_yearstringUnit-periods in a year; APR = rate per unit-period × this (exact).
first_payment_unit_periodsintegerFull unit-periods from consummation to the first payment.
first_period_fractionstringThe odd fraction of a unit-period before the first payment (0 for none).
regular_transactionbooleanTrue when the payments are equal (apart from the first and the last), so the 1/8 point tolerance applies; false for irregular payments (1/4 point).
tolerance_percentstringA disclosed APR within this many percentage points of the exact APR is accurate (Regulation Z § 1026.22(a)(2) and (3)).

Examples

Regulation Z step-rate example: $10,000, 24 × $210.71, 24 × $220.25, 12 × $222.59

Requestcurl
curl https://api.curatedapi.com/v1/calc/finance/apr/us-reg-z \
  -H "Authorization: Bearer $CURATEDAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_financed": "10000",
    "payment_amounts": ["210.71", "220.25", "222.59"],
    "payment_counts": ["24", "24", "12"]
  }'
200 OKResponse
{
  "calculator": "finance/apr/us-reg-z@1",
  "result": {
    "apr_percent": "10.75",
    "finance_charge": "3014.12",
    "total_of_payments": "13014.12",
    "number_of_payments": 60,
    "unit_period": "month",
    "unit_periods_per_year": "12",
    "first_payment_unit_periods": 1,
    "first_period_fraction": "0",
    "regular_transaction": false,
    "tolerance_percent": "0.25"
  },
  "exactness": {
    "apr_percent": "rounded",
    "finance_charge": "exact",
    "total_of_payments": "exact"
  },
  "precision": {
    "rounding": "half_up",
    "decimals": 2
  },
  "inputs": {
    "amount_financed": "10000",
    "payment_amounts": [
      "210.71",
      "220.25",
      "222.59"
    ],
    "payment_counts": [
      "24",
      "24",
      "12"
    ],
    "payment_frequency": "monthly",
    "month_end_payments": false
  },
  "formula": "A = Σ P_j / ((1 + f·i)(1 + i)^t_j); APR = i × unit-periods per year × 100",
  "references": [
    {
      "title": "Regulation Z, Appendix J: Annual percentage rate computations for closed-end credit transactions",
      "url": "https://www.consumerfinance.gov/rules-policy/regulations/1026/J/"
    },
    {
      "title": "Regulation Z, official interpretation of § 1026.22 (step-rate and add-on rate examples, tolerances)",
      "url": "https://www.consumerfinance.gov/rules-policy/regulations/1026/Interp-22"
    }
  ],
  "warnings": []
}

$5,000 in 24 monthly payments of $230, first payment 34 days after the loan

Requestcurl
curl https://api.curatedapi.com/v1/calc/finance/apr/us-reg-z \
  -H "Authorization: Bearer $CURATEDAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_financed": "5000",
    "payment_amounts": ["230"],
    "payment_counts": ["24"],
    "consummation_date": "2026-01-12",
    "first_payment_date": "2026-02-15"
  }'
200 OKResponse
{
  "calculator": "finance/apr/us-reg-z@1",
  "result": {
    "apr_percent": "9.61",
    "finance_charge": "520.00",
    "total_of_payments": "5520.00",
    "number_of_payments": 24,
    "unit_period": "month",
    "unit_periods_per_year": "12",
    "first_payment_unit_periods": 1,
    "first_period_fraction": "0.1",
    "regular_transaction": true,
    "tolerance_percent": "0.125"
  },
  "exactness": {
    "apr_percent": "rounded",
    "finance_charge": "exact",
    "total_of_payments": "exact"
  },
  "precision": {
    "rounding": "half_up",
    "decimals": 2
  },
  "inputs": {
    "amount_financed": "5000",
    "payment_amounts": [
      "230"
    ],
    "payment_counts": [
      "24"
    ],
    "payment_frequency": "monthly",
    "consummation_date": "2026-01-12",
    "first_payment_date": "2026-02-15",
    "month_end_payments": false
  },
  "formula": "A = Σ P_j / ((1 + f·i)(1 + i)^t_j); APR = i × unit-periods per year × 100",
  "references": [
    {
      "title": "Regulation Z, Appendix J: Annual percentage rate computations for closed-end credit transactions",
      "url": "https://www.consumerfinance.gov/rules-policy/regulations/1026/J/"
    },
    {
      "title": "Regulation Z, official interpretation of § 1026.22 (step-rate and add-on rate examples, tolerances)",
      "url": "https://www.consumerfinance.gov/rules-policy/regulations/1026/Interp-22"
    }
  ],
  "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.