create_opportunity
Create a sales opportunity linked to a party, placed in a specific pipeline stage via milestone. Supports custom fields, owner assignment, and optional value with currency.
Instructions
Create a new opportunity linked to a party. Requires partyId and milestoneId (which pins the deal to a specific pipeline stage — pipeline is inferred from the milestone). Value is optional but if amount is set, currency must be set too (3-letter ISO 4217 code, e.g. 'USD'). Discover valid milestone ids via list_pipelines + list_milestones first. For multi-party deals, use add_additional_party after creation.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| partyId | No | ID of the party this opportunity belongs to | |
| milestoneId | No | ID of the pipeline milestone to place this opportunity at. The milestone implicitly determines the pipeline — there is no separate pipelineId parameter. Discover via list_pipelines / list_milestones. NOTE: some Capsule tenants configure **pipeline / milestone-reached automation rules** that mutate `owner` and/or `team` immediately after creation — e.g. an 'Assign to a Team' action that fires on entry to a specific milestone and has been observed to clear `owner` as an automation side-effect. If you observe a newly-created opp landing with `owner: null` despite passing `ownerId`, the cause is almost certainly a milestone automation on the destination pipeline rather than the connector. Documented workaround: follow `create_opportunity` with an immediate `batch_update_opportunity({items: [{id, ownerId, teamId}]})` carrying both fields — PUT does not re-fire milestone-reached triggers, so the owner sticks. | |
| description | No | ||
| value | No | ||
| expectedCloseOn | No | YYYY-MM-DD | |
| probability | No | ||
| ownerId | No | Assign to user ID. Defaults to the API-token owner when omitted — note that opportunities do NOT inherit owner from the linked party, even though one might expect it. To clear owner later, call update_opportunity with `ownerId: null`. Discover IDs via list_users. WARNING: tenant pipeline / milestone-reached automation can mutate this field post-create — see the `milestoneId` description for details and the chained-PUT workaround. | |
| teamId | No | Assign to team ID (discover via list_teams). Independent from `ownerId` — setting one does NOT clear the other on create. Three ownership shapes are valid: owner alone, team alone, or owner+team (the owner must be a member of the team; users can belong to multiple teams — 422 'owner is not a member of the team' otherwise). | |
| fields | No | Set custom field values on this record. PARTIAL UPDATE: only the definitions you list are touched; any field NOT in this array is left unchanged. Discover available definitions via list_custom_fields; read current values via get_opportunity with embed='fields'. Capsule's POST /opportunities accepts the same `fields[]` shape as PUT (inferred by symmetry with the v1.6.5 wire-trace findings on POST /parties and POST /kases — the tenant probed had no opportunity custom fields configured, so this is unverified empirically). Setting custom fields on creation removes the create-then-update ritual. |