Expense Reports
- GET
/rest/v1.0/projects/{project_id}/expense_reports - POST
/rest/v1.0/projects/{project_id}/expense_reports - GET
/rest/v1.0/projects/{project_id}/expense_reports/{id} - PATCH
/rest/v1.0/projects/{project_id}/expense_reports/{id} - GET
/rest/v1.0/projects/{project_id}/expense_reports/{id}/reimbursement - POST
/rest/v1.0/projects/{project_id}/expense_reports/{id}/reimbursement - POST
/rest/v1.0/projects/{project_id}/expense_reports/{id}/transitions - POST
/rest/v1.0/projects/{project_id}/expense_reports/reimbursement_payees
/rest/v1.0/projects/{project_id}/expense_reportsGET projects/{project_id}/expense_reports
Parameters
- project_idintegerpathrequired
- pageintegerquery
- per_pageintegerquery
- statusstringqueryOne of: draft, submitted, returned, rejected, approved.
Response · 200 · object[]
- idintegerrequired
- numberstringrequired
- project_idintegerrequired
- statusstringrequiredOne of: draft, submitted, returned, rejected, approved.
- revisionintegerrequired
- versionintegerrequired
- created_by_idintegerrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
- revisionsobject[]required
- revisions[].revisionintegerrequired
- revisions[].merchantstringrequired
- revisions[].purposestringrequired
- revisions[].occurred_onstring (date)required
- revisions[].currencystringrequired
- revisions[].created_atstring (date-time)required
- revisions[].totalstringrequired
- revisions[].exceptionobject | nullrequired
- revisions[].linesobject[]required
- revisions[].unavailable_evidence_countintegerrequired
- revisions[].evidenceobject[]required
- decisionsobject[]required
- decisions[].revisionintegerrequired
- decisions[].versionintegerrequired
- decisions[].actionstringrequired
- decisions[].reasonstringrequired
- decisions[].actor_idintegerrequired
- decisions[].evidence_dispositionstringrequiredOne of: none, receipt_reviewed, exception_accepted.
- decisions[].created_atstring (date-time)required
Errors
401Unauthenticated403Permission or source scope denied404Not found or not visible409Stale version or invalid transition422Invalid input or evidence
Example request
curl -X GET "https://app.os.construction/rest/v1.0/projects/1/expense_reports" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"/rest/v1.0/projects/{project_id}/expense_reportsPOST projects/{project_id}/expense_reports
Parameters
- project_idintegerpathrequired
- Idempotency-KeystringheaderOptional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.
Request body
- reportobjectrequiredProvide exactly one receipt basis: nonempty evidence or missing-receipt exception. No currency conversion. Claimant is the authenticated creator.
- report.merchantstringrequired
- report.purposestringrequired
- report.occurred_onstring (date)required
- report.currencystringrequiredSupported two-decimal currencies; no exchange conversion. One of: USD, CAD, EUR, GBP, AUD, NZD, CHF.
- report.linesobject[]required
- report.lines[].descriptionstringrequired
- report.lines[].cost_code_idintegerrequired
- report.lines[].amountstringrequiredPositive decimal, maximum 9999999999.99, at most two fractional digits; zero rejected.
- report.evidenceobject[]
- report.evidence[].file_idintegerrequired
- report.evidence[].document_version_idintegerrequired
- report.exceptionobject | null
- report.exception.kindstringrequiredOne of: lost_receipt, merchant_not_issued.
- report.exception.reasonstringrequired
- request_keystring (uuid)requiredStable claimant-scoped key; replay returns the original report, changed payload returns409.
Response · 201 · object
- idintegerrequired
- numberstringrequired
- project_idintegerrequired
- statusstringrequiredOne of: draft, submitted, returned, rejected, approved.
- revisionintegerrequired
- versionintegerrequired
- created_by_idintegerrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
- revisionsobject[]required
- revisions[].revisionintegerrequired
- revisions[].merchantstringrequired
- revisions[].purposestringrequired
- revisions[].occurred_onstring (date)required
- revisions[].currencystringrequired
- revisions[].created_atstring (date-time)required
- revisions[].totalstringrequired
- revisions[].exceptionobject | nullrequired
- revisions[].linesobject[]required
- revisions[].unavailable_evidence_countintegerrequired
- revisions[].evidenceobject[]required
- decisionsobject[]required
- decisions[].revisionintegerrequired
- decisions[].versionintegerrequired
- decisions[].actionstringrequired
- decisions[].reasonstringrequired
- decisions[].actor_idintegerrequired
- decisions[].evidence_dispositionstringrequiredOne of: none, receipt_reviewed, exception_accepted.
- decisions[].created_atstring (date-time)required
Errors
401Unauthenticated403Permission or source scope denied404Not found or not visible409Stale version or invalid transition422Invalid input or evidence
Example request
curl -X POST "https://app.os.construction/rest/v1.0/projects/1/expense_reports" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"report": {
"merchant": "string",
"purpose": "string",
"occurred_on": "2026-11-01",
"currency": "USD",
"lines": [
{
"description": "string",
"cost_code_id": 1,
"amount": "0.00"
}
]
},
"request_key": "00000000-0000-4000-8000-000000000000"
}'/rest/v1.0/projects/{project_id}/expense_reports/{id}GET projects/{project_id}/expense_reports/{id}
Parameters
- project_idintegerpathrequired
- idintegerpathrequired
Response · 200 · object
- idintegerrequired
- numberstringrequired
- project_idintegerrequired
- statusstringrequiredOne of: draft, submitted, returned, rejected, approved.
- revisionintegerrequired
- versionintegerrequired
- created_by_idintegerrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
- revisionsobject[]required
- revisions[].revisionintegerrequired
- revisions[].merchantstringrequired
- revisions[].purposestringrequired
- revisions[].occurred_onstring (date)required
- revisions[].currencystringrequired
- revisions[].created_atstring (date-time)required
- revisions[].totalstringrequired
- revisions[].exceptionobject | nullrequired
- revisions[].linesobject[]required
- revisions[].unavailable_evidence_countintegerrequired
- revisions[].evidenceobject[]required
- decisionsobject[]required
- decisions[].revisionintegerrequired
- decisions[].versionintegerrequired
- decisions[].actionstringrequired
- decisions[].reasonstringrequired
- decisions[].actor_idintegerrequired
- decisions[].evidence_dispositionstringrequiredOne of: none, receipt_reviewed, exception_accepted.
- decisions[].created_atstring (date-time)required
Errors
401Unauthenticated403Permission or source scope denied404Not found or not visible409Stale version or invalid transition422Invalid input or evidence
Example request
curl -X GET "https://app.os.construction/rest/v1.0/projects/1/expense_reports/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"/rest/v1.0/projects/{project_id}/expense_reports/{id}PATCH projects/{project_id}/expense_reports/{id}
Parameters
- project_idintegerpathrequired
- idintegerpathrequired
- Idempotency-KeystringheaderOptional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.
Request body
- expected_versionintegerrequired
- reportobjectrequiredProvide exactly one receipt basis: nonempty evidence or missing-receipt exception. No currency conversion. Claimant is the authenticated creator.
- report.merchantstringrequired
- report.purposestringrequired
- report.occurred_onstring (date)required
- report.currencystringrequiredSupported two-decimal currencies; no exchange conversion. One of: USD, CAD, EUR, GBP, AUD, NZD, CHF.
- report.linesobject[]required
- report.lines[].descriptionstringrequired
- report.lines[].cost_code_idintegerrequired
- report.lines[].amountstringrequiredPositive decimal, maximum 9999999999.99, at most two fractional digits; zero rejected.
- report.evidenceobject[]
- report.evidence[].file_idintegerrequired
- report.evidence[].document_version_idintegerrequired
- report.exceptionobject | null
- report.exception.kindstringrequiredOne of: lost_receipt, merchant_not_issued.
- report.exception.reasonstringrequired
Response · 200 · object
- idintegerrequired
- numberstringrequired
- project_idintegerrequired
- statusstringrequiredOne of: draft, submitted, returned, rejected, approved.
- revisionintegerrequired
- versionintegerrequired
- created_by_idintegerrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
- revisionsobject[]required
- revisions[].revisionintegerrequired
- revisions[].merchantstringrequired
- revisions[].purposestringrequired
- revisions[].occurred_onstring (date)required
- revisions[].currencystringrequired
- revisions[].created_atstring (date-time)required
- revisions[].totalstringrequired
- revisions[].exceptionobject | nullrequired
- revisions[].linesobject[]required
- revisions[].unavailable_evidence_countintegerrequired
- revisions[].evidenceobject[]required
- decisionsobject[]required
- decisions[].revisionintegerrequired
- decisions[].versionintegerrequired
- decisions[].actionstringrequired
- decisions[].reasonstringrequired
- decisions[].actor_idintegerrequired
- decisions[].evidence_dispositionstringrequiredOne of: none, receipt_reviewed, exception_accepted.
- decisions[].created_atstring (date-time)required
Errors
401Unauthenticated403Permission or source scope denied404Not found or not visible409Stale version or invalid transition422Invalid input or evidence
Example request
curl -X PATCH "https://app.os.construction/rest/v1.0/projects/1/expense_reports/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"expected_version": 1,
"report": {
"merchant": "string",
"purpose": "string",
"occurred_on": "2026-11-01",
"currency": "USD",
"lines": [
{
"description": "string",
"cost_code_id": 1,
"amount": "0.00"
}
]
}
}'/rest/v1.0/projects/{project_id}/expense_reports/{id}/reimbursementGET projects/{project_id}/expense_reports/{id}/reimbursement
Requires expense report admin, expense_reports:read/write and accounting:write; returns management choices without receipt URLs. Receipt evidence additionally requires documents:read and live ACL access.
Parameters
- project_idintegerpathrequired
- idintegerpathrequired
Response · 200 · object
No documented fields.
Errors
401Unauthenticated403Scope, independent actor, evidence or accounting authority refused404Not found409Stale claim/mapping, changed retry or existing handoff422Invalid payee, account, currency or evidence
Example request
curl -X GET "https://app.os.construction/rest/v1.0/projects/1/expense_reports/1/reimbursement" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"/rest/v1.0/projects/{project_id}/expense_reports/{id}/reimbursementPOST projects/{project_id}/expense_reports/{id}/reimbursement
Creates only a draft AP bill from the current approved revision. Explicit verified employee/payee mapping; claimant, reviewer and converter must differ. Currency must match both company base and entity functional currency. Amount, company, entity and payee cannot be supplied. Identical same-converter request replays its original bill forever, including after void. Changed retry conflicts. Source evidence remains protected in Expense Reports.
Parameters
- project_idintegerpathrequired
- idintegerpathrequired
- Idempotency-KeystringheaderOptional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.
Request body
- expected_versionintegerrequired
- mapping_versionintegerrequired
- reasonstringrequired
- linesobject[]required
- lines[].claim_line_idintegerrequired
- lines[].account_idintegerrequired
Response · 200 · object
- idintegerrequired
- bill_idintegerrequired
- report_idintegerrequired
- currencystringrequired
- totalstringrequired
- replayedbooleanrequired
Errors
401Unauthenticated403Scope, independent actor, evidence or accounting authority refused404Not found409Stale claim/mapping, changed retry or existing handoff422Invalid payee, account, currency or evidence
Example request
curl -X POST "https://app.os.construction/rest/v1.0/projects/1/expense_reports/1/reimbursement" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"expected_version": 1,
"mapping_version": 1,
"reason": "string",
"lines": [
{
"claim_line_id": 1,
"account_id": 1
}
]
}'/rest/v1.0/projects/{project_id}/expense_reports/{id}/transitionsPOST projects/{project_id}/expense_reports/{id}/transitions
Parameters
- project_idintegerpathrequired
- idintegerpathrequired
- Idempotency-KeystringheaderOptional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.
Request body
- expected_versionintegerrequired
- actionstringrequiredOne of: submit, approve, return, reject.
- reasonstring
- accept_missing_receiptboolean
Response · 200 · object
- idintegerrequired
- numberstringrequired
- project_idintegerrequired
- statusstringrequiredOne of: draft, submitted, returned, rejected, approved.
- revisionintegerrequired
- versionintegerrequired
- created_by_idintegerrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
- revisionsobject[]required
- revisions[].revisionintegerrequired
- revisions[].merchantstringrequired
- revisions[].purposestringrequired
- revisions[].occurred_onstring (date)required
- revisions[].currencystringrequired
- revisions[].created_atstring (date-time)required
- revisions[].totalstringrequired
- revisions[].exceptionobject | nullrequired
- revisions[].linesobject[]required
- revisions[].unavailable_evidence_countintegerrequired
- revisions[].evidenceobject[]required
- decisionsobject[]required
- decisions[].revisionintegerrequired
- decisions[].versionintegerrequired
- decisions[].actionstringrequired
- decisions[].reasonstringrequired
- decisions[].actor_idintegerrequired
- decisions[].evidence_dispositionstringrequiredOne of: none, receipt_reviewed, exception_accepted.
- decisions[].created_atstring (date-time)required
Errors
401Unauthenticated403Permission or source scope denied404Not found or not visible409Stale version or invalid transition422Invalid input or evidence
Example request
curl -X POST "https://app.os.construction/rest/v1.0/projects/1/expense_reports/1/transitions" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"expected_version": 1,
"action": "submit"
}'/rest/v1.0/projects/{project_id}/expense_reports/reimbursement_payeesPOST projects/{project_id}/expense_reports/reimbursement_payees
Requires expense report admin, accounting manageVendorBanking with unrestricted entity access, accounting step-up, expense_reports:read/write and accounting:write scopes. Active same-company project claimant and payee; mapper cannot be claimant. One vendor maps to one claimant. expected_version=0 creates; changes use current version and an audited identity-verification reason.
Parameters
- project_idintegerpathrequired
- Idempotency-KeystringheaderOptional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.
Request body
- claimant_idintegerrequired
- vendor_idintegerrequired
- expected_versionintegerrequired
- reasonstringrequired
Response · 200 · object
- idintegerrequired
- claimant_idintegerrequired
- vendor_idintegerrequired
- versionintegerrequired
Errors
401Unauthenticated403Scope, independent actor, evidence or accounting authority refused404Not found409Stale claim/mapping, changed retry or existing handoff422Invalid payee, account, currency or evidence
Example request
curl -X POST "https://app.os.construction/rest/v1.0/projects/1/expense_reports/reimbursement_payees" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"claimant_id": 1,
"vendor_id": 1,
"expected_version": 1,
"reason": "string"
}'