Opportunities

An opportunity is pipeline work that has not been won yet. Drum stores opportunities as projects with project_type: "opportunity", so they share most fields with projects. Converting an opportunity creates a delivery project.

Money is tax exclusive. deal_won_date and deal_lost_date are full timestamps. Other dates are yyyy-mm-dd.

GET /api/v1/opportunities

Lists the opportunities the token’s user can read. Deleted opportunities are left out. Paginated (see Pagination).

Each row is compact:

[
  {
    "id": 12001,
    "name": "Riverside fit-out",
    "project_number": "OPP-2026-014",
    "description": "Ground floor refurbishment",
    "currency": "AUD",
    "project_type": "opportunity",
    "estimated_start_date": "2026-10-01",
    "estimated_end_date": "2026-12-15",
    "enquiry_date": "2026-08-20",
    "target_date": null,
    "project_status": {"id": 301, "name": "Proposal Sent", "complete_status": false},
    "client": {"id": 789, "name": "Acme Corporation", "type": "Company"},
    "team": {"id": 42, "name": "Fit-out"},
    "amount": 48500.0,
    "lead_score": {"id": 51, "name": "Warm"},
    "planned": false
  }
]

amount (the deal value) appears only with view_opportunity_financial_values. due_date appears only when the account uses opportunity due dates.

GET /api/v1/opportunities/:id

Returns one opportunity with its deliverables and tasks, contacts, addresses and custom fields, in the project shape. These fields are specific to opportunities:

A delivery project id, a deleted opportunity, an id from another account, or an opportunity hidden from the token’s user returns 404 with an empty body.

POST /api/v1/opportunities

Creates an opportunity as the New Opportunity form does. Send fields flat or under opportunity.

name and client_company_id are required. You can also send the PATCH fields below (except add_opportunity_tags, remove_opportunity_tags, expected_project_status_id, project_role_id and member_ids), plus:

Fields you leave out take the form’s defaults:

The templates add their deliverables, and the opportunity gets its number and custom fields, as in Drum.

Send an Idempotency-Key header to make retries safe (see Idempotency keys).

Returns 201 with the opportunity in the show shape. A token user who can read only assigned opportunities, and is not a member of the new one, gets {"id", "project_number", "visible": false}.

PATCH /api/v1/opportunities/:id

Changes the fields you send. Send fields flat or under opportunity. A field of the wrong type is refused with 422 invalid_input and field.

Moving to a won status sets deal_won_date, and a lost status sets deal_lost_date. A won status does not create a project. Use convert for that.

On a variation opportunity, PATCH cannot set a won status: convert it instead. A lost status declines the variation’s proposal and rejects the variation in the same request, and needs update_quotes as well (update_budgets when the variation has no proposal). A committed variation cannot be lost this way: 422 validation_failed. Once a variation opportunity is won or lost, its status changes only through its proposal.

PATCH /api/v1/opportunities/12001
{
  "opportunity": {
    "project_status_id": 302,
    "expected_project_status_id": 301,
    "add_opportunity_tags": ["fit-out"]
  }
}

Returns 200 with the opportunity in the show shape.

opportunity_tag_list is no longer accepted and returns 422 invalid_input. Use add_opportunity_tags and remove_opportunity_tags.

Errors for create and update

Convert an opportunity

POST /api/v1/opportunities/:id/convert creates a delivery project from the opportunity and marks the opportunity won, in one transaction. Send fields flat or under conversion. All fields are optional.

A variation opportunity converts differently and takes other fields. See Variation opportunities.

To convert, the token’s user needs the opportunity update rights and create_projects. A user with read_quotes and accept_quotes can instead convert through an accepted proposal of the opportunity (the one named by proposal_id, or by default the last accepted one), without the other two.

What a convert does:

• Creates the project with a new project number. With an accepted proposal, the project’s structure and budget come from it, and the proposal is linked to the project.
• Marks the client company as a client.
• Moves the opportunity to its won status and sets deal_won_date, unless it is already won.
• Adds the opportunity’s members to the project with the first of the account’s project roles. Adds the token’s user too, but only when they could not otherwise read the project.

POST /api/v1/opportunities/12001/convert
{"project_status_id": 410, "expected_project_status_id": 301}

Returns 201 with a new project, or 200 when a project already exists:

{
  "created": true,
  "project": {"id": 20488, "name": "Riverside fit-out", "project_number": "2026-088", "project_type": "project", "opportunity_id": 12001},
  "opportunity": {
    "id": 12001,
    "project_number": "OPP-2026-014",
    "project_status": {"id": 305, "name": "Won", "sales_status_type": "won"},
    "deal_won_date": "2026-09-10T00:00:00.000Z",
    "variation_opportunity": false
  }
}

project holds the full project shape plus opportunity_id (shortened above). It holds only id and project_number when the token’s user cannot read the project.

Retries. When the opportunity already has a delivery project, convert changes nothing and returns 200 with created: false and that project. Treat 201 and 200 as success. This makes a retry safe without an idempotency key.

Budget. budget_cents is stored as the project’s budget and as the opportunity’s deal value. New projects use the account’s default currency. If the opportunity’s currency is different, budget_cents is refused with 422 currency_mismatch. The project’s total_budget is built from its tasks, so it stays 0.0 until tasks are added.

Events. A convert sends three webhook events: project.created for the new project, and project.updated and opportunity.won for the opportunity. A replay sends none.

Convert errors

Error bodies are {"error", "code"}, with field on input errors. Every error leaves the account unchanged.

Variation opportunities

A variation opportunity (variation_opportunity: true) sells a variation on a project that already exists. Converting it creates no project. Instead it accepts the variation’s proposal, which approves the variation, commits it to its project and marks the opportunity won.

GET /opportunities/:id shows what a convert would do in variation:

"variation": {
  "id": 611,
  "name": "Extra loading dock",
  "status": "submitted",
  "project": {"id": 20488, "project_number": "2026-088", "name": "Riverside fit-out"},
  "proposal": {"id": 9120, "number": "Q-0412", "status": "sent"},
  "total_cents": 1850000,
  "currency": "AUD",
  "convertible": true,
  "blocked_code": null,
  "blocked_reason": null
}

Fields for a variation convert:

The fields that build a new project (project_status_id, name, description, team_id, start_date, end_date, location_id, budget_cents, allow_additional_project, structure_type) are refused with 422 invalid_input.

It needs read_quotes and accept_quotes. A user with the opportunity update rights but no proposal to accept gets the variation_proposal_missing error.

The response is 200 with created: false. project is the project the variation changed, opportunity has variation_opportunity: true, and variation shows the variation after the convert. Converting again once it is done returns the same response and changes nothing.

Errors specific to a variation convert, all 422 unless shown:

Deliverables and tasks

These endpoints edit one deliverable or task of an opportunity at a time:

POST   /api/v1/opportunities/:opportunity_id/deliverables
PATCH  /api/v1/opportunities/:opportunity_id/deliverables/:id
DELETE /api/v1/opportunities/:opportunity_id/deliverables/:id
POST   /api/v1/opportunities/:opportunity_id/tasks
PATCH  /api/v1/opportunities/:opportunity_id/tasks/:id
DELETE /api/v1/opportunities/:opportunity_id/tasks/:id

Send the row’s fields at the top level. A field you leave out does not change, and null clears an optional field.

position is a 1-based place among the row’s siblings, or {"after": id} or {"before": id}.

An opportunity is priced in its proposal budget, not on its tasks, so budget fields (budget_type, quantity, quantity_unit, rate_cents, contract_value_cents, resource_type_id) are refused with 422 invalid_input.

A write returns {"rows": [row]}. Each row has record_kind (deliverable or task), and money (budget, rate, contract_value) only for a user who can read budgets. A DELETE returns {"record_kind", "id", "deleted": true}.

Changing a row needs the opportunity update rights or update_budgets. A deliverable’s rate_card_id also needs update_budgets. Deleting needs the opportunity update rights or delete_budgets. Error codes include opportunity_not_found, deliverable_not_found, task_not_found, project_phase_not_found, rate_card_not_found, member_not_found, project_template_deliverable_not_found and deliverable_has_tracked_time.

Permissions