Skip to content
Documentation
English
Explore guides

For administrators

Opportunities

List, create, show, update, and delete opportunities, change stage, and close or reopen them.

Contents

Before you start

Send Accept: application/json and Authorization: Bearer YOUR_TOKEN to https://{subdomain}.talentohq.com. See API for authentication.

Path and query identifiers are UUID strings.

Successful responses use 200. Validation failures use 422. Missing or invalid tokens, and records that cannot be found, use 401.

List all opportunities

GET /api/v3/opportunities

Parameter Type Description
period string Optional period. Defaults to all.
status string Optional status.
rotting boolean Optional rotting filter.
overdue boolean Optional overdue filter.
inactive boolean Optional inactive filter.
opportunity_stage_id string (UUID) Optional stage id.
customer_id string (UUID) Optional customer id.
closing_factor_id string (UUID) Optional closing factor id.
employee_id string (UUID) Optional owner id.

Results are paginated. Pass page to move through pages of 50 records.

Response 200 

[
  {
    "id": "8d429d99-fbd4-4196-a9ac-94f1dc481344",
    "name": "Acme rollout",
    "description": "First year",
    "status": "open",
    "customer_id": "55129d78-0281-4e72-aca1-8d547a2df814",
    "customer_name": "Acme",
    "employee_id": "3ed57043-3894-43e9-a03b-69883506a3d6",
    "employee_name": "Employee name",
    "opportunity_stage_id": "2c2d2fd9-fe83-480a-adb8-351efc6a9808",
    "opportunity_stage_name": "Proposal",
    "expected_amount": 12000,
    "amount_period": "one_off",
    "probability": 40,
    "effective_probability": 40,
    "expected_close_date": "2026-06-30",
    "actual_amount": null,
    "actual_amount_period": null,
    "closed_at": null,
    "closing_factor_id": null,
    "closing_factor_name": null,
    "next_action_on": "2026-04-10",
    "next_action_type": "call",
    "next_action_note": "Send proposal",
    "last_activity_at": "2026-04-01T12:00:00.000Z",
    "rotting": false
  }
]

Create an opportunity

POST /api/v3/opportunities

Request

{
  "name": "Acme rollout",
  "description": "First year",
  "expected_amount": 12000,
  "amount_period": "one_off",
  "expected_close_date": "2026-06-30",
  "probability": 40,
  "customer_id": "55129d78-0281-4e72-aca1-8d547a2df814",
  "employee_id": "3ed57043-3894-43e9-a03b-69883506a3d6",
  "opportunity_stage_id": "2c2d2fd9-fe83-480a-adb8-351efc6a9808"
}

Response 200 

{
  "id": "8d429d99-fbd4-4196-a9ac-94f1dc481344",
  "name": "Acme rollout",
  "description": "First year",
  "status": "open",
  "customer_id": "55129d78-0281-4e72-aca1-8d547a2df814",
  "customer_name": "Acme",
  "employee_id": "3ed57043-3894-43e9-a03b-69883506a3d6",
  "employee_name": "Employee name",
  "opportunity_stage_id": "2c2d2fd9-fe83-480a-adb8-351efc6a9808",
  "opportunity_stage_name": "Proposal",
  "expected_amount": 12000,
  "amount_period": "one_off",
  "probability": 40,
  "effective_probability": 40,
  "expected_close_date": "2026-06-30",
  "actual_amount": null,
  "actual_amount_period": null,
  "closed_at": null,
  "closing_factor_id": null,
  "closing_factor_name": null,
  "next_action_on": "2026-04-10",
  "next_action_type": "call",
  "next_action_note": "Send proposal",
  "last_activity_at": "2026-04-01T12:00:00.000Z",
  "rotting": false
}

Show an opportunity

GET /api/v3/opportunities/{opportunity_id}

Parameter Type Description
opportunity_id string (UUID) Opportunity id.

Response 200 

{
  "id": "8d429d99-fbd4-4196-a9ac-94f1dc481344",
  "name": "Acme rollout",
  "description": "First year",
  "status": "open",
  "customer_id": "55129d78-0281-4e72-aca1-8d547a2df814",
  "customer_name": "Acme",
  "employee_id": "3ed57043-3894-43e9-a03b-69883506a3d6",
  "employee_name": "Employee name",
  "opportunity_stage_id": "2c2d2fd9-fe83-480a-adb8-351efc6a9808",
  "opportunity_stage_name": "Proposal",
  "expected_amount": 12000,
  "amount_period": "one_off",
  "probability": 40,
  "effective_probability": 40,
  "expected_close_date": "2026-06-30",
  "actual_amount": null,
  "actual_amount_period": null,
  "closed_at": null,
  "closing_factor_id": null,
  "closing_factor_name": null,
  "next_action_on": "2026-04-10",
  "next_action_type": "call",
  "next_action_note": "Send proposal",
  "last_activity_at": "2026-04-01T12:00:00.000Z",
  "rotting": false
}

Update an opportunity

PUT /api/v3/opportunities/{opportunity_id}

Request

{
  "name": "Acme rollout",
  "expected_amount": 15000,
  "customer_id": "55129d78-0281-4e72-aca1-8d547a2df814",
  "employee_id": "3ed57043-3894-43e9-a03b-69883506a3d6",
  "opportunity_stage_id": "2c2d2fd9-fe83-480a-adb8-351efc6a9808"
}

Response 200 

{
  "id": "8d429d99-fbd4-4196-a9ac-94f1dc481344",
  "name": "Acme rollout",
  "description": "First year",
  "status": "open",
  "customer_id": "55129d78-0281-4e72-aca1-8d547a2df814",
  "customer_name": "Acme",
  "employee_id": "3ed57043-3894-43e9-a03b-69883506a3d6",
  "employee_name": "Employee name",
  "opportunity_stage_id": "2c2d2fd9-fe83-480a-adb8-351efc6a9808",
  "opportunity_stage_name": "Proposal",
  "expected_amount": 15000,
  "amount_period": "one_off",
  "probability": 40,
  "effective_probability": 40,
  "expected_close_date": "2026-06-30",
  "actual_amount": null,
  "actual_amount_period": null,
  "closed_at": null,
  "closing_factor_id": null,
  "closing_factor_name": null,
  "next_action_on": "2026-04-10",
  "next_action_type": "call",
  "next_action_note": "Send proposal",
  "last_activity_at": "2026-04-01T12:00:00.000Z",
  "rotting": false
}

Delete an opportunity

DELETE /api/v3/opportunities/{opportunity_id}

Response 200 

{}

Change opportunity stage

POST /api/v3/opportunities/{opportunity_id}/stage

Parameter Type Description
opportunity_id string (UUID) Opportunity id.

Request

{
  "opportunity_stage_id": "795c7a6e-cfb7-4883-bef8-2fb380de92c8",
  "note": "Proposal sent"
}

Response 200 

{
  "id": "8d429d99-fbd4-4196-a9ac-94f1dc481344",
  "name": "Acme rollout",
  "description": "First year",
  "status": "open",
  "customer_id": "55129d78-0281-4e72-aca1-8d547a2df814",
  "customer_name": "Acme",
  "employee_id": "3ed57043-3894-43e9-a03b-69883506a3d6",
  "employee_name": "Employee name",
  "opportunity_stage_id": "795c7a6e-cfb7-4883-bef8-2fb380de92c8",
  "opportunity_stage_name": "Negotiation",
  "expected_amount": 12000,
  "amount_period": "one_off",
  "probability": 40,
  "effective_probability": 40,
  "expected_close_date": "2026-06-30",
  "actual_amount": null,
  "actual_amount_period": null,
  "closed_at": null,
  "closing_factor_id": null,
  "closing_factor_name": null,
  "next_action_on": "2026-04-10",
  "next_action_type": "call",
  "next_action_note": "Send proposal",
  "last_activity_at": "2026-04-01T12:00:00.000Z",
  "rotting": false
}

Close and reopen

Close

POST /api/v3/opportunities/{opportunity_id}/close

Request

{
  "closing_factor_id": "0f27fb66-20f6-4e9b-9d7f-664066c28f58",
  "outcome": "won",
  "closing_factor_text": "Signed annually",
  "closed_at": "2026-05-01",
  "actual_amount": 12000,
  "actual_amount_period": "one_off"
}

Response 200 

{
  "id": "8d429d99-fbd4-4196-a9ac-94f1dc481344",
  "name": "Acme rollout",
  "description": "First year",
  "status": "won",
  "customer_id": "55129d78-0281-4e72-aca1-8d547a2df814",
  "customer_name": "Acme",
  "employee_id": "3ed57043-3894-43e9-a03b-69883506a3d6",
  "employee_name": "Employee name",
  "opportunity_stage_id": "2c2d2fd9-fe83-480a-adb8-351efc6a9808",
  "opportunity_stage_name": "Proposal",
  "expected_amount": 12000,
  "amount_period": "one_off",
  "probability": 40,
  "effective_probability": 40,
  "expected_close_date": "2026-06-30",
  "actual_amount": 12000,
  "actual_amount_period": "one_off",
  "closed_at": "2026-05-01T00:00:00.000Z",
  "closing_factor_id": "0f27fb66-20f6-4e9b-9d7f-664066c28f58",
  "closing_factor_name": "Price",
  "next_action_on": "2026-04-10",
  "next_action_type": "call",
  "next_action_note": "Send proposal",
  "last_activity_at": "2026-04-01T12:00:00.000Z",
  "rotting": false
}

Reopen

POST /api/v3/opportunities/{opportunity_id}/reopen

Request

{
  "note": "Customer came back"
}

Response 200 

{
  "id": "8d429d99-fbd4-4196-a9ac-94f1dc481344",
  "name": "Acme rollout",
  "description": "First year",
  "status": "open",
  "customer_id": "55129d78-0281-4e72-aca1-8d547a2df814",
  "customer_name": "Acme",
  "employee_id": "3ed57043-3894-43e9-a03b-69883506a3d6",
  "employee_name": "Employee name",
  "opportunity_stage_id": "2c2d2fd9-fe83-480a-adb8-351efc6a9808",
  "opportunity_stage_name": "Proposal",
  "expected_amount": 12000,
  "amount_period": "one_off",
  "probability": 40,
  "effective_probability": 40,
  "expected_close_date": "2026-06-30",
  "actual_amount": null,
  "actual_amount_period": null,
  "closed_at": null,
  "closing_factor_id": null,
  "closing_factor_name": null,
  "next_action_on": "2026-04-10",
  "next_action_type": "call",
  "next_action_note": "Send proposal",
  "last_activity_at": "2026-04-01T12:00:00.000Z",
  "rotting": false
}