Costs API

Authentication

All API requests require authentication using a Bearer token. See the API Authentication documentation for details.

All endpoints are scoped to a specific account and project.

The Cost Object

A cost object represents an expense or cost incurred on a project.

Attributes

Attribute	Type	Description
id	integer	Unique identifier for the cost.
name	string	Cost name/description.
description	string \| null	Detailed description of the cost.
reference	string \| null	Reference number or code.
invoice_number	string \| null	Supplier invoice number.
purchase_order_number	string \| null	Purchase order number.
status	string	Cost status: `draft`, `submitted`, `approved`, or `rejected`.
billable	boolean	Whether this cost can be billed to the client.
billing_status	string	Billing status: `unbilled`, `partial`, or `billed`.
issued_date	string	Date the cost was issued (ISO 8601 format: YYYY-MM-DD).
due_date	string \| null	Payment due date (ISO 8601 format: YYYY-MM-DD).
paid_date	string \| null	Date the cost was paid (ISO 8601 format: YYYY-MM-DD).
tax_rule	string	Tax treatment: `inclusive` or `exclusive`.
project_id	integer	ID of the associated project.
task_id	integer \| null	ID of the associated task.
task_name	string \| null	Name of the task.
project_procedure_id	integer \| null	ID of the project procedure/phase.
cost_type_id	integer \| null	ID of the cost type category.
cost_type_name	string \| null	Name of the cost type (e.g., "Materials", "Subcontractors").
company_id	integer \| null	ID of the supplier company.
supplier_name	string \| null	Name of the supplier.
available_resource_id	integer \| null	ID of the resource who incurred this cost.
approved_by_id	integer \| null	ID of the user who approved this cost.
approved_by_name	string \| null	Name of the approver.
approved_at	string \| null	Timestamp when the cost was approved (ISO 8601 format).
created_by_id	integer	ID of the user who created this cost.
created_by_name	string	Name of the creator.
third_party_purchase_order_status	string \| null	Sync status with accounting system for purchase order: `synced`, `pending`, `failed`, or null.
third_party_bill_status	string \| null	Sync status with accounting system for bill: `synced`, `pending`, `failed`, or null.
created_at	string	Timestamp when the cost was created (ISO 8601 format).
updated_at	string	Timestamp when the cost was last updated (ISO 8601 format).

Financial Attributes (requires `view_project_metrics` permission)

Attribute	Type	Description
currency	string	Three-letter ISO currency code (e.g., "AUD", "USD").
total_cents	integer	Total cost amount in cents (including tax if tax_rule is inclusive).
total_excluding_tax_cents	integer	Total cost amount excluding tax in cents.
billed_amount_cents	integer	Amount that has been billed to the client in cents.
remaining_billable_cents	integer	Amount remaining to be billed in cents.
amount_paid_cents	integer	Amount that has been paid to the supplier in cents.

Supplier/Markup Attributes (requires `update_costs` or `approve_costs` permission)

These fields contain sensitive supplier pricing and markup information.

Attribute	Type	Description
fixed_markup_cents	integer \| null	Fixed markup amount in cents. Only included if > 0.
percentage_markup	decimal \| null	Percentage markup applied. Only included if > 0.
total_with_markup_cents	integer	Total cost with markup applied in cents (excluding tax).
total_with_markup_including_tax_cents	integer	Total cost with markup applied in cents (including tax).

Line Items

Line items are only included when include_line_items=true is passed as a query parameter.

Attribute	Type	Description
line_items	array	Array of line item objects (see Line Item Object below).

Example Object

{
  "id": 567,
  "name": "Electrical Installation - Phase 2",
  "description": "Supply and install electrical systems for floor 2",
  "reference": "ELEC-2025-042",
  "invoice_number": "INV-98765",
  "purchase_order_number": "PO-12345",
  "status": "approved",
  "billable": true,
  "billing_status": "unbilled",
  "issued_date": "2025-10-15",
  "due_date": "2025-11-15",
  "paid_date": null,
  "tax_rule": "inclusive",
  "project_id": 42,
  "task_id": 789,
  "task_name": "Electrical Works",
  "project_procedure_id": 101,
  "cost_type_id": 3,
  "cost_type_name": "Subcontractors",
  "company_id": 456,
  "supplier_name": "ABC Electrical Ltd",
  "available_resource_id": null,
  "approved_by_id": 50,
  "approved_by_name": "Jane Smith",
  "approved_at": "2025-10-16T09:30:00Z",
  "created_by_id": 42,
  "created_by_name": "John Doe",
  "third_party_purchase_order_status": "synced",
  "third_party_bill_status": "synced",
  "created_at": "2025-10-15T14:20:00Z",
  "updated_at": "2025-10-16T09:30:00Z",
  "currency": "AUD",
  "total_cents": 2500000,
  "total_excluding_tax_cents": 2272727,
  "billed_amount_cents": 0,
  "remaining_billable_cents": 2500000,
  "amount_paid_cents": 0,
  "percentage_markup": 15.0,
  "total_with_markup_cents": 2613636,
  "total_with_markup_including_tax_cents": 2875000
}

The Line Item Object

Line items represent individual items or charges within a cost.

Attributes

Attribute	Type	Description
id	integer	Unique identifier for the line item.
name	string	Line item name/description.
quantity	decimal	Quantity of this item.
position	integer	Sort position within the cost.
line_type	string	Type of line: `standard` or `comment`.
tax_rate_id	integer \| null	ID of the applied tax rate.
tax_rate_name	string \| null	Name of the tax rate.
finance_account_id	integer \| null	ID of the accounting/finance account.
finance_account_name	string \| null	Name of the finance account.
line_item_code_id	integer \| null	ID of the line item code/SKU.
line_item_code_name	string \| null	Name of the line item code.

Financial Attributes (requires `view_project_metrics` permission)

Attribute	Type	Description
price_cents	integer	Unit price in cents.
discount_cents	integer	Discount amount in cents.
total_cents	integer	Total line item amount in cents (including tax).
total_excluding_tax_cents	integer	Total line item amount excluding tax in cents.

Example Line Item

{
  "id": 1234,
  "name": "Electrical cable - 100m",
  "quantity": 5.0,
  "position": 1,
  "line_type": "standard",
  "price_cents": 50000,
  "discount_cents": 0,
  "total_cents": 275000,
  "total_excluding_tax_cents": 250000,
  "tax_rate_id": 1,
  "tax_rate_name": "GST 10%",
  "finance_account_id": 42,
  "finance_account_name": "Materials",
  "line_item_code_id": 567,
  "line_item_code_name": "ELEC-CABLE-100"
}

List Project Costs

Retrieve all costs for a specific project. Excludes costs from unapproved contract variations.

Endpoint

GET /api/v1/projects/:project_id/costs

Authentication

Required.

Permissions

Requires api_read permission
Requires read_costs permission
Requires permission to view the project
Financial data requires view_project_metrics permission
Supplier/markup details require update_costs or approve_costs permission

Path Parameters

Parameter	Type	Required	Description
account_id	integer	Yes	The account ID.
project_id	integer	Yes	The project ID.

Query Parameters (Filters)

Parameter	Type	Description
start_date	string	Filter to costs issued on or after this date (YYYY-MM-DD).
end_date	string	Filter to costs issued on or before this date (YYYY-MM-DD).
status	string	Filter by status: `draft`, `submitted`, `approved`, or `rejected`.
task_id	integer	Filter to costs for a specific task.
project_procedure_id	integer	Filter to costs for a specific project procedure.
billing_status	string	Filter by billing status: `unbilled`, `partial`, or `billed`.
billable	boolean	Filter by billable flag: `true` or `false`.
cost_type_id	integer	Filter by cost type category.
include_line_items	boolean	Include line item details in response: `true` or `false`. Default: false.
page	integer	Page number for pagination (default: 1).
items	integer	Items per page (default: 20).

Example Request

curl "https://app.getdrum.com/api/v1/projects/42/costs" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Example Request with Filters

curl "https://app.getdrum.com/api/v1/projects/42/costs?status=approved&billable=true&start_date=2025-10-01&include_line_items=true" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response

Returns a paginated array of cost objects, ordered by issued_date (descending), then created_at (descending).

{
  "data": [
    {
      "id": 567,
      "name": "Electrical Installation - Phase 2",
      "description": "Supply and install electrical systems for floor 2",
      "reference": "ELEC-2025-042",
      "invoice_number": "INV-98765",
      "purchase_order_number": "PO-12345",
      "status": "approved",
      "billable": true,
      "billing_status": "unbilled",
      "issued_date": "2025-10-15",
      "due_date": "2025-11-15",
      "paid_date": null,
      "tax_rule": "inclusive",
      "project_id": 42,
      "task_id": 789,
      "task_name": "Electrical Works",
      "cost_type_id": 3,
      "cost_type_name": "Subcontractors",
      "supplier_name": "ABC Electrical Ltd",
      "approved_by_name": "Jane Smith",
      "approved_at": "2025-10-16T09:30:00Z",
      "created_by_name": "John Doe",
      "created_at": "2025-10-15T14:20:00Z",
      "updated_at": "2025-10-16T09:30:00Z",
      "currency": "AUD",
      "total_cents": 2500000,
      "total_excluding_tax_cents": 2272727,
      "billed_amount_cents": 0,
      "remaining_billable_cents": 2500000,
      "amount_paid_cents": 0
    }
  ],
  "pagination": {
    "page": 1,
    "items": 20,
    "count": 1,
    "pages": 1,
    "from": 1,
    "to": 1,
    "prev": null,
    "next": null
  }
}

Retrieve a Cost

Get details for a specific cost within a project.

Endpoint

GET /api/v1/projects/:project_id/costs/:id

Authentication

Required.

Permissions

Same as list costs endpoint.

Path Parameters

Parameter	Type	Required	Description
account_id	integer	Yes	The account ID.
project_id	integer	Yes	The project ID.
id	integer	Yes	The cost ID.

Query Parameters

Parameter	Type	Description
include_line_items	boolean	Include line item details in response: `true` or `false`. Default: false.

Example Request

curl "https://app.getdrum.com/api/v1/projects/42/costs/567" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Example Request with Line Items

curl "https://app.getdrum.com/api/v1/projects/42/costs/567?include_line_items=true" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response

Returns a single cost object.

{
  "id": 567,
  "name": "Electrical Installation - Phase 2",
  "description": "Supply and install electrical systems for floor 2",
  "reference": "ELEC-2025-042",
  "invoice_number": "INV-98765",
  "purchase_order_number": "PO-12345",
  "status": "approved",
  "billable": true,
  "billing_status": "unbilled",
  "issued_date": "2025-10-15",
  "due_date": "2025-11-15",
  "paid_date": null,
  "tax_rule": "inclusive",
  "project_id": 42,
  "task_id": 789,
  "task_name": "Electrical Works",
  "cost_type_name": "Subcontractors",
  "supplier_name": "ABC Electrical Ltd",
  "approved_by_name": "Jane Smith",
  "approved_at": "2025-10-16T09:30:00Z",
  "created_by_name": "John Doe",
  "created_at": "2025-10-15T14:20:00Z",
  "updated_at": "2025-10-16T09:30:00Z",
  "currency": "AUD",
  "total_cents": 2500000,
  "total_excluding_tax_cents": 2272727,
  "billed_amount_cents": 0,
  "remaining_billable_cents": 2500000,
  "amount_paid_cents": 0,
  "line_items": [
    {
      "id": 1234,
      "name": "Electrical cable - 100m",
      "quantity": 5.0,
      "position": 1,
      "line_type": "standard",
      "price_cents": 50000,
      "total_cents": 275000,
      "total_excluding_tax_cents": 250000,
      "tax_rate_name": "GST 10%"
    }
  ]
}

Cost Status Values

Status	Description
draft	Cost is being prepared and not yet submitted for approval.
submitted	Cost has been submitted and is awaiting approval.
approved	Cost has been approved and can be billed/paid.
rejected	Cost was rejected and will not be paid/billed.

Billing Status Values

Status	Description
unbilled	Cost has not been billed to the client yet.
partial	Some of the cost has been billed to the client.
billed	All of the cost has been billed to the client.

Tax Rules

Rule	Description
inclusive	Prices include tax (tax is calculated from the total).
exclusive	Prices exclude tax (tax is added on top).

Third-Party Integration Status

Costs can be synced with external accounting systems (like Xero or QuickBooks):

Status	Description
synced	Successfully synchronized with accounting system.
pending	Synchronization is in progress or queued.
failed	Synchronization failed (check integration logs).
null	Not yet synced or integration not configured.

Both purchase orders and bills are tracked separately:

third_party_purchase_order_status: Sync status for the PO
third_party_bill_status: Sync status for the supplier bill

Financial Data Visibility

Financial data in costs has multiple permission levels:

Public Data (always visible)

Name, description, reference numbers
Status and dates
Task and supplier associations
Billable flag and billing status

Project Metrics (`view_project_metrics` permission)

Total amounts and currency
Billed amounts
Payment status
Line item pricing (if included)

Supplier Details (`update_costs` or `approve_costs` permission)

Markup percentages and amounts
Supplier pricing vs. client billing
⚠️ Sensitive: Contains supplier cost information and profit margins

Line Items

Line items provide detailed breakdowns of costs:

Include by request: Add ?include_line_items=true to any costs endpoint
Performance: Line items increase response size; only request when needed
Line types:
- standard: Regular billable/cost items
- comment: Text-only lines for notes or section headers

Cost Markups

Costs can have markups applied for billing to clients:

Fixed markup: A fixed dollar amount added to the cost
Percentage markup: A percentage of the cost added
Client billing: Markup is added to supplier cost to determine client billing amount
Visibility: Only visible to users with update_costs or approve_costs permission

Example Calculation

Supplier Cost: $10,000 (excluding tax)
Percentage Markup: 15%
Markup Amount: $1,500
Client Bill Amount: $11,500 (excluding tax)

Error Responses

Status Code	Description
200	Success - Request completed successfully.
401	Unauthorized - Invalid or missing authentication token.
403	Forbidden - Insufficient permissions to access project or costs.
404	Not Found - Project or cost not found.

Notes

Monetary Values

All monetary amounts are in cents. To display as currency:

Divide by 100
Format according to the currency field
Example: total_cents: 2500000 = $25,000.00 AUD

Unapproved Variation Costs

Costs from unapproved contract variations are automatically excluded from the API response. This ensures financial reporting only includes approved changes.

Project Access

Users can only access costs for projects they have permission to view. Access is determined by:

Project visibility settings
Team membership
Direct project assignment
Account role permissions

Pagination

Default pagination settings apply (20 items per page). Results are ordered by issued date (most recent first), then by creation time.

Cost Approval Workflow

Draft: Cost is created but not submitted
Submitted: Cost is sent for approval
Approved: Cost is approved and can be processed
Rejected: Cost is rejected and cannot be billed/paid

The approved_by_id, approved_by_name, and approved_at fields track who approved the cost and when.

Projects API

Opportunities API

Tracked Times API

Invoices & Write-Offs API

Authentication

The Cost Object

Attributes

Financial Attributes (requires view_project_metrics permission)

Supplier/Markup Attributes (requires update_costs or approve_costs permission)

Line Items

Example Object

The Line Item Object

Attributes

Financial Attributes (requires view_project_metrics permission)

Example Line Item

List Project Costs

Endpoint

Authentication

Permissions

Path Parameters

Query Parameters (Filters)

Example Request

Example Request with Filters

Response

Retrieve a Cost

Endpoint

Authentication

Permissions

Path Parameters

Query Parameters

Example Request

Example Request with Line Items

Response

Cost Status Values

Billing Status Values

Tax Rules

Third-Party Integration Status

Financial Data Visibility

Public Data (always visible)

Project Metrics (view_project_metrics permission)

Supplier Details (update_costs or approve_costs permission)

Line Items

Cost Markups

Example Calculation

Error Responses

Notes

Monetary Values

Unapproved Variation Costs

Project Access

Pagination

Cost Approval Workflow

Financial Attributes (requires `view_project_metrics` permission)

Supplier/Markup Attributes (requires `update_costs` or `approve_costs` permission)

Financial Attributes (requires `view_project_metrics` permission)

Project Metrics (`view_project_metrics` permission)

Supplier Details (`update_costs` or `approve_costs` permission)