Esc

↑↓ move↵ openIndex · Pagefind
REST reference · Financial Management

Expense Reports

8 endpoints8 implementedAll modules →
  1. GET /rest/v1.0/projects/{project_id}/expense_reports
  2. POST /rest/v1.0/projects/{project_id}/expense_reports
  3. GET /rest/v1.0/projects/{project_id}/expense_reports/{id}
  4. PATCH /rest/v1.0/projects/{project_id}/expense_reports/{id}
  5. GET /rest/v1.0/projects/{project_id}/expense_reports/{id}/reimbursement
  6. POST /rest/v1.0/projects/{project_id}/expense_reports/{id}/reimbursement
  7. POST /rest/v1.0/projects/{project_id}/expense_reports/{id}/transitions
  8. POST /rest/v1.0/projects/{project_id}/expense_reports/reimbursement_payees
GET /rest/v1.0/projects/{project_id}/expense_reports

GET projects/{project_id}/expense_reports

v1.0Implemented

Parameters

  • project_id
    integerpathrequired
  • page
    integerquery
  • per_page
    integerquery
  • status
    stringquery
    One of: draft, submitted, returned, rejected, approved.

Response · 200 · object[]

  • id
    integerrequired
  • number
    stringrequired
  • project_id
    integerrequired
  • status
    stringrequired
    One of: draft, submitted, returned, rejected, approved.
  • revision
    integerrequired
  • version
    integerrequired
  • created_by_id
    integerrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • revisions
    object[]required
  • revisions[].revision
    integerrequired
  • revisions[].merchant
    stringrequired
  • revisions[].purpose
    stringrequired
  • revisions[].occurred_on
    string (date)required
  • revisions[].currency
    stringrequired
  • revisions[].created_at
    string (date-time)required
  • revisions[].total
    stringrequired
  • revisions[].exception
    object | nullrequired
  • revisions[].lines
    object[]required
  • revisions[].unavailable_evidence_count
    integerrequired
  • revisions[].evidence
    object[]required
  • decisions
    object[]required
  • decisions[].revision
    integerrequired
  • decisions[].version
    integerrequired
  • decisions[].action
    stringrequired
  • decisions[].reason
    stringrequired
  • decisions[].actor_id
    integerrequired
  • decisions[].evidence_disposition
    stringrequired
    One of: none, receipt_reviewed, exception_accepted.
  • decisions[].created_at
    string (date-time)required

Errors

  • 401Unauthenticated
  • 403Permission or source scope denied
  • 404Not found or not visible
  • 409Stale version or invalid transition
  • 422Invalid input or evidence

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/projects/1/expense_reports" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
POST /rest/v1.0/projects/{project_id}/expense_reports

POST projects/{project_id}/expense_reports

v1.0Implemented

Parameters

  • project_id
    integerpathrequired
  • Idempotency-Key
    stringheader
    Optional. 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

  • report
    objectrequired
    Provide exactly one receipt basis: nonempty evidence or missing-receipt exception. No currency conversion. Claimant is the authenticated creator.
  • report.merchant
    stringrequired
  • report.purpose
    stringrequired
  • report.occurred_on
    string (date)required
  • report.currency
    stringrequired
    Supported two-decimal currencies; no exchange conversion. One of: USD, CAD, EUR, GBP, AUD, NZD, CHF.
  • report.lines
    object[]required
  • report.lines[].description
    stringrequired
  • report.lines[].cost_code_id
    integerrequired
  • report.lines[].amount
    stringrequired
    Positive decimal, maximum 9999999999.99, at most two fractional digits; zero rejected.
  • report.evidence
    object[]
  • report.evidence[].file_id
    integerrequired
  • report.evidence[].document_version_id
    integerrequired
  • report.exception
    object | null
  • report.exception.kind
    stringrequired
    One of: lost_receipt, merchant_not_issued.
  • report.exception.reason
    stringrequired
  • request_key
    string (uuid)required
    Stable claimant-scoped key; replay returns the original report, changed payload returns409.

Response · 201 · object

  • id
    integerrequired
  • number
    stringrequired
  • project_id
    integerrequired
  • status
    stringrequired
    One of: draft, submitted, returned, rejected, approved.
  • revision
    integerrequired
  • version
    integerrequired
  • created_by_id
    integerrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • revisions
    object[]required
  • revisions[].revision
    integerrequired
  • revisions[].merchant
    stringrequired
  • revisions[].purpose
    stringrequired
  • revisions[].occurred_on
    string (date)required
  • revisions[].currency
    stringrequired
  • revisions[].created_at
    string (date-time)required
  • revisions[].total
    stringrequired
  • revisions[].exception
    object | nullrequired
  • revisions[].lines
    object[]required
  • revisions[].unavailable_evidence_count
    integerrequired
  • revisions[].evidence
    object[]required
  • decisions
    object[]required
  • decisions[].revision
    integerrequired
  • decisions[].version
    integerrequired
  • decisions[].action
    stringrequired
  • decisions[].reason
    stringrequired
  • decisions[].actor_id
    integerrequired
  • decisions[].evidence_disposition
    stringrequired
    One of: none, receipt_reviewed, exception_accepted.
  • decisions[].created_at
    string (date-time)required

Errors

  • 401Unauthenticated
  • 403Permission or source scope denied
  • 404Not found or not visible
  • 409Stale version or invalid transition
  • 422Invalid input or evidence

Example request

Generated from the contractcurl
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"
}'
GET /rest/v1.0/projects/{project_id}/expense_reports/{id}

GET projects/{project_id}/expense_reports/{id}

v1.0Implemented

Parameters

  • project_id
    integerpathrequired
  • id
    integerpathrequired

Response · 200 · object

  • id
    integerrequired
  • number
    stringrequired
  • project_id
    integerrequired
  • status
    stringrequired
    One of: draft, submitted, returned, rejected, approved.
  • revision
    integerrequired
  • version
    integerrequired
  • created_by_id
    integerrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • revisions
    object[]required
  • revisions[].revision
    integerrequired
  • revisions[].merchant
    stringrequired
  • revisions[].purpose
    stringrequired
  • revisions[].occurred_on
    string (date)required
  • revisions[].currency
    stringrequired
  • revisions[].created_at
    string (date-time)required
  • revisions[].total
    stringrequired
  • revisions[].exception
    object | nullrequired
  • revisions[].lines
    object[]required
  • revisions[].unavailable_evidence_count
    integerrequired
  • revisions[].evidence
    object[]required
  • decisions
    object[]required
  • decisions[].revision
    integerrequired
  • decisions[].version
    integerrequired
  • decisions[].action
    stringrequired
  • decisions[].reason
    stringrequired
  • decisions[].actor_id
    integerrequired
  • decisions[].evidence_disposition
    stringrequired
    One of: none, receipt_reviewed, exception_accepted.
  • decisions[].created_at
    string (date-time)required

Errors

  • 401Unauthenticated
  • 403Permission or source scope denied
  • 404Not found or not visible
  • 409Stale version or invalid transition
  • 422Invalid input or evidence

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/projects/1/expense_reports/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
PATCH /rest/v1.0/projects/{project_id}/expense_reports/{id}

PATCH projects/{project_id}/expense_reports/{id}

v1.0Implemented

Parameters

  • project_id
    integerpathrequired
  • id
    integerpathrequired
  • Idempotency-Key
    stringheader
    Optional. 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_version
    integerrequired
  • report
    objectrequired
    Provide exactly one receipt basis: nonempty evidence or missing-receipt exception. No currency conversion. Claimant is the authenticated creator.
  • report.merchant
    stringrequired
  • report.purpose
    stringrequired
  • report.occurred_on
    string (date)required
  • report.currency
    stringrequired
    Supported two-decimal currencies; no exchange conversion. One of: USD, CAD, EUR, GBP, AUD, NZD, CHF.
  • report.lines
    object[]required
  • report.lines[].description
    stringrequired
  • report.lines[].cost_code_id
    integerrequired
  • report.lines[].amount
    stringrequired
    Positive decimal, maximum 9999999999.99, at most two fractional digits; zero rejected.
  • report.evidence
    object[]
  • report.evidence[].file_id
    integerrequired
  • report.evidence[].document_version_id
    integerrequired
  • report.exception
    object | null
  • report.exception.kind
    stringrequired
    One of: lost_receipt, merchant_not_issued.
  • report.exception.reason
    stringrequired

Response · 200 · object

  • id
    integerrequired
  • number
    stringrequired
  • project_id
    integerrequired
  • status
    stringrequired
    One of: draft, submitted, returned, rejected, approved.
  • revision
    integerrequired
  • version
    integerrequired
  • created_by_id
    integerrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • revisions
    object[]required
  • revisions[].revision
    integerrequired
  • revisions[].merchant
    stringrequired
  • revisions[].purpose
    stringrequired
  • revisions[].occurred_on
    string (date)required
  • revisions[].currency
    stringrequired
  • revisions[].created_at
    string (date-time)required
  • revisions[].total
    stringrequired
  • revisions[].exception
    object | nullrequired
  • revisions[].lines
    object[]required
  • revisions[].unavailable_evidence_count
    integerrequired
  • revisions[].evidence
    object[]required
  • decisions
    object[]required
  • decisions[].revision
    integerrequired
  • decisions[].version
    integerrequired
  • decisions[].action
    stringrequired
  • decisions[].reason
    stringrequired
  • decisions[].actor_id
    integerrequired
  • decisions[].evidence_disposition
    stringrequired
    One of: none, receipt_reviewed, exception_accepted.
  • decisions[].created_at
    string (date-time)required

Errors

  • 401Unauthenticated
  • 403Permission or source scope denied
  • 404Not found or not visible
  • 409Stale version or invalid transition
  • 422Invalid input or evidence

Example request

Generated from the contractcurl
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"
      }
    ]
  }
}'
GET /rest/v1.0/projects/{project_id}/expense_reports/{id}/reimbursement

GET 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.

v1.0Implemented

Parameters

  • project_id
    integerpathrequired
  • id
    integerpathrequired

Response · 200 · object

No documented fields.

Errors

  • 401Unauthenticated
  • 403Scope, independent actor, evidence or accounting authority refused
  • 404Not found
  • 409Stale claim/mapping, changed retry or existing handoff
  • 422Invalid payee, account, currency or evidence

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/projects/1/expense_reports/1/reimbursement" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
POST /rest/v1.0/projects/{project_id}/expense_reports/{id}/reimbursement

POST 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.

v1.0Implemented

Parameters

  • project_id
    integerpathrequired
  • id
    integerpathrequired
  • Idempotency-Key
    stringheader
    Optional. 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_version
    integerrequired
  • mapping_version
    integerrequired
  • reason
    stringrequired
  • lines
    object[]required
  • lines[].claim_line_id
    integerrequired
  • lines[].account_id
    integerrequired

Response · 200 · object

  • id
    integerrequired
  • bill_id
    integerrequired
  • report_id
    integerrequired
  • currency
    stringrequired
  • total
    stringrequired
  • replayed
    booleanrequired

Errors

  • 401Unauthenticated
  • 403Scope, independent actor, evidence or accounting authority refused
  • 404Not found
  • 409Stale claim/mapping, changed retry or existing handoff
  • 422Invalid payee, account, currency or evidence

Example request

Generated from the contractcurl
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
    }
  ]
}'
POST /rest/v1.0/projects/{project_id}/expense_reports/{id}/transitions

POST projects/{project_id}/expense_reports/{id}/transitions

v1.0Implemented

Parameters

  • project_id
    integerpathrequired
  • id
    integerpathrequired
  • Idempotency-Key
    stringheader
    Optional. 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_version
    integerrequired
  • action
    stringrequired
    One of: submit, approve, return, reject.
  • reason
    string
  • accept_missing_receipt
    boolean

Response · 200 · object

  • id
    integerrequired
  • number
    stringrequired
  • project_id
    integerrequired
  • status
    stringrequired
    One of: draft, submitted, returned, rejected, approved.
  • revision
    integerrequired
  • version
    integerrequired
  • created_by_id
    integerrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • revisions
    object[]required
  • revisions[].revision
    integerrequired
  • revisions[].merchant
    stringrequired
  • revisions[].purpose
    stringrequired
  • revisions[].occurred_on
    string (date)required
  • revisions[].currency
    stringrequired
  • revisions[].created_at
    string (date-time)required
  • revisions[].total
    stringrequired
  • revisions[].exception
    object | nullrequired
  • revisions[].lines
    object[]required
  • revisions[].unavailable_evidence_count
    integerrequired
  • revisions[].evidence
    object[]required
  • decisions
    object[]required
  • decisions[].revision
    integerrequired
  • decisions[].version
    integerrequired
  • decisions[].action
    stringrequired
  • decisions[].reason
    stringrequired
  • decisions[].actor_id
    integerrequired
  • decisions[].evidence_disposition
    stringrequired
    One of: none, receipt_reviewed, exception_accepted.
  • decisions[].created_at
    string (date-time)required

Errors

  • 401Unauthenticated
  • 403Permission or source scope denied
  • 404Not found or not visible
  • 409Stale version or invalid transition
  • 422Invalid input or evidence

Example request

Generated from the contractcurl
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"
}'
POST /rest/v1.0/projects/{project_id}/expense_reports/reimbursement_payees

POST 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.

v1.0Implemented

Parameters

  • project_id
    integerpathrequired
  • Idempotency-Key
    stringheader
    Optional. 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_id
    integerrequired
  • vendor_id
    integerrequired
  • expected_version
    integerrequired
  • reason
    stringrequired

Response · 200 · object

  • id
    integerrequired
  • claimant_id
    integerrequired
  • vendor_id
    integerrequired
  • version
    integerrequired

Errors

  • 401Unauthenticated
  • 403Scope, independent actor, evidence or accounting authority refused
  • 404Not found
  • 409Stale claim/mapping, changed retry or existing handoff
  • 422Invalid payee, account, currency or evidence

Example request

Generated from the contractcurl
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"
}'

Ask the OS

Reading this page

Ask anything about this page. Answers use what you're reading as context.

Suggested

    AI · may be imperfect · sample data where shown

    Open file