> ## Documentation Index
> Fetch the complete documentation index at: https://docs.automate.ax/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Automate.ax automations are TypeScript programs.
> Use Bun for installation and command examples.
> Use Automate.ax for the product name and automate.ax for the package, CLI, and domain.
> Treat documented public APIs as current; do not invent transitional or deprecated names.

# Upsert opportunity

> Creates or updates an opportunity using HighLevel's matching rules.

`highlevel.upsertOpportunity` creates or updates an opportunity using HighLevel's matching rules.

```ts automations/highlevel-upsert-opportunity.automation.ts theme={null}
import { automation, markSignificant } from "automate.ax"
import { highlevel } from "automate.ax/highlevel"

export default automation("Upsert opportunity", () => {
  markSignificant(
    highlevel.upsertOpportunity({
      pipelineId: "bCkKGpDsyPP4peuKowkG",
      followers: ["LiKJ2vnRg5ETM8Z19K7"],
      isRemoveAllFollowers: true,
      followersActionType: "add",
    }),
  )
})
```

## Input

| Field                  | Type                                      | Required | Description                            |
| ---------------------- | ----------------------------------------- | -------- | -------------------------------------- |
| `id`                   | `string`                                  | No       | Existing opportunity ID.               |
| `pipelineId`           | `string`                                  | Yes      | pipeline Id                            |
| `followers`            | `string[]`                                | Yes      | Contact IDs to follow the opportunity. |
| `isRemoveAllFollowers` | `boolean`                                 | Yes      | isRemoveAllFollowers                   |
| `followersActionType`  | `add \| remove`                           | Yes      | followers action type                  |
| `name`                 | `string`                                  | No       | name                                   |
| `status`               | `open \| won \| lost \| abandoned \| all` | No       | HighLevel status value.                |
| `pipelineStageId`      | `string`                                  | No       | HighLevel pipeline stage id value.     |
| `monetaryValue`        | `number`                                  | No       | Opportunity monetary value.            |
| `assignedTo`           | `string`                                  | No       | HighLevel assigned to value.           |
| `lostReasonId`         | `string`                                  | No       | lost reason Id                         |

Automate.ax supplies the connected sub-account's location ID. Optional second argument `{ account }` selects a named HighLevel binding.

## Output

| Field         | Type      | Required | Description               |
| ------------- | --------- | -------- | ------------------------- |
| `opportunity` | `object`  | Yes      | Updated / New Opportunity |
| `new`         | `boolean` | Yes      | HighLevel new value.      |

This action calls `POST /opportunities/upsert` with HighLevel API version `2021-07-28` and requires `opportunities.write`. HighLevel validation and permission errors fail the action. Rate limits honor the provider's retry timing. Automate.ax does not automatically replay this create or send operation after an indeterminate transport failure.