GET /contacts/{contact_id}/deals

Get all deals for a specific contact

Returns the deals on this contact, with the same paging, sorting and filters as GET /deals — including filtering by status, stage, pipeline_id or owner_id.

Path parameters

Name	Type	Description
`contact_id` req	string	Contact ID

Query parameters (14)

Name	Type	Description
`name`	string	Search deals by name
`search`	string	Search deals by deal name, contact name or company name
`status`	string	Return deals of a particular status (i.e. `pending`, `won`, `lost`, or `closed`)
`stage`	integer	Return deals (of status `pending`) with specified deal stage
`owner_id`	string	Return deals owned by a specific user
`date_filter`	string	Signals which date field to be used for only returning resources, added or edited, in a specified date range (only to be used with `since` and/or `until`, not with `modified_since` or `unmodified_since`)
`since`	string	Specifies the start of the date range to filter resources, which have been added or edited (use with `date_filter` - date must be in format `YYYY-MM-DD` or UNIX timestamp)
`until`	string	Specifies the end of the date range to filter resources, which have been added or edited (use with `date_filter` - date must be in format `YYYY-MM-DD` or UNIX timestamp)
`modified_since`	string	Return only resources that were modified since specified time (cannot be used with `date_filter` - date must be in format `YYYY-MM-DD` or UNIX timestamp)
`unmodified_since`	string	Return only resources that were unmodified since specified time (cannot be used with `date_filter` - date must be in format `YYYY-MM-DD` or UNIX timestamp)
`sort_by`	string	Specify field by which to order the results (use in conjunction with `order`)
`order`	string	Specify the order (ascending or descending) of the sort of the results (use in conjunction with `sort_by`)
`page`	integer	Page number. Starts from 1. Default is 1.
`per_page`	integer	Number of records to return. Maximum 100 allowed. Default is 10.

Responses

200 OK

statusintegerint32
Response code
messagestring
Response message
timestampintegerunix-timestamp
Response time
dataobject
object fields →
- dealsarray<object>
  array item fields →
  dealobject
  Represent (potential) financial transactions with your contacts. Deals include information like amount, deal stage, closed date or expected close date. Deals support file attachments.
  object fields →
  idstringbson-id
  ID of the deal
  contact_idstringbson-idrequired
  ID of the contact, to whom the deal belongs
  owner_idstringbson-idrequired
  ID of the user, to whom the deal belongs. Defaults to the logged API user's ID.
  pipeline_idstringbson-id
  ID of a pipeline the deal belongs to
  sales_pipeline_idstringbson-id
  ID of a sales pipeline the deal belongs to
  namestringrequired
  Name of the deal
  textstring
  Extra notes related to the deal (supports `[b]bold[/b]` and `[i]italic[/i]` formatting)
  stageintegerint32
  A numerical representation of the progress of a pending deal (number ranging from 0 to 100 exclusive)
  statusstring
  Status of the deal
  enum: pending · won · lost
  expected_close_datestringdate
  The date the deal is expected to close (status should be `pending`). Defaults to today's date.
  close_datestringdate
  The date the deal actually closed (status should be `won` or `lost`). Defaults to today's date.
  datestringdate
  Creation date of the deal. Defaults to today's date.
  amountnumberfloat
  The monitary value of the deal (per month, if multi-month deal)
  monthsintegerint32
  Number of months the deal is to be paid for (1 for regular deals, 2+ for multi-month)
  costnumberfloat
  The monitary cost of the deal
  marginnumberfloat
  Profit margin for the deal (`amount` minus `cost`)
  total_amountnumberfloat
  Product of amount and months (will only differ from `amount` field, if multi-month deal)
  total_costnumberfloat
  Product of cost and months (will only differ from `cost` field, if multi-month deal)
  commission_basestring
  Base used to calculate the commission of the deal
  enum: amount · margin
  commission_typestring
  Type of commission for the deal
  enum: none · percentage · absolute
  commissionnumberfloat
  Commission payable for the deal
  commission_percentagenumberfloat
  Commission percentage for the deal
  reason_lost_idstringbson-id
  ID of the reason lost
  deal_fieldsarray<object>
  Custom field values on the deal.
  array item fields →
  deal_fieldobject
  Extra user-configurable data fields for Deals. Only editable by admins.
  object fields →
  idstringbson-id
  ID of the deal field
  namestringrequired
  Name of the deal field
  typestringrequired
  Type of the deal field. There are several types of custom fields that may store data in different formats. External ID type is a special type introduced for referencing entities in the external systems. Its value is unique amid the whole system. Section divider type is introduced just for visual purpose: it allows grouping custom fields. If custom fields in the section don't have values then they are hidden in the 'view' UI (but always shown in 'edit' UI). This logic is applied in the API: if a deal doesn't have values for all the custom fields in the section then this section divider custom field isn't exposed in the API (along with other custom fields inside the section).
  enum: date · multi_line_text · multiple_choice · number · select_box · single_line_text · external_id · section_divider
  positionintegerint32
  The position of the deal field in the list
  choicesarray<string>
  A list of possible choices (for fields of type `multiple_choice` or `select_box`)
  valuestring
  Value for the deal field
  has_deal_itemsboolean
  Does the deal have deal items?
  deal_itemsarray<object>
  Line items on the deal — each with a name, quantity, price, cost and amount.
  array item fields →
  idstringbson-id
  ID of the deal item
  namestringrequired
  Name of the deal item
  descriptionstringrequired
  Description text of the deal item
  costnumberfloatrequired
  Cost of the deal item
  pricenumberfloatrequired
  Price of the deal item
  amountnumberfloat
  Amount of the deal items
  qtyintegerint32required
  Quantity of deal items
  deal_idstringbson-id
  ID of the parent deal
  predefined_item_idstringbson-id
  ID of the predefined item used for deal item creation (can be empty)
  positionintegerint32
  Position of the predefined item in the items list
  created_atstringdate-time
  Creation time of the deal item
  modified_atstringdate-time
  Last modification time of the deal item
  authorstring
  Shortened name of the creator of the deal. Defaults to the logged API user.
  has_related_notesboolean
  Does the deal have related notes?
  attachmentsarray<object>
  Files attached to the deal.
  array item fields →
  idstringbson-id
  ID of the attachment
  filenamestringrequired
  Name of the attachment file
  custom_filenamestring
  Custom name of the attachment file
  pinnedboolean
  Show if the attachment is pinned to its owner contact
  pinned_atstring
  Shows pinned at timestamp. Is null if pinned == false
  sizeintegerint32required
  Size of the attachment file (in bytes)
  storage_providerstring
  Name of the storage provider (where the attachment file is stored)
  enum: amazon · google_drive · dropbox · evernote
  urlstring
  External URL of the attachment file
  url_expires_atstringdate-time
  The time the attachment URL expires
  thumbnailobject
  An image preview of the attachment file (if one exists)
  object fields →
  urlstring
  External URL of the attachment's thumbnail
  contact_infoobject
  Information about the contact, to whom the deal belongs (read only).
  object fields →
  contact_namestring
  Name of the contact associated with the deal
  companystring
  Name of the company associated with the deal
  ownerobject
  Information about the deal owner (read only).
  object fields →
  idstring
  ID of the deal owner
  namestring
  Name of the deal owner
  emailstring
  Email address of the deal owner
  previous_pipeline_stagesobject
  Returns the last stage in which the deal was for each pipeline (pipeline_id => stage) This field is returned only when 'include_history=true' param is supplied in query string
  created_atstringdate-time
  Creation time of the deal
  modified_atstringdate-time
  Last modification time of the deal
  linked_contactsarray<object>
  Short form of contacts linked to the deal. Always returned with the deal payload (on both `GET /deals` and `GET /deals/{deal_id}`). For full contact objects use `fields=contacts(all)` on `GET /deals`.
  array item fields →
  idstringbson-id
  ID of the linked contact
  contact_namestring
  Full display name of the linked contact
  companystring
  Display name of the company the contact belongs to (empty string if none)
  photo_urlstring
  URL of the contact's profile picture (empty string if none)
- total_countintegerint32
  Total number of items
- pageintegerint32
  Current page number
- per_pageintegerint32
  Number of items returned in each page
- max_pageintegerint32
  The page number of the last page of items

Standard error responses: 400 · 401 · 403 · 404 · 409 · 500 — shared across the API. See Errors.

Related guides

GET /contacts/{contact_id}/deals

curl "https://app.onepagecrm.com/api/v3/contacts/{contact_id}/deals" \
  -u $user_id:$api_key

200 example response

{
  "status": 0,
  "message": "OK",
  "timestamp": 1528373119,
  "data": {
    "deals": [
      {
        "deal": {
          "id": "5aaa9b059007ba08c9ebaf58",
          "contact_id": "5aaa9b059007ba08c9ebaf58",
          "owner_id": "5aba31e99007ba0f570c12f7",
          "pipeline_id": "5cfa87a4849d7873db082f98",
          "sales_pipeline_id": "5cfa87a4849d7873db082f98",
          "name": "Solar panels",
          "text": "Fingers crossed!",
          "stage": 50,
          "status": "pending",
          "expected_close_date": "2018-04-15",
          "close_date": "2018-04-15",
          "date": "2018-04-15",
          "amount": 99.99,
          "months": 1,
          "cost": 0,
          "margin": 99.99,
          "total_amount": 99.99,
          "total_cost": 0,
          "commission_base": "amount",
          "commission_type": "none",
          "commission": 0,
          "commission_percentage": 0,
          "reason_lost_id": "5aaa9b059007ba08c9ebaf58",
          "deal_fields": [
            {}
          ],
          "has_deal_items": true,
          "deal_items": [
            {}
          ],
          "author": "Jane D.",
          "has_related_notes": true,
          "attachments": [
            {}
          ],
          "contact_info": {
            "contact_name": "Joe Bloggs",
            "company": "Big Company Inc."
          },
          "owner": {
            "id": "5aba31e99007ba0f570c12f7",
            "name": "Joe Bloggs",
            "email": "joe.bloggs@example.com"
          },
          "previous_pipeline_stages": {
            "5da7b67a849d78737812437c": 40
          },
          "created_at": "2018-03-15T16:10:45Z",
          "modified_at": "2018-03-15T16:10:45Z",
          "linked_contacts": [
            {
              "id": "68b5edd78b3ee61b685c8692",
              "contact_name": "Sajed Almorsy",
              "company": "OnePageCRM",
              "photo_url": ""
            }
          ]
        }
      }
    ],
    "total_count": 1,
    "page": 1,
    "per_page": 10,
    "max_page": 1
  }
}