Skip to content

Guides

Working with opportunities

Create, advance, and query opportunities across cycle stages.

  • Guides
  • 1 min read

Scope

This guide covers day-to-day opportunity operations: create, advance stage, attach channel context, and list filtered sets. Prerequisites: Installation and Core concepts.

Create

const opportunity = await client.opportunities.create({
  name: 'Working-capital facility — ACME Corp',
  stage: 'qualify',
  channel: 'relationship',
  borrowerSegment: 'mid-market',
  ownerId: 'user_123',
})

Required fields depend on tenant policy. Validation errors list missing or invalid fields by name.

Advance stage

const updated = await client.opportunities.advance(opportunity.id, {
  toStage: 'structure',
  reason: 'Credit memo draft ready for structuring review',
})

Invalid transitions (skipping a required stage, or advancing without required fields) return 409 with the allowed next stages. Stage history is append-only.

List and filter

const page = await client.opportunities.list({
  stage: ['qualify', 'structure'],
  channel: 'relationship',
  limit: 50,
})

Prefer server-side filters over downloading the full set. Pagination cursors are opaque; do not invent offset arithmetic.

Explainability on stage changes

When a stage change produces decision-facing output, request explanations explicitly:

const detail = await client.opportunities.get(opportunity.id, {
  include: ['explanations'],
})

Related