Foreign Currency
Maintain exchange rates, revalue foreign-currency balances and translate entities for consolidation. Every operation below is generated from the published OpenAPI contract. Paths are company-scoped; read the Accounting API guide for scopes, step-up and permissions, and the Foreign Currency guide for the workflow.
- GET
/rest/v1.0/companies/{company_id}/accounting/fx/entitiesList entity functional currencies - PATCH
/rest/v1.0/companies/{company_id}/accounting/fx/entities/{id}Set an entity's functional currency - GET
/rest/v1.0/companies/{company_id}/accounting/fx/ratesList exchange rates - POST
/rest/v1.0/companies/{company_id}/accounting/fx/ratesAdd an exchange rate - GET
/rest/v1.0/companies/{company_id}/accounting/fx/rates/{id}Show an exchange rate - PATCH
/rest/v1.0/companies/{company_id}/accounting/fx/rates/{id}Change an unused exchange rate - DELETE
/rest/v1.0/companies/{company_id}/accounting/fx/rates/{id}Delete an unused exchange rate - POST
/rest/v1.0/companies/{company_id}/accounting/fx/rates/importImport exchange rates from CSV - GET
/rest/v1.0/companies/{company_id}/accounting/fx/revaluationsList revaluation runs - POST
/rest/v1.0/companies/{company_id}/accounting/fx/revaluationsPrepare a revaluation - GET
/rest/v1.0/companies/{company_id}/accounting/fx/revaluations/{id}Show a revaluation run - POST
/rest/v1.0/companies/{company_id}/accounting/fx/revaluations/{id}/decisionApprove or cancel a revaluation - GET
/rest/v1.0/companies/{company_id}/accounting/fx/revaluations/previewPreview a revaluation - POST
/rest/v1.0/companies/{company_id}/accounting/fx/setupCreate the FX accounts - GET
/rest/v1.0/companies/{company_id}/accounting/fx/translationTranslated trial balance
Accounting / Foreign Currency
GET/rest/v1.0/companies/{company_id}/accounting/fx/entitiesList entity functional currencies
Each entity in the grant's scope with its functional currency (the base currency when unset). Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Response · 200 · object
- base_currencystringrequired
- entitiesobject[]required
- entities[].idintegerrequired
- entities[].codestringrequired
- entities[].namestringrequired
- entities[].functional_currencystringrequired
- entities[].functional_is_basebooleanrequired
- entities[].is_activeboolean
- entities[].is_eliminationboolean
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, entity outside the grant, or read-only token
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/fx/entities" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Foreign Currency
PATCH/rest/v1.0/companies/{company_id}/accounting/fx/entities/{id}Set an entity's functional currency
ASC 830-10-45-2. Allowed only before the entity has posted or unposted entries (a later change is prospective remeasurement, which is not automated); the elimination entity stays in the base currency. Needs manage_coa over every entity. Audited. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- entityobjectrequired
- entity.functional_currencystring | nullrequired
Response · 200 · object
- idintegerrequired
- codestringrequired
- namestringrequired
- functional_currencystringrequired
- functional_is_basebooleanrequired
- is_activeboolean
- is_eliminationboolean
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, entity outside the grant, or read-only token404Not found in this company422Validation failed, a closed period, a missing rate or account mapping
Example request
curl -X PATCH "https://app.os.construction/rest/v1.0/companies/1/accounting/fx/entities/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"entity": {
"functional_currency": "string"
}
}'Accounting / Foreign Currency
GET/rest/v1.0/companies/{company_id}/accounting/fx/ratesList exchange rates
Effective-dated rates (spot, average, historical), newest first, with Total/Per-Page/Link headers. Any accounting grant. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- from_currencystringqueryFilter: from currency
- to_currencystringqueryFilter: to currency
- rate_typestringqueryFilter: rate type One of: spot, average, historical.
- sincestring (date)queryEffective on or after
- untilstring (date)queryEffective on or before
- pageintegerqueryPage number
- per_pageintegerqueryPage size (default 100)
Response · 200 · object[]
- idintegerrequired
- rate_typestringrequiredOne of: spot, average, historical.
- from_currencystringrequired
- to_currencystringrequired
- ratestringrequired
- effective_datestring (date)required
- sourcestringrequiredOne of: manual, csv, provider.
- import_refstring | null
- created_by_idinteger | null
- used_atstring | null (date-time)required
- immutablebooleanrequired
- created_atstring (date-time)
- updated_atstring (date-time)
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, entity outside the grant, or read-only token422Validation failed, a closed period, a missing rate or account mapping
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/fx/rates" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Foreign Currency
POST/rest/v1.0/companies/{company_id}/accounting/fx/ratesAdd an exchange rate
Adds one rate: rate units of to_currency per unit of from_currency, effective on effective_date. Needs manage_coa over every entity. Audited. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- exchange_rateobjectrequired
- exchange_rate.rate_typestringOne of: spot, average, historical.
- exchange_rate.from_currencystringrequired
- exchange_rate.to_currencystringrequired
- exchange_rate.effective_datestring (date)required
- exchange_rate.ratestringrequired
Response · 201 · object
- idintegerrequired
- rate_typestringrequiredOne of: spot, average, historical.
- from_currencystringrequired
- to_currencystringrequired
- ratestringrequired
- effective_datestring (date)required
- sourcestringrequiredOne of: manual, csv, provider.
- import_refstring | null
- created_by_idinteger | null
- used_atstring | null (date-time)required
- immutablebooleanrequired
- created_atstring (date-time)
- updated_atstring (date-time)
Errors
400Malformed JSON body or Idempotency-Key header401Missing or invalid bearer token403No accounting access, missing permission, wrong company, entity outside the grant, or read-only token409Conflict: the rate is used by the ledger, a duplicate rate, or evidence changed since preparation422Validation failed, a closed period, a missing rate or account mapping
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/fx/rates" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"exchange_rate": {
"from_currency": "0.00",
"to_currency": "0.00",
"effective_date": "2026-11-01",
"rate": "0.00"
}
}'Accounting / Foreign Currency
GET/rest/v1.0/companies/{company_id}/accounting/fx/rates/{id}Show an exchange rate
One rate, with whether it is used (immutable). Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object
- idintegerrequired
- rate_typestringrequiredOne of: spot, average, historical.
- from_currencystringrequired
- to_currencystringrequired
- ratestringrequired
- effective_datestring (date)required
- sourcestringrequiredOne of: manual, csv, provider.
- import_refstring | null
- created_by_idinteger | null
- used_atstring | null (date-time)required
- immutablebooleanrequired
- created_atstring (date-time)
- updated_atstring (date-time)
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, entity outside the grant, or read-only token404Not found in this company
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/fx/rates/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Foreign Currency
PATCH/rest/v1.0/companies/{company_id}/accounting/fx/rates/{id}Change an unused exchange rate
Changes the rate or effective date of a rate no posting, document or revaluation has used (409 once used; a database trigger also refuses). Needs manage_coa over every entity. Audited with before and after values. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- exchange_rateobjectrequired
- exchange_rate.ratestringrequired
- exchange_rate.effective_datestring (date)
Response · 200 · object
- idintegerrequired
- rate_typestringrequiredOne of: spot, average, historical.
- from_currencystringrequired
- to_currencystringrequired
- ratestringrequired
- effective_datestring (date)required
- sourcestringrequiredOne of: manual, csv, provider.
- import_refstring | null
- created_by_idinteger | null
- used_atstring | null (date-time)required
- immutablebooleanrequired
- created_atstring (date-time)
- updated_atstring (date-time)
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, entity outside the grant, or read-only token404Not found in this company409Conflict: the rate is used by the ledger, a duplicate rate, or evidence changed since preparation422Validation failed, a closed period, a missing rate or account mapping
Example request
curl -X PATCH "https://app.os.construction/rest/v1.0/companies/1/accounting/fx/rates/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"exchange_rate": {
"rate": "0.00"
}
}'Accounting / Foreign Currency
DELETE/rest/v1.0/companies/{company_id}/accounting/fx/rates/{id}Delete an unused exchange rate
Deletes a rate nothing has used (409 once used). Needs manage_coa over every entity. Audited. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 204
No response body.
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, entity outside the grant, or read-only token404Not found in this company409Conflict: the rate is used by the ledger, a duplicate rate, or evidence changed since preparation
Example request
curl -X DELETE "https://app.os.construction/rest/v1.0/companies/1/accounting/fx/rates/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Foreign Currency
POST/rest/v1.0/companies/{company_id}/accounting/fx/rates/importImport exchange rates from CSV
CSV with header rate_type,from_currency,to_currency,effective_date,rate (rate_type optional, default spot). All or nothing: any invalid row, or a row that would change an existing rate, refuses the file (422; with dry_run the errors are returned). Rows equal to existing rates are unchanged, so re-importing a file is a no-op (natural key). One audit event with the file's sha256. Needs manage_coa over every entity. Returns 201 when rates were created, else 200. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Request body
- importobjectrequired
- import.csvstringrequired
- import.dry_runboolean
Response · 200 · object
- dry_runbooleanrequired
- sha256stringrequired
- createdintegerrequired
- unchangedintegerrequired
- errorsobject[]required
- errors[].lineintegerrequired
- errors[].messagestringrequired
- rowsobject[]required
- rows[].lineinteger
- rows[].rate_typestring
- rows[].from_currencystring
- rows[].to_currencystring
- rows[].effective_datestring (date)
- rows[].ratestring
- rows[].actionstringOne of: create, unchanged.
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, entity outside the grant, or read-only token422Validation failed, a closed period, a missing rate or account mapping
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/fx/rates/import" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"import": {
"csv": "string"
}
}'Accounting / Foreign Currency
GET/rest/v1.0/companies/{company_id}/accounting/fx/revaluationsList revaluation runs
Month-end revaluation runs, newest first (at most 200), in the grant's entities. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- entity_idintegerqueryFilter: entity
- period_idintegerqueryFilter: period
Response · 200 · object[]
- idintegerrequired
- entity_idintegerrequired
- period_idintegerrequired
- revisionintegerrequired
- statusstringrequiredOne of: prepared, posted, cancelled, superseded.
- as_ofstring (date)required
- reverse_onstring (date)required
- evidence_hashstringrequired
- linesobject[]required
- lines[].account_idintegerrequired
- lines[].currencystringrequired
- lines[].txn_balancestringrequired
- lines[].functional_balancestringrequired
- lines[].ratestringrequired
- lines[].targetstringrequired
- lines[].adjustmentstringrequired
- ratesobject[]required
- total_gainstringrequired
- total_lossstringrequired
- net_gainstringrequired
- prepared_by_idintegerrequired
- prepared_atstring (date-time)required
- approved_by_idinteger | nullrequired
- approved_atstring | null (date-time)required
- entry_idinteger | nullrequired
- cancel_reasonstring | null
- unchangedboolean
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, entity outside the grant, or read-only token
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/fx/revaluations" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Foreign Currency
POST/rest/v1.0/companies/{company_id}/accounting/fx/revaluationsPrepare a revaluation
ASC 830-20-35-1: restates the entity's foreign-currency cash, receivable, payable and intercompany balances at the period-end spot rate. Saves a prepared run with its lines, rates and evidence hash; nothing posts until a different user approves. Natural key: at most one prepared run per entity and period; preparing again with unchanged balances and rates returns the current run (200, unchanged: true). Refused (422) in a closed period, when the next period (where it reverses) is missing or closed, when a prior revaluation has not yet auto-reversed, or when no gain/loss account is mapped. Needs post_journal and the entity in the grant. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Request body
- revaluationobjectrequired
- revaluation.entity_idintegerrequired
- revaluation.period_idintegerrequired
Response · 200 · object
- idintegerrequired
- entity_idintegerrequired
- period_idintegerrequired
- revisionintegerrequired
- statusstringrequiredOne of: prepared, posted, cancelled, superseded.
- as_ofstring (date)required
- reverse_onstring (date)required
- evidence_hashstringrequired
- linesobject[]required
- lines[].account_idintegerrequired
- lines[].currencystringrequired
- lines[].txn_balancestringrequired
- lines[].functional_balancestringrequired
- lines[].ratestringrequired
- lines[].targetstringrequired
- lines[].adjustmentstringrequired
- ratesobject[]required
- total_gainstringrequired
- total_lossstringrequired
- net_gainstringrequired
- prepared_by_idintegerrequired
- prepared_atstring (date-time)required
- approved_by_idinteger | nullrequired
- approved_atstring | null (date-time)required
- entry_idinteger | nullrequired
- cancel_reasonstring | null
- unchangedboolean
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, entity outside the grant, or read-only token404Not found in this company422Validation failed, a closed period, a missing rate or account mapping
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/fx/revaluations" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"revaluation": {
"entity_id": 1,
"period_id": 1
}
}'Accounting / Foreign Currency
GET/rest/v1.0/companies/{company_id}/accounting/fx/revaluations/{id}Show a revaluation run
One run with its lines, rates and posting. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object
- idintegerrequired
- entity_idintegerrequired
- period_idintegerrequired
- revisionintegerrequired
- statusstringrequiredOne of: prepared, posted, cancelled, superseded.
- as_ofstring (date)required
- reverse_onstring (date)required
- evidence_hashstringrequired
- linesobject[]required
- lines[].account_idintegerrequired
- lines[].currencystringrequired
- lines[].txn_balancestringrequired
- lines[].functional_balancestringrequired
- lines[].ratestringrequired
- lines[].targetstringrequired
- lines[].adjustmentstringrequired
- ratesobject[]required
- total_gainstringrequired
- total_lossstringrequired
- net_gainstringrequired
- prepared_by_idintegerrequired
- prepared_atstring (date-time)required
- approved_by_idinteger | nullrequired
- approved_atstring | null (date-time)required
- entry_idinteger | nullrequired
- cancel_reasonstring | null
- unchangedboolean
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, entity outside the grant, or read-only token404Not found in this company
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/fx/revaluations/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Foreign Currency
POST/rest/v1.0/companies/{company_id}/accounting/fx/revaluations/{id}/decisionApprove or cancel a revaluation
approve (approve_journal, never the preparer): recomputes the evidence (409 if balances or rates moved), posts the GJ entry dated the period end, auto-reversing on the next period's first day, and stamps the rates used. cancel (post_journal, with a reason) withdraws a prepared run. A repeat of a finished decision returns the run. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- decisionobjectrequired
- decision.actionstringrequiredOne of: approve, cancel.
- decision.reasonstring
Response · 200 · object
- idintegerrequired
- entity_idintegerrequired
- period_idintegerrequired
- revisionintegerrequired
- statusstringrequiredOne of: prepared, posted, cancelled, superseded.
- as_ofstring (date)required
- reverse_onstring (date)required
- evidence_hashstringrequired
- linesobject[]required
- lines[].account_idintegerrequired
- lines[].currencystringrequired
- lines[].txn_balancestringrequired
- lines[].functional_balancestringrequired
- lines[].ratestringrequired
- lines[].targetstringrequired
- lines[].adjustmentstringrequired
- ratesobject[]required
- total_gainstringrequired
- total_lossstringrequired
- net_gainstringrequired
- prepared_by_idintegerrequired
- prepared_atstring (date-time)required
- approved_by_idinteger | nullrequired
- approved_atstring | null (date-time)required
- entry_idinteger | nullrequired
- cancel_reasonstring | null
- unchangedboolean
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, entity outside the grant, or read-only token404Not found in this company409Conflict: the rate is used by the ledger, a duplicate rate, or evidence changed since preparation422Validation failed, a closed period, a missing rate or account mapping
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/fx/revaluations/1/decision" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"decision": {
"action": "approve"
}
}'Accounting / Foreign Currency
GET/rest/v1.0/companies/{company_id}/accounting/fx/revaluations/previewPreview a revaluation
What a revaluation of the entity for the period would post now. No write. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- entity_idintegerqueryrequiredEntity
- period_idintegerqueryrequiredPeriod
Response · 200 · object
- as_ofstring (date)required
- functional_currencystringrequired
- linesobject[]required
- lines[].account_idintegerrequired
- lines[].currencystringrequired
- lines[].txn_balancestringrequired
- lines[].functional_balancestringrequired
- lines[].ratestringrequired
- lines[].targetstringrequired
- lines[].adjustmentstringrequired
- ratesobject[]required
- net_gainstringrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, entity outside the grant, or read-only token404Not found in this company422Validation failed, a closed period, a missing rate or account mapping
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/fx/revaluations/preview" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Foreign Currency
POST/rest/v1.0/companies/{company_id}/accounting/fx/setupCreate the FX accounts
Creates and maps any missing FX_GAIN_LOSS (7500), FX_UNREALIZED_GAIN_LOSS (7510) and CTA (3600, accumulated other comprehensive income) accounts. Idempotent: nothing is created when every role is mapped (200). Needs manage_coa over every entity. Audited. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Response · 200 · object
- createdobject[]required
- created[].rolestringrequired
- created[].account_idintegerrequired
- created[].numberstringrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, entity outside the grant, or read-only token
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/fx/setup" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Foreign Currency
GET/rest/v1.0/companies/{company_id}/accounting/fx/translationTranslated trial balance
ASC 830-30 current rate method for one entity as of a date: assets and liabilities at the closing rate (reporting-currency balances at their transaction amount), income and expense at monthly average rates, equity at historical rates, prior years' earnings in retained earnings, and the cumulative translation adjustment. Lists the rates used. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- entity_idintegerqueryrequiredEntity
- as_ofstring (date)queryrequiredAs-of date
Response · 200 · object
- entity_idintegerrequired
- as_ofstring (date)required
- functional_currencystringrequired
- reporting_currencystringrequired
- linesobject[]required
- lines[].account_idintegerrequired
- lines[].numberstring | null
- lines[].namestring | null
- lines[].typestring | null
- lines[].netstringrequired
- ctastringrequired
- net_incomestringrequired
- ratesstring[]required
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, entity outside the grant, or read-only token404Not found in this company422Validation failed, a closed period, a missing rate or account mapping
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/fx/translation" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"