# Add draw rate

This endpoint is used for adding rates. A draw can have multiple rates. If two or more `interestRate` overlap on the same date
we use the lowest value. If two or more `promoRate` overlap on the same date, we take the sum of the promo rates for the given
day, and cap this rate at the maximum interest rate for the given day (to avoid accruing negative interest).
The added `interestRate` will default to the existing interest type set on the loan at the time of
origination (see `atOrigination.interestRate.interestType` attribute).
The added `interestRate` must be within the bounds of any corresponding minimum and maximum rate range
configuration that is found on the loan type (if any).

Endpoint: POST /people/{personId}/loans/{loanId}/draws/{drawId}/rates
Version: 2025-03-26
Security: oauth2, bearerAuth, apiKeyHeader

## Path parameters:

  - `personId` (string, required)
    A Borrower's unique identifier, tied to a person or a business. Can be Peach or a lender's external identifier.

  - `loanId` (string, required)
    The unique identifier of the Loan we wish to retrieve. Can be
Peach or lender's external identifier.

  - `drawId` (string, required)
    The draw identifier.

## Request fields (application/json):

  - `interestRate` (object)
    An interest rate on a loan.
The system will treat the provided value according on the interest type that was set at the time of origination (see `atOrigination.interestType` attribute.)
To remind, `interestType` can have one of the following values: `absolute` or `spread`.
`absolute` - interest rates defined as `absolute` will use the value as provided in the `annualRate` attribute without adding the Index Interest Rate.
- Negative interest `annualRate` value is not allowed.
- If the provided `annualRate` is outside of the range defined on the loan type, the system will accept the `annualRate` but will return a warning in the response's object `ratesValidation`.

`spread` - interest rates defined as `spread` will calculate an absolute rate by adding the relative loan rate (aka spread) provided in the
`annualRate` attribute to the Index Interest Rate effective on the date the interest is accrued. In case the Index Interest Rate is not set,
the system will assume that the Index Interest Rate value is zero on the date the interest is accrued.
- Negative interest spread `annualRate` value is allowed, but the system will default to zero if the addition of the Index Interest Rate still results in a negative rate.
- If the calculated absolute rate, `annualRate` (aka spread) plus Index Interest Rate, is outside of the range defined on the loan type, the system will accept the
`annualRate` but will return a warning in the response's object `ratesValidation`.

  - `interestRate.isEndExistingRates` (boolean)
    If true, the system will set all existing rates that have `endDate=null` to the new rate's `startDate` minus one calendar day.
Use this flag carefully as it might impact ALL existing rates. For example:
- A loan has one existing rate of 0.05 with `startDate=2021-07-01` and `endDate=null`.
- A new rate of 0.01 is added with `startDate=2021-08-05` and `isEndExistingRates=true`.
- The rate of 0.05 will be updated, and the end date will be set to `endDate=2021-08-04`.

Notes:
- Only rates with `endDate=null` will be updated. If an existing rate has a defined end date, that rate will not be modified.
- If an existing rate has `startDate` equal to the new rate, and `endDate=null`, the system will invalidate the existing rate vs. setting
`endDate` to the new rate's `startDate` minus one calendar day. For example:
  - A loan has one existing rate of 0.05 with `startDate=2025-10-02` and `endDate=null`.
  - A new rate of 0.01 is added with `startDate=2025-10-02` and `isEndExistingRates=true`.
  - The rate of 0.05 will be invalidated because the `endDate` cannot be `2025-10-01`.

  - `promoRate` (object)
    A promo rate on a loan. If the annual interest rate is 0.25 and the promo rate for the corresponding
period is 0.05, the net interest rate after application of the promo rate would be 0.2.

  - `promoRate.isEndExistingRates` (boolean)
    If true, the system will set all existing rates that have `endDate=null` to the new rate's `startDate` minus one calendar day.
Use this flag carefully as it might impact ALL existing rates. For example:
- A loan has one existing rate of 0.05 with `startDate=2021-07-01` and `endDate=null`.
- A new rate of 0.01 is added with `startDate=2021-08-05` and `isEndExistingRates=true`.
- The rate of 0.05 will be updated, and the end date will be set to `endDate=2021-08-04`.

Notes:
- Only rates with `endDate=null` will be updated. If an existing rate has a defined end date, that rate will not be modified.
- If an existing rate has `startDate` equal to the new rate, and `endDate=null`, the system will invalidate the existing rate vs. setting
`endDate` to the new rate's `startDate` minus one calendar day. For example:
  - A loan has one existing rate of 0.05 with `startDate=2025-10-02` and `endDate=null`.
  - A new rate of 0.01 is added with `startDate=2025-10-02` and `isEndExistingRates=true`.
  - The rate of 0.05 will be invalidated because the `endDate` cannot be `2025-10-01`.

  - `caseId` (string)
    An identifier for an existing case.

## Response 201 fields (application/json):

  - `message` (string)
    Description of the server action or error.

  - `status` (integer)
    HTTP status code.

  - `data` (object)

  - `data.ratesValidation` (object)

  - `data.ratesValidation.interestRateBelowMinOrZero` (boolean)
    `true` if the interest rate is below the minimum interest rate.

  - `data.ratesValidation.interestRateExceedsMax` (boolean)
    `true` if the interest rate exceeds the maximum interest rate.