PipelineDeals

developers API Documentation

API

Overview

Primary Resources

Admin Resources

Web-to-leads

Automations

Deals

Deal Attributes

Name Type Default val Example Writable? Description
id integer auto-incremented 1234 no The unique id of the deal
name string My deal yes The name of the deal
summary string Quite a large deal yes A description of the deal
user_id integer 1234 yes The owner id of the deal
user object {full_name: 'Bob Smith', id: 1234} no A convenience object to get the full name of the deal owner
status integer 1 yes A simple red-yellow-green status for the deal. 1 = red, 2 = yellow, 3 = green.
custom_fields object { custom_label_90: [45, 46, 47], custom_label_5: "text val" } yes Custom fields for the deal. See custom fields section for more info.
created_at datetime 2012/02/07 15:26:10 -0500 yes Timestamp for when deal was created
updated_at datetime 2012/02/07 15:26:10 -0500 yes Timestamp for when deal was last updated
import_id integer 1234 no The id of the import, if the deal was imported
import_id integer 1234 no The id of the import, if the deal was imported
expected_close_date_event_id integer 1234 no The id of the expected close date calendar entry
expected_close_date date 2011-01-01 yes The expected close date
closed_time date 2011-01-01 yes The date when the deal was closed (either won or lost)
is_archived boolean false yes Flag for archived status
value decimal 123.45 yes The deal's value, possibly with decimal value (depends on the currency of the account)
value_in_cents integer 12345 yes The deal's value, in cents. DEPRECATED: Please use value instead.
primary_contact_id integer 1234 yes The id of the primary contact for the deal
primary_contact object {id: 1234, full_name: 'Bob Smith'} no A convenience object to display the full name of the primary contact for a deal
people array [{"id": 1234, "first_name": "Rose", "last_name": "Tyler"}] no A convenient list of people on the deal that includes name and id for each.
person_ids array [4,5] yes An array of person ids that are associated with the deal.
collaborators array [{"first_name": "Willy","last_name": "Wonka","id": 4,"api_key": "f00dbeef"}] no A convenient list of collaborators that includes basic attributes for each.
shared_user_ids array [6,7] yes The array of user ids with whom the deal's been shared.
company object { id: 5, name: "Apple" } no An convenience object to get the name of the company associated with the deal
company_id integer 1234 yes The id of the company associated with the deal
company_name string Bob Inc. yes The company name of the deal (if changed, will find or create a company by that name)
currency object { code: "USD", name: "US Dollar", symbol: "$" } no The deal's currency
probability integer 50 yes

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_id integer 1234 yes The id of the deal stage
deal_stage object {id: 1234, name: 'Proposal'} no A convenience object to get the stage name for a deal.
deal_loss_reason_id integer 1234 yes The id of the deal loss reason
deal_loss_reason object {id: 1234, name: 'Price'} no A convenience object to get the loss reason name for a deal.
deal_loss_reason_notes string The price was too high. yes A description of the deal loss reason.
source_id integer 1234 yes The source id of the deal. You can get a list of sources from the lead_sources call.
source object {id: 1234, name: 'Hot'} no A convenience object to get the name of the source.
possible_notify_user_ids array [1,2,3,4,5] no The list of user_ids that can be added to notify_user_ids on associated notes.

Deal Associations

Retrieve notes associated to a deal

GET /api/v3/deals/1234/notes.json

Retrieve people associated to a deal

GET /api/v3/deals/1234/people.json

Retrieve calendar entries associated to a deal

GET /api/v3/deals/1234/calendar_entries.json

Receive a list of all Deals

Request format

GET /deals.json

Request Parameters

Param Type Description
page integer The current page.
per_page integer The maximum amount of deals to bring back per page. Default is 200.
search_id integer Search deals by previously saved filter with given search_id. Note: when you provide a search_id, all parameters except page and per_page will be ignored.
totals boolean When set to true, the response will include all total-able fields (ie. deal value, commission, bonus, custom fields, etc.). Default is false.
conditions[deal_id] integer The deal with given deal_id. Note: you can specify a comma-separated list of ids to retrieve more deals at once, e.g. conditions[deal_id]=1,2,3
conditions[deal_name] string The deals with name like deal_name
conditions[deal_percentage] integer The deals that match deal_percentage
conditions[deal_source] integer The deals that match deal_source, (source_id)
conditions[deal_owner] integer The deals owned by deal_owner, (user_id). This parameter will also accept all to return deals owned by anyone.
conditions[deal_value] integer The deals with values between deal_value
conditions[deal_stage] integer The deals with stage deal_stage, (stage_id)
conditions[exp_close] datetime range The deals with expected close dates on exp_close. See the docs about datetime range for more info.
conditions[deal_created] datetime range The deals created within the range. See the docs about datetime range for more info.
conditions[deal_modified] datetime range The deals modified within the range. See the docs about datetime range for more info.
conditions[deal_closed_time] datetime range The deals closed within the range. See the docs about datetime range for more info.
conditions[person_full_name] string The deals with the person's full name like person_full_name
conditions[person_email] string The deals with the person's email like person_email
conditions[person_phone] string The deals with the person's phone like person_phone
conditions[person_city] string The deals with the person's city like person_city
conditions[person_state] string The deals with the person's state like person_state
conditions[person_work_zip] string The deals with the person's work zip like person_work_zip
conditions[person_zip] string The deals with the person's zip like person_zip
conditions[person_company_name] string The deals with the person's company name like person_company_name
sort string Sort by deals.name, -deals.name, deals.owner_id, -deal.owner_id, deals.source_id, -deals.source_id, deals.probability, -deals.probability, deals.expected_close_date, -deals.expected_close_date, deals.created_at, -deals.created_at, deals.updated_at, -deals.updated_at, deals.closed_time, -deals.closed_time,

Examples

curl "https://api.pipelinedeals.com/api/v3/deals.json?api_key=abc1234"
HTTP Code
200
Body
{
  "entries": [
    {
      "people": [
        {
          "full_name": "john hammer",
          "id": 17
        }
      ],
      "value_in_cents": null,
      "is_archived": false,
      "primary_contact_id": 17,
      "closed_time": null,
      "user_id": 1,
      "expected_close_date": null,
      "source_id": null,
      "expected_close_date_event_id": null,
      "name": "kjkjkj",
      "id": 1,
      "user": {
        "full_name": "admin nick",
        "id": 1
      },
      "company_id": 4,
      "primary_contact": {
        "full_name": "john hammer",
        "id": 17
      },
      "probability": 25,
      "import_id": null,
      "person_ids": [
        17
      ],
      "is_example": null,
      "company": {
        "name": "apple",
        "id": 4
      },
      "status": 1,
      "created_at": "2012/01/19 15:26:09 -0500",
      "updated_at": "2012/04/18 10:20:18 -0400",
      "summary": null,
      "custom_fields": {
        "custom_label_24": 1,
        "custom_label_25": 5,
        "custom_label_83": [

        ],
        "custom_label_26": 9,
        "custom_label_27": 0,
        "custom_label_88": 0
      },
      "deal_stage_id": 3,
      "deal_stage": {
        "percent": 25,
        "name": "Request for Info",
        "id": 3
      }
    },
    {
      "people": [
        {
          "full_name": "Ken Yarmosh",
          "id": 4
        }
      ],
      "value_in_cents": null,
      "is_archived": false,
      "primary_contact_id": 4,
      "closed_time": null,
      "user_id": 1,
      "expected_close_date": null,
      "source_id": 1,
      "expected_close_date_event_id": null,
      "name": "bargle deal",
      "id": 2,
      "user": {
        "full_name": "admin nick",
        "id": 1
      },
      "company_id": 5,
      "primary_contact": {
        "full_name": "Ken Yarmosh",
        "id": 4
      },
      "probability": 75,
      "import_id": null,
      "person_ids": [
        4
      ],
      "is_example": null,
      "company": {
        "name": "bramble",
        "id": 5
      },
      "status": 1,
      "created_at": "2012/01/26 15:11:02 -0500",
      "updated_at": "2012/06/13 15:20:06 -0400",
      "summary": null,
      "custom_fields": {
        "custom_label_25": 4,
        "custom_label_83": [

        ],
        "custom_label_27": 0,
        "custom_label_88": 0
      },
      "deal_stage_id": 5,
      "deal_stage": {
        "percent": 75,
        "name": "Negotiation",
        "id": 5
      },
      "source": {
        "name": "None",
        "id": 1
      }
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 2,
    "total": 3
  }
}

Create a deal

Request format

POST https://api.pipelinedeals.com/api/v3/deals.json

Applying a todo template

To apply a deals-based todo template, pass the deal todo_template_id when creating the deal.

To set the owner of any tasks created by applying the given todo template, you may also pass a todo_template_user_id parameter. 

curl -X POST -d "deal[name]=Kinda a big deal&todo_template_id=1234&todo_template_user_id=42" \
"https://api.pipelinedeals.com/api/v3/deals.json?api_key=abc1234"


Examples

curl -X POST -d "deal[name]=Kinda a big deal" \
  "https://api.pipelinedeals.com/api/v3/deals.json?api_key=abc1234"
HTTP Code
200
Body
{
  "value_in_cents": null,
  "primary_contact_id": 3,
  "id": 3,
  "updated_at": "2012/06/14 11:54:13 -0400",
  "company_id": 6,
  "summary": null,
  "expected_close_date_event_id": null,
  "closed_time": null,
  "name": "tester",
  "user": {
    "id": 1,
    "full_name": "admin nick"
  },
  "primary_contact": {
    "id": 3,
    "full_name": "Veronika Ajtai"
  },
  "company": {
    "id": 6,
    "name": "zingle"
  },
  "currency_code": "GBP",
  "probability": 10,
  "custom_fields": {
    "custom_label_83": [

    ],
    "custom_label_88": 0,
    "custom_label_24": 1,
    "custom_label_25": 5,
    "custom_label_26": 9,
    "custom_label_27": 0
  },
  "deal_stage_id": 2,
  "is_example": null,
  "person_ids": [
    3
  ],
  "deal_stage": {
    "id": 2,
    "percent": 10,
    "name": "Qualified Lead"
  },
  "expected_close_date": null,
  "created_at": "2012/02/07 15:26:10 -0500",
  "source_id": null,
  "is_archived": false,
  "status": 3,
  "people": [
    {
      "id": 3,
      "full_name": "Veronika Ajtai"
    }
  ],
  "import_id": null,
  "user_id": 1
}

Failure Response

HTTP Code
422
Body
[
    {
        "field": "name", 
        "humanized_field": "Name", 
        "msg": "can't be blank"
    }
]

Retrieve a single deal

Request format

GET /deals/:id.json

Examples

curl \
  "https://api.pipelinedeals.com/api/v3/deals/8.json?api_key=abc1234"
HTTP Code
200
Body
{
  "value_in_cents": null,
  "primary_contact_id": 3,
  "id": 3,
  "updated_at": "2012/06/14 11:54:13 -0400",
  "company_id": 6,
  "summary": null,
  "expected_close_date_event_id": null,
  "closed_time": null,
  "name": "tester",
  "user": {
    "id": 1,
    "full_name": "admin nick"
  },
  "primary_contact": {
    "id": 3,
    "full_name": "Veronika Ajtai"
  },
  "company": {
    "id": 6,
    "name": "zingle"
  },
  "probability": 10,
  "custom_fields": {
    "custom_label_83": [

    ],
    "custom_label_88": 0,
    "custom_label_24": 1,
    "custom_label_25": 5,
    "custom_label_26": 9,
    "custom_label_27": 0
  },
  "deal_stage_id": 2,
  "is_example": null,
  "person_ids": [
    3
  ],
  "people": [
    {
      "id": 3,
      "first_name": "Rose",
      "last_name": "Tyler"
    }
  ],
  "deal_stage": {
    "id": 2,
    "percent": 10,
    "name": "Qualified Lead"
  },
  "expected_close_date": null,
  "created_at": "2012/02/07 15:26:10 -0500",
  "source_id": null,
  "is_archived": false,
  "status": 3,
  "import_id": null,
  "user_id": 1,
  "shared_user_ids": [
    4
  ],
  "collaborators": [
    {
      "first_name": "Willy",
      "last_name": "Wonka",
      "id": 4,
      "api_key": "f00dbeef"
    }
  ],
  "possible_notify_user_ids": [
    1, 2, 3, 4, 5
  ]
}

Failure Response

HTTP Code
422
Body
empty

Update a deal

Request format

PUT /deals/:id.json

Applying a todo template

To apply a deals-based todo template, pass the deal todo_template_id when updating the deal.

To set the owner of any tasks created by applying the given todo template, you may also pass a todo_template_user_id parameter. 

curl -X PUT -d "deal[name]=myname&todo_template_id=1234&todo_template_user_id=42" \
"https://api.pipelinedeals.com/api/v3/deals/3.json?api_key=abc1234"

Examples

curl -X PUT -d "deal[name]=Updating deal 3" \
  "https://api.pipelinedeals.com/api/v3/deals/3.json?api_key=abc1234"
HTTP Code
200
Body
{
    "account_id": 3, 
    "bonus": null, 
    "closed_time": null, 
    "commission_rate": null, 
    "company_id": null, 
    "created_at": "2012/01/12 14:34:35 -0500", 
    "custom_fields_applied_at": "2012/01/12 14:34:35 -0500", 
    "custom_fields_hidden": false, 
    "deal_import_id": null, 
    "deal_stage_id": null, 
    "expected_close_date": null, 
    "expected_close_date_event_id": null, 
    "id": 3014, 
    "import_id": null, 
    "is_archived": false, 
    "is_shared": false, 
    "last_modified_by_user_id": null, 
    "name": "Updating deal 3", 
    "primary_contact_id": null, 
    "probability": null, 
    "source_id": null, 
    "status": null, 
    "summary": null, 
    "updated_at": "2012/01/12 14:36:10 -0500", 
    "user": {
        "full_name": "Benjamin Rhodes", 
        "id": 1
    }, 
    "user_id": 1, 
    "value_in_cents": null, 
    "viewed_at": null
}

Failure Response

HTTP Code
404
Body
empty

Delete a deal

Request format

DELETE /deals/:id.json

Examples

curl -X DELETE "https://api.pipelinedeals.com/api/v3/deals/8.json?api_key=abc1234"
HTTP Code
200
Body
empty

Failure Response

HTTP Code
404
Body
empty
PipelineDeals iOS App
PipelineDeals Android App
Features
Resources
Company
From the blog
@pipelinedeals tweets

© 2020 PipelineDeals. All rights reserved.