Exchange Rates

Manage currency exchange rates for multi-currency financial forecasting. Exchange rates define the conversion factor between two currencies and can be time-bounded to support historical and forward-looking calculations.

Exchange Rate Object

Field	Type	Description
id	string	Unique identifier (CUID format). System-generated. Read-only.
fromCurrencyCode	string	Source currency code (3-character ISO 4217, e.g. "GBP").
toCurrencyCode	string	Target currency code (3-character ISO 4217, e.g. "USD").
rate	number	Conversion rate. Multiply the from amount by this rate to get the to amount.
effectiveDate	date (YYYY-MM-DD)	Date the rate takes effect.
createdAt	datetime (ISO 8601)	When the record was created. Read-only.
updatedAt	datetime (ISO 8601)	When the record was last modified. Read-only.

How conversion works

If fromCurrencyCode is "GBP", toCurrencyCode is "USD", and rate is 1.27, then 100 GBP = 127 USD.

---

Endpoints

Method	Path	Description
GET	/org/:orgId/exchange-rates	List exchange rates
GET	/org/:orgId/exchange-rates/:id	Get exchange rate
POST	/org/:orgId/exchange-rates	Create exchange rate
PATCH	/org/:orgId/exchange-rates/:id	Update exchange rate
DELETE	/org/:orgId/exchange-rates/:id	Delete exchange rate

---

List Exchange Rates

GET /org/:orgId/exchange-rates

Query Parameters

Parameter	Type	Default	Description
page	integer	1	Page number (1-based).
limit	integer	20	Records per page. Min 1, max 100.
search	string	--	Search by currency code.
sortBy	string	fromCurrency	Field to sort by: fromCurrency, toCurrency, rate, effectiveFrom, createdAt.
sortDir	string	asc	asc or desc.

Example Request

curl -X GET "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/exchange-rates?sortBy=fromCurrency" \
  -H "Authorization: Bearer private_..."

Example Response

{
  "data": [
    {
      "id": "clx6t7u8v9w0x1y2z3a4",
      "fromCurrencyCode": "GBP",
      "toCurrencyCode": "USD",
      "rate": 1.27,
      "effectiveDate": "2026-01-01",
      "createdAt": "2024-01-10T08:00:00Z",
      "updatedAt": "2025-11-20T14:00:00Z"
    },
    {
      "id": "clx1e2n3g4r5o0t6u7v8",
      "fromCurrencyCode": "EUR",
      "toCurrencyCode": "USD",
      "rate": 1.08,
      "effectiveDate": "2026-01-01",
      "createdAt": "2024-01-05T08:00:00Z",
      "updatedAt": "2025-09-01T10:00:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 8,
    "hasNextPage": false
  }
}

---

Create Exchange Rate

POST /org/:orgId/exchange-rates

Create Request Body

Field	Type	Required	Description
fromCurrency	string	Yes	Source currency code (3-character ISO 4217).
toCurrency	string	Yes	Target currency code (3-character ISO 4217).
rate	number	Yes	Conversion rate. Must be positive.
effectiveFrom	datetime (ISO 8601)	No	When this rate takes effect. Defaults to now.

Update Request Body

All fields from Create are accepted, all optional.

Example Request

curl -X POST "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/exchange-rates" \
  -H "Authorization: Bearer private_..." \
  -H "Content-Type: application/json" \
  -d '{
    "fromCurrency": "GBP",
    "toCurrency": "USD",
    "rate": 1.27,
    "effectiveFrom": "2026-01-01T00:00:00Z"
  }'

Status: 201 Created

---

Error Responses

Validation Error (400)

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed.",
    "details": [{ "field": "rate", "message": "rate must be positive" }],
    "errorId": "err_clx9a8b7c6d5e4f3"
  }
}

Not Found (404)

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Exchange rate not found.",
    "errorId": "err_clx9a8b7c6d5e4f3"
  }
}

---

Related Endpoints

• Employees -- Employee salaries may be in different currencies.
• Contractors -- Contractor rates may be in different currencies.
• Locations -- Locations have a default currency that exchange rates convert from.