---
title: "NPV / IRR over periodic or dated cashflows"
method: POST
path: "/v1/cashflow/npv-irr"
tags: ["Utilities"]
---

# NPV / IRR over periodic or dated cashflows

`POST /v1/cashflow/npv-irr`

## Request

- Base URL: `https://api.numeratica.com`
- URL: `https://api.numeratica.com/v1/cashflow/npv-irr`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Computes net present value at a given rate and the internal rate of return for a cashflow series — either periodic (NPV/IRR, one flow per period) or dated (XNPV/XIRR, actual/365 day-count). IRR is a bounded root-find (sign-change scan + bisection with a fixed iteration cap); it is omitted when the cashflows never change sign. Provide exactly one of cashflows or dated_cashflows. Deterministic.

## Request body

- NPVIRRRequest: Provide exactly one of cashflows or dated_cashflows.
  - `rate` number, required: Discount rate for NPV: per-period (periodic) or annual (dated).
  - `cashflows` number[]: Periodic amounts at the end of periods 0, 1, 2, …
  - `dated_cashflows` object[]: Amounts on calendar dates (XNPV/XIRR).
    - `date` string, required: YYYY-MM-DD
    - `amount` number, required

## Response `200`

NPV/IRR result

- NPVIRRResponse
  - `result_id` string
  - `engine_version` string
  - `inputs` NPVIRRRequest: Provide exactly one of cashflows or dated_cashflows.
    - `rate` number, required: Discount rate for NPV: per-period (periodic) or annual (dated).
    - `cashflows` number[]: Periodic amounts at the end of periods 0, 1, 2, …
    - `dated_cashflows` object[]: Amounts on calendar dates (XNPV/XIRR).
      - `date` string, required: YYYY-MM-DD
      - `amount` number, required
  - `result` object
    - `dated` boolean: Dated (XNPV/XIRR) vs periodic.
    - `npv` number: NPV at the given rate (XNPV in dated mode).
    - `irr` number: Solved IRR (annualized XIRR); omitted when no sign change exists.
    - `irr_found` boolean
  - `disclaimer` string

## Other responses

- `400`: Invalid request
- `401`: Missing or invalid API key.
- `405`: Method not allowed
- `429`: The key's per-minute request budget is exceeded. Retry after the delay in the Retry-After header.
- `503`: A dependency (e.g. the key store) is temporarily unavailable, or the request exceeded its compute deadline. Retryable.

---

[API](https://skmtc.dev/numeratica/apis/numeratica-financial-planning-calculations-api.md) · [All operations](https://skmtc.dev/numeratica/apis/numeratica-financial-planning-calculations-api/llms.txt) · [OpenAPI document](https://skmtc.dev/numeratica/apis/numeratica-financial-planning-calculations-api/revisions/075bcfbd1ebf?raw)