Skip to main content
Talk to salesStart

Create deal

Create one Deal linked to exact organization companies and leads.

POST/api/deals
Scope deals:writeUpdated October 23, 2026

This page documents the canonical HTTP contract. Switch to the CLI example when you want the operator workflow.

A stage category determines Deal state. Creating a Deal in a won stage on a pipeline with marks_customer_on_win=true can mark direct Deal contacts as customers and exit linked account leads from prospecting sequences. The response is the created Deal; its organization, actor, and lifecycle history are server-owned.

Body parameters

  • namerequired

    string

    Non-empty Deal name, at most 240 characters.

  • primary_company_id · optional

    string | null

    Primary linked company ID.

  • company_ids · optional

    array<string>

    Linked company IDs in this organization.

  • lead_ids · optional

    array<string>

    Linked lead IDs in this organization.

  • owner_user_id · optional

    string | null

    Active owner user in this organization.

  • amount · optional

    object | null

    {value: decimal string, currency_code: three-letter currency code}.

  • pipeline_id · optional

    string | null

    Pipeline and stage must be set together.

  • stage_id · optional

    string | null

    Stage in the selected active pipeline.

  • expected_close_date · optional

    date | null

  • actual_close_date · optional

    date | null

  • next_step · optional

    string | null

  • custom_fields · optional

    object

    Values validated against active Deal custom fields.

Errors

StatusMeaning
400Invalid association, owner, pipeline, stage, or custom field.
401Authentication required.
403Missing deals:write scope.
422Invalid Deal payload.

Docs