Exchange Rates

Manage currency exchange rates for multi-currency financial forecasting.

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

Returns a paginated list of exchange rates in the organization.

Query Parameters

Parameter	Type	Default	Description
page	integer	1	Page number
limit	integer	20	Records per page (max 200)
search	string	—	Search by fromCurrency or toCurrency
sortBy	string	fromCurrency	Sort field: 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&limit=50" \
  -H "Authorization: Bearer private_..."

Example Response

{
  "data": [
    {
      "id": "clx6t7u8v9w0x1y2",
      "fromCurrency": "GBP",
      "toCurrency": "USD",
      "rate": 1.27,
      "effectiveFrom": "2026-01-01T00:00:00Z",
      "createdAt": "2024-01-10T08:00:00Z",
      "updatedAt": "2025-11-20T14:00:00Z"
    },
    {
      "id": "clx1e2n3g4r5o0t6",
      "fromCurrency": "EUR",
      "toCurrency": "USD",
      "rate": 1.08,
      "effectiveFrom": "2026-01-01T00:00:00Z",
      "createdAt": "2024-01-05T08:00:00Z",
      "updatedAt": "2025-09-01T10:00:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 50,
    "total": 8,
    "hasNextPage": false
  }
}

---

Get Exchange Rate

GET /org/:orgId/exchange-rates/:id

Returns a single exchange rate by ID.

Example Request

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

Example Response

{
  "data": {
    "id": "clx6t7u8v9w0x1y2",
    "fromCurrency": "GBP",
    "toCurrency": "USD",
    "rate": 1.27,
    "effectiveFrom": "2026-01-01T00:00:00Z",
    "createdAt": "2024-01-10T08:00:00Z",
    "updatedAt": "2025-11-20T14:00:00Z"
  }
}

---

Create Exchange Rate

POST /org/:orgId/exchange-rates

Creates a new exchange rate.

Request Body

{
  "fromCurrency": "GBP",
  "toCurrency": "USD",
  "rate": 1.27,
  "effectiveFrom": "2026-01-01T00:00:00Z"
}

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"
  }'

Example Response

{
  "data": {
    "id": "clx3d4e5f6g7h8i9",
    "fromCurrency": "GBP",
    "toCurrency": "USD",
    "rate": 1.27,
    "effectiveFrom": "2026-01-01T00:00:00Z",
    "createdAt": "2026-03-11T09:40:00Z",
    "updatedAt": "2026-03-11T09:40:00Z"
  }
}

Status: 201 Created

---

Update Exchange Rate

PATCH /org/:orgId/exchange-rates/:id

Updates one or more fields on an existing exchange rate. Only include the fields you want to change.

Example Request

curl -X PATCH "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/exchange-rates/clx6t7u8v9w0x1y2" \
  -H "Authorization: Bearer private_..." \
  -H "Content-Type: application/json" \
  -d '{
    "rate": 1.29
  }'

Example Response

{
  "data": {
    "id": "clx6t7u8v9w0x1y2",
    "fromCurrency": "GBP",
    "toCurrency": "USD",
    "rate": 1.29,
    "effectiveFrom": "2026-01-01T00:00:00Z",
    "createdAt": "2024-01-10T08:00:00Z",
    "updatedAt": "2026-03-11T09:45:00Z"
  }
}

---

Delete Exchange Rate

DELETE /org/:orgId/exchange-rates/:id

Deletes an exchange rate.

Example Request

curl -X DELETE "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/exchange-rates/clx6t7u8v9w0x1y2" \
  -H "Authorization: Bearer private_..."

Example Response

{
  "data": {
    "id": "clx6t7u8v9w0x1y2",
    "deleted": true
  }
}

Status: 200 OK

---

Field Reference

Field	Type	Required	Description
id	string	—	Unique identifier (read-only)
fromCurrency	string	Yes	Source currency code (3-char ISO 4217, e.g., "GBP")
toCurrency	string	Yes	Target currency code (3-char ISO 4217, e.g., "USD")
rate	number	Yes	Conversion rate (from * rate = to)
effectiveFrom	datetime	No	Date the rate takes effect (defaults to now)
createdAt	datetime	—	Record creation timestamp (read-only)
updatedAt	datetime	—	Last modification timestamp (read-only)