Skip to main content

Agent Workorder Document API

Endpoint added in BIRCH backend for agents to request generated workorder documents without driving the browser UI.

Endpoint​

POST /agent/workorder-documents

Production base URL when deployed:

https://birchbackend.ihrailsoftware.com/agent/workorder-documents

Auth​

Required header:

Authorization: Bearer <BIRCH_AGENT_DOCUMENT_API_KEY>

The backend intentionally returns 503 if BIRCH_AGENT_DOCUMENT_API_KEY or AGENT_DOCUMENT_API_KEY is not configured in the backend environment. Do not expose this key in frontend code.

Request body​

Use either work_order or work_id.

{
  "work_order": "WO_05926",
  "document_type": "brc",
  "bill_to": "owner"
}

document_type values​

  • brc
  • arr-500b
  • invoice
  • bbom
  • work-order

Aliases accepted:

  • aar or aar-500b → arr-500b
  • bom → bbom
  • workorder or wo → work-order

bill_to values​

  • owner
  • lessee
  • third_party
  • combined
  • all

Aliases accepted:

  • leasee → lessee
  • 3rd_party / thirdparty → third_party

For BRC/ARR/Invoice, the mapping matches the existing BIRCH frontend behavior:

  • combined → frontend forWhom = 1
  • owner → frontend forWhom = 2
  • lessee → frontend forWhom = 3
  • third_party → frontend forWhom = 4

all generates owner plus whichever of lessee/third party are actually present on billed jobs and returns a zip.

Responses​

Single BRC/Invoice/BBOM/Work Order:

  • Content-Type: application/pdf
  • Content-Disposition: attachment; filename="...pdf"

Single ARR-500B:

  • Content-Type: text/plain; charset=utf-8
  • Content-Disposition: attachment; filename="BIRCH <railcar>.txt"

Multiple files (bill_to: all):

  • Content-Type: application/zip
  • Content-Disposition: attachment; filename="workorder-<work_order>-documents.zip"

Example curl​

curl -fsS \
  -X POST 'https://birchbackend.ihrailsoftware.com/agent/workorder-documents' \
  -H 'Authorization: Bearer <BIRCH_AGENT_DOCUMENT_API_KEY>' \
  -H 'Content-Type: application/json' \
  --data '{"work_order":"WO_05926","document_type":"arr-500b","bill_to":"owner"}' \
  -o 'BIRCH-WO_05926.txt'
curl -fsS \
  -X POST 'https://birchbackend.ihrailsoftware.com/agent/workorder-documents' \
  -H 'Authorization: Bearer <BIRCH_AGENT_DOCUMENT_API_KEY>' \
  -H 'Content-Type: application/json' \
  --data '{"work_order":"WO_05926","document_type":"brc","bill_to":"all"}' \
  -o 'WO_05926-brc.zip'

Error cases​

  • 400 unsupported document type, unsupported bill-to value, missing work order, or invoice PO requirement not satisfied.
  • 401 missing/wrong bearer token.
  • 404 work order not found.
  • 503 agent document API key not configured.
  • 500 PDFCrowd or unexpected generation failure.