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

# Create an opportunity

> Creates an opportunity and returns it with 201. `account` (a live account's id) and `name` are required; `crm_opportunity_id` links it to your CRM's record, and is unique: one any opportunity holds, a deleted one included, is a 409 naming it. Every other key is an update key, checked the same way, and your validation rules apply, with one difference: without a `crm_opportunity_id`, a create may also set a custom field that comes from your CRM (describe's `owner` is `crm`; not one a CRM field copies into a field of your own) where your admins have made it editable, since no CRM record overwrites it until the opportunity is in your CRM. Where your workspace syncs opportunities with Salesforce and the account is linked to one, the next push creates the opportunity there if you sent no `crm_opportunity_id`; if you sent one, it writes Statisfy's values over that Salesforce record. A 500 that says the opportunity was created names its id: update it by id rather than creating it again. Send an `Idempotency-Key` header to make a retry safe: the same key replays the first response.



## OpenAPI

````yaml /api/statisfy-api.openapi.json post /v1/objects/opportunity/records
openapi: 3.1.0
info:
  description: >-
    The agent-first Statisfy API. Authenticate with an API key (`Authorization:
    Bearer stfy_live_…`), then call `GET /v1/meta/capabilities` to discover
    every operation and its schemas.
  title: Statisfy API
  version: 1.0.0
servers:
  - url: https://api.statisfy.com
    description: Production
security: []
paths:
  /v1/objects/opportunity/records:
    post:
      tags:
        - opportunities
      summary: Create an opportunity
      description: >-
        Creates an opportunity and returns it with 201. `account` (a live
        account's id) and `name` are required; `crm_opportunity_id` links it to
        your CRM's record, and is unique: one any opportunity holds, a deleted
        one included, is a 409 naming it. Every other key is an update key,
        checked the same way, and your validation rules apply, with one
        difference: without a `crm_opportunity_id`, a create may also set a
        custom field that comes from your CRM (describe's `owner` is `crm`; not
        one a CRM field copies into a field of your own) where your admins have
        made it editable, since no CRM record overwrites it until the
        opportunity is in your CRM. Where your workspace syncs opportunities
        with Salesforce and the account is linked to one, the next push creates
        the opportunity there if you sent no `crm_opportunity_id`; if you sent
        one, it writes Statisfy's values over that Salesforce record. A 500 that
        says the opportunity was created names its id: update it by id rather
        than creating it again. Send an `Idempotency-Key` header to make a retry
        safe: the same key replays the first response.
      operationId: opportunities_create
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              description: >-
                An update body plus the keys only a create sets. ``account`` and
                ``name`` are required.
              properties:
                account:
                  default: null
                  description: 'Required: the id of the account the opportunity is on'
                  title: Account
                  type: string
                amount:
                  default: null
                  description: The deal's value
                  title: Amount
                  type: number
                close_date:
                  default: null
                  description: YYYY-MM-DD
                  format: date
                  title: Close Date
                  type: string
                crm_opportunity_id:
                  default: null
                  description: The opportunity's id in your CRM
                  title: Crm Opportunity Id
                  type: string
                description:
                  default: null
                  description: Free text
                  title: Description
                  type: string
                fields:
                  anyOf:
                    - additionalProperties: true
                      type: object
                    - type: 'null'
                  default: null
                  description: Custom field keys to values
                  title: Fields
                name:
                  default: null
                  description: The opportunity's name (required on a create)
                  title: Name
                  type: string
                owner:
                  default: null
                  description: The owner's user id
                  title: Owner
                  type: string
                stage:
                  default: null
                  description: >-
                    One of your stages (key or label) where your stage list is
                    set up
                  title: Stage
                  type: string
                type:
                  default: null
                  description: New Business, Renewal, Expansion, ...
                  title: Type
                  type: string
              type: object
        required: false
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Opportunity'
          description: Successful Response
      security:
        - HTTPBearer: []
components:
  schemas:
    Opportunity:
      properties:
        account:
          anyOf:
            - type: string
            - type: 'null'
          description: The id of the account the opportunity is on
          title: Account
        account_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Account Name
        amount:
          anyOf:
            - type: number
            - type: 'null'
          title: Amount
        close_date:
          anyOf:
            - type: string
            - type: 'null'
          title: Close Date
        created_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Created At
        crm_opportunity_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Crm Opportunity Id
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        fields:
          additionalProperties: true
          title: Fields
          type: object
        id:
          title: Id
          type: string
        is_closed:
          default: false
          title: Is Closed
          type: boolean
        is_won:
          default: false
          title: Is Won
          type: boolean
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
        owner:
          anyOf:
            - type: string
            - type: 'null'
          description: The owner's user id
          title: Owner
        source:
          anyOf:
            - type: string
            - type: 'null'
          title: Source
        stage:
          anyOf:
            - type: string
            - type: 'null'
          title: Stage
        type:
          anyOf:
            - type: string
            - type: 'null'
          title: Type
      required:
        - id
      title: Opportunity
      type: object
  securitySchemes:
    HTTPBearer:
      scheme: bearer
      type: http
      description: >-
        An API key, sent as `Authorization: Bearer stfy_live_…`. See
        [Authentication](/rest-api/authentication) for how to get one and which
        scopes it needs.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.