developers API Documentation

Company Attributes

Name Type Default val Example Writable? Description
id integer auto-incremented 1234 no The unique id of the company
name string My company yes The name of the company
description string yes
email string [email protected] yes The email of the company
web string contact.com yes The company's website
fax string yes
custom_fields object {custom_label_90: [45, 46, 47], custom_label_5: "text val"} yes Custom fields for the company. See custom fields section for more info.
created_at datetime 2012/02/07 15:26:10 -0500 yes Timestamp for when company was created
updated_at datetime 2012/02/07 15:26:10 -0500 yes Timestamp for when company was last updated
image_thumb_url string http://s3.amazonaws.com/avatar.png yes The uploaded avatar of the company. Avatar is scaled to maximum of 50x50 pixels.
image_mobile_url string https://s3.amazonaws.com/avatar.png no The uploaded mobile avatar of the company. Mobile avatar is scaled to maximum of 100x100 pixels.
address_1 string yes
address_2 string yes
city string yes
state string yes
postal_code string yes
country string yes
phone1 string yes
phone2 string yes
phone3 string yes
phone4 string yes
phone1_desc string yes
phone2_desc string yes
phone3_desc string yes
phone4_desc string yes
phone4_desc string yes
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.
owner_id integer yes The owner id of the company
owner object {full_name: 'Bob Smith', id: 1234} no A convenience object to get the full name of the company owner

Company Associations

Retrieve notes associated to a company

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

Retrieve people associated to a company

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

Retrieve deals associated to a company

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

Retrieve calendar entries associated to a company

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

Receive a list of Companies

Request format

GET /companies.json

Request Parameters

Param Type Description
page integer The page of companies.
per_page integer Number of companies per page.
search_id integer Search companies 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.
sort string Field to sort the companies on. Use a - minus sign for descending order.
conditions[company_id] integer The company with given company_id. Note: you can specify a comma-separated list of ids to retrieve more companies at once, e.g. conditions[company_id]=1,2,3
conditions[company_name] string Return companies that have a name that exactly matches or starts with the provided string
conditions[company_description] string Return companies that have a description that exactly matches or starts with the provided string
conditions[company_email] string Return companies that have an email that exactly matches or starts with the provided string
conditions[company_phone] string Return companies that have a phone number that exactly matches or starts with the provided string
conditions[company_fax] string Return companies that have a fax number that exactly matches or starts with the provided string
conditions[company_address] string Return companies that have an address that exactly matches or starts with the provided string
conditions[company_address2] string Return companies that have a secondary address that exactly matches or starts with the provided string
conditions[company_city] string Return companies that have a city that exactly matches or starts with the provided string
conditions[company_state] string Return companies that have a state that exactly matches or starts with the provided string
conditions[company_zip] string Return companies that have a postal code that exactly matches or starts with the provided string
conditions[company_country] string Return companies that have a country that exactly matches or starts with the provided string
conditions[company_created] datetime range Companies created within the specified date range. See the docs about datetime range for more info.
conditions[company_modified] datetime range Companies updated within the specified date range. See the docs about datetime range for more info.
conditions[company_imported_at] datetime range Companies with an imported_at within the specified date range. See the docs about datetime range for more info.

Examples

curl "https://api.pipelinedeals.com/api/v3/companies.json?api_key=abc1234"
HTTP Code
200
Body
{
  "pagination": {
    "page": 1,
    "per_page": 2,
    "total": 16
  },
  "entries": [
    {
      "id": 3,
      "name": "Advanta",
      "email": null,
      "web": null,
      "image_thumb_url": "/webpack/images/thumb/missing_company.png",
      "image_mobile_url": "/webpack/images/mobile/missing_company.png",
      "address_1": null,
      "address_2": null,
      "created_at": "2012/01/23 13:10:28 -0500",
      "fax": null,
      "phone3_desc": null,
      "city": "Manhattan",
      "phone1": null,
      "phone2": null,
      "phone3": null,
      "phone4": null,
      "postal_code": null,
      "phone1_desc": null,
      "phone4_desc": null,
      "state": null,
      "custom_fields": {
        "custom_label_83": []
      },
      "phone2_desc": null,
      "country": null,
      "import_id": null,
      "updated_at": "2012/06/01 14:36:01 -0400",
      "description": null
    },
    {
      "web": "test.com",
      "image_thumb_url": "/webpack/images/thumb/missing_company.png",
      "address_1": "123 Fake st",
      "address_2": "Suite 206",
      "created_at": "2012/02/13 17:32:38 -0500",
      "fax": null,
      "phone3_desc": null,
      "city": "Philadelphia",
      "phone1": "123-123-1234",
      "phone2": null,
      "phone3": null,
      "phone4": null,
      "postal_code": "12345",
      "email": null,
      "phone1_desc": null,
      "phone4_desc": null,
      "state": "PA",
      "custom_fields": {},
      "id": 4,
      "phone2_desc": null,
      "name": "apple",
      "country": "US",
      "import_id": null,
      "updated_at": "2012/04/17 11:08:03 -0400",
      "description": null
    }
  ]
}

Create a company

Request format

POST /companies.json

Examples

curl -X POST -d "company[name]=PipelineDeals" \
  "https://api.pipelinedeals.com/api/v3/companies.json?api_key=abc1234"
HTTP Code
200
Body
{
  "web": null,
  "phone1_desc": null,
  "fax": null,
  "address_1": null,
  "address_2": null,
  "country": null,
  "description": null,
  "created_at": "2012/01/23 13:10:28 -0500",
  "phone2_desc": null,
  "phone3_desc": null,
  "city": "dingletown",
  "name": "Advanta",
  "image_thumb_url": "/webpack/images/thumb/missing_company.png",
  "image_mobile_url": "/webpack/images/mobile/missing_company.png",
  "phone4_desc": null,
  "email": null,
  "id": 3,
  "import_id": null,
  "phone1": null,
  "phone2": null,
  "phone3": null,
  "phone4": null,
  "state": null,
  "custom_fields": {
    "custom_label_83": [

    ]
  },
  "postal_code": null,
  "updated_at": "2012/06/01 14:36:01 -0400"
}

Failure Response

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

Flags when creating a company

Below are a list of flags that can be used to manipulate how the system works when performing requests. They are added as parameters to the request.

check_for_duplicates

Default: false

Behavior: If true, the system will return an error if you attempt to create a duplicate company.

A duplicate is any company that that has the same name as any other company in your account.

Example of turning check_for_duplicates on

  curl -X POST -d "company[name]=KoopaKorp" \
  "https://api.pipelinedeals.com/api/v3/companies.json?api_key=fXKPfR09VAV82DcTR4BR&check_for_duplicates=true"
  

Retrieve a single company

Request format

GET /companies/:id.json

Request Parameters

Param Type Description
assocations comma string The list of associations you would like to retrieve with the company.

Examples

curl "https://api.pipelinedeals.com/api/v3/companies/30.json?associations=notes&api_key=abc1234"
HTTP Code
200
Body
{
  "web": null,
  "phone1_desc": null,
  "fax": null,
  "address_1": null,
  "address_2": null,
  "country": null,
  "description": null,
  "created_at": "2012/01/23 13:10:28 -0500",
  "phone2_desc": null,
  "phone3_desc": null,
  "city": "dingletown",
  "name": "Advanta",
  "image_thumb_url": "/webpack/images/thumb/missing_company.png",
  "image_mobile_url": "/webpack/images/mobile/missing_company.png",
  "phone4_desc": null,
  "email": null,
  "id": 3,
  "import_id": null,
  "phone1": null,
  "phone2": null,
  "phone3": null,
  "phone4": null,
  "state": null,
  "custom_fields": {
    "custom_label_83": [

    ]
  },
  "postal_code": null,
  "updated_at": "2012/06/01 14:36:01 -0400"
}

Failure Response

HTTP Code
404
Body
empty

Update a company

Request format

PUT /companies/:id.json

Examples

curl -X PUT -d "company[name]=RAWWWR Inc" \
  "https://api.pipelinedeals.com/api/v3/companies/30.json?api_key=abc1234"
HTTP Code
200
Body
{
  "web": null,
  "phone1_desc": null,
  "fax": null,
  "address_1": null,
  "address_2": null,
  "country": null,
  "description": null,
  "created_at": "2012/01/23 13:10:28 -0500",
  "phone2_desc": null,
  "phone3_desc": null,
  "city": "dingletown",
  "name": "Advanta",
  "image_thumb_url": "/webpack/images/thumb/missing_company.png",
  "image_mobile_url": "/webpack/images/mobile/missing_company.png",
  "phone4_desc": null,
  "email": null,
  "id": 3,
  "import_id": null,
  "phone1": null,
  "phone2": null,
  "phone3": null,
  "phone4": null,
  "state": null,
  "custom_fields": {
    "custom_label_83": [

    ]
  },
  "postal_code": null,
  "updated_at": "2012/06/01 14:36:01 -0400"
}

Failure Response

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

Flags when updating a company

Below are a list of flags that can be used to manipulate how the system works when performing requests. They are added as parameters to the request.

deliver_reassignment_email

Default: true

Behavior: If true, and you are changing a company's owner_id, the system will send an assignment email to the new user.

Example of turning deliver_reassignment_email off

  curl -X PUT -d "company[owner_id]=1234" \
  "https://api.pipelinedeals.com/api/v3/companies/123.json?api_key=fXKPfR09VAV82DcTR4BR&deliver_reassignment_email=false"
  

Delete a company

Request format

DELETE /companies/:id.json

Examples

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

Failure Response

HTTP Code
404
Body
empty