Deals

Create deal

post/deals

Request

  • Base URL: https://api.pipelinecrm.com/api/v3
  • URL: https://api.pipelinecrm.com/api/v3/deals
  • Auth: one of:
    • HTTP bearer
    • HTTP bearer and API key in header app-key
    • API key in query parameter api_key and API key in query parameter app_key

Query parameters

deliver_assignment_emailboolean

If true, and you are assigning the deal to a different user, the system will send an assignment email to the new user. Setting it to false will disable sending an assignment email.

Request body

todo_template_idinteger

The ID of the todo template to apply to this deal

todo_template_user_idinteger

The owner of any tasks created by applying the given todo template

Example request

{
  "deal": {
    "created_at": "2026-09-01 14:22:07",
    "updated_at": "2026-09-01 14:22:07",
    "name": "Acme Corporation - Q4 renewal",
    "summary": "Renewal of the 120-seat plan; legal review in progress.",
    "user_id": 13,
    "status": 1,
    "expected_close_date": "2026-10-15",
    "value": "12000.0",
    "primary_contact_id": 8802,
    "person_ids": [
      1,
      2,
      3
    ],
    "shared_user_ids": [
      1,
      2,
      3
    ],
    "company_id": 3310,
    "company_name": "Acme Corporation",
    "probability": 60,
    "deal_stage_id": 3,
    "deal_loss_reason_notes": "Too expensive",
    "deal_won_reason_id": 4,
    "deal_won_reason_notes": "Great value for the price",
    "deal_source": 5,
    "custom_fields": {
      "custom_label_90": [
        45,
        46,
        47
      ],
      "custom_label_5": "text val"
    },
    "tag_ids": [
      3,
      4,
      5
    ],
    "address_1": "123 Main St.",
    "address_2": "Suite 100",
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "94105",
    "country": "USA"
  },
  "todo_template_id": 1,
  "todo_template_user_id": 13473
}

Response

Successful Response

idinteger

Unique identifier

import_idinteger nullable

The ID of the Import (if this deal was imported)

expected_close_date_event_idinteger nullable

The ID of the expected close date Calendar Entry

possible_notify_user_idsinteger[]

The list of User IDs that can be added to notify_user_ids on associated notes.

next_task_namestring

Name of the next calendar entry due associated with the deal

next_task_idinteger

The ID of the next calendar entry due associated with the deal

next_task_duestring

Due date of the next calendar entry due associated with the deal

next_task_all_dayboolean

Is the next calendar entry due associated with the deal an all day event?

created_atstring

Timestamp when the record was created (time zone in user's time zone).

updated_atstring

Timestamp when the record was last touched (time zone in user's time zone).

namestring

The name of the deal

summarystring nullable

Explanatory or descriptive text about the deal

user_idinteger

The ID of the user who owns this deal

statusinteger nullable

The ID of the deal status for this deal.

expected_close_datestring nullable

The date the deal is expected to close by (YYYY-MM-DD format)

closed_timestring nullable

The date the deal actually closed (either won or lost). YYYY-MM-DD format.

is_archivedboolean

Flag for archived status

valuestring nullable

The deal's value in its currency. A decimal serialized as a string (see Conventions); send a number or a numeric string.

primary_contact_idinteger nullable

The ID of the primary contact Person record associated with this deal

person_idsinteger[]

IDs of Person records associated to this deal

shared_user_idsinteger[]

The array of User IDs with whom this deal's been shared (also known as Collaborators)

company_idinteger nullable

The ID of the company associated to this deal

company_namestring

Creates a new Company associated to this deal if provided

probabilityinteger nullable

The probability, from 0-100, that the deal will close. Note that if you set the probability to 0 or 100, the deal will close. Similarly, if the deal is closed, and you set the probability to 1-99, the deal will re-open and closed_time will be set to nil.

deal_stage_idinteger nullable

ID of the deal stage this deal is in.

deal_loss_reason_idinteger nullable

The ID of the Deal Loss Reason for this deal.

deal_loss_reason_notesstring nullable

Explanatory or descriptive text about why the deal was lost

deal_won_reason_idinteger nullable

The ID of the Deal Won Reason for this deal.

deal_won_reason_notesstring nullable

Explanatory or descriptive text about why the deal was won

deal_sourceinteger

The ID of this deal's Lead Source

custom_fieldsobject

Custom fields for the deal. See custom fields section for more info.

tag_idsinteger[]

IDs of the tags to set on this deal

address_1string nullable

The first line of the deal's address

address_2string nullable

The second line of the deal's address

citystring nullable

The city of the deal's address

statestring nullable

The state of the deal's address

postal_codestring nullable

The postal code of the deal's address

countrystring nullable

The country of the deal's address

Example response

{
  "id": 4521,
  "owner": {
    "id": 13,
    "full_name": "Sam Okafor"
  },
  "primary_contact": {
    "id": 8802,
    "full_name": "Jane Rivera"
  },
  "people": [
    {
      "id": 8802,
      "first_name": "Jane",
      "last_name": "Rivera"
    },
    {
      "id": 8815,
      "first_name": "Marcus",
      "last_name": "Chen"
    }
  ],
  "collaborators": [
    {
      "id": 27,
      "first_name": "Priya",
      "last_name": "Natarajan"
    }
  ],
  "company": {
    "id": 3310,
    "name": "Acme Corporation"
  },
  "currency": {
    "name": "US Dollar",
    "code": "USD",
    "symbol": "$"
  },
  "deal_stage": {
    "id": 3,
    "name": "Proposal sent",
    "percent": 50
  },
  "deal_loss_reason": {
    "id": 1,
    "name": "Price"
  },
  "source": {
    "id": 5,
    "name": "Website"
  },
  "possible_notify_user_ids": [
    1,
    2,
    3,
    4,
    5
  ],
  "next_task_name": "Send revised quote",
  "next_task_id": 5602,
  "next_task_due": "2026/09/08",
  "tags": [
    {
      "id": 3,
      "name": "Enterprise"
    },
    {
      "id": 9,
      "name": "Renewal"
    }
  ],
  "created_at": "2026-09-01 14:22:07",
  "updated_at": "2026-09-01 14:22:07",
  "name": "Acme Corporation - Q4 renewal",
  "summary": "Renewal of the 120-seat plan; legal review in progress.",
  "user_id": 13,
  "status": 1,
  "expected_close_date": "2026-10-15",
  "value": "12000.0",
  "primary_contact_id": 8802,
  "person_ids": [
    1,
    2,
    3
  ],
  "shared_user_ids": [
    1,
    2,
    3
  ],
  "company_id": 3310,
  "company_name": "Acme Corporation",
  "probability": 60,
  "deal_stage_id": 3,
  "deal_loss_reason_notes": "Too expensive",
  "deal_won_reason_id": 4,
  "deal_won_reason_notes": "Great value for the price",
  "deal_source": 5,
  "custom_fields": {
    "custom_label_90": [
      45,
      46,
      47
    ],
    "custom_label_5": "text val"
  },
  "tag_ids": [
    3,
    4,
    5
  ],
  "address_1": "123 Main St.",
  "address_2": "Suite 100",
  "city": "San Francisco",
  "state": "CA",
  "postal_code": "94105",
  "country": "USA"
}

Changes

No recorded changes to this operation across all 1 revision of this API.