developers API Documentation

The API is HTTP based and uses a REST approach for objects inside the system. All requests and responses follow the same pattern, so you'll know what to expect for each request.

The main functions for a REST-based api include HTTP verbs (GET, POST, PUT, DELETE) to perform all the basic CRUD operations on an object.

Request Action
GET /:object List this objects
GET /:object/id Show contents of an object
POST /:object Create an object
PUT /:object/:id Update an object
DELETE /:object/:id Delete an object

Requests

When requesting data via a command-line tool like curl, you can choose the format in which to send your POST requests. You can send it either in http-request format, or in JSON format.

Example

Here's an example of creating a note in http request format:

curl -v -X POST \
  -H "Accept: application/json" \
  -d "note[content]=note all the things&note[deal_id]=237" \
  "https://api.pipelinedeals.com/api/v3/notes.json?api_key=abc1234"
      

And here's the same request being made in JSON format:

curl -v -X POST \
  -H "Accept: application/json"
  -H "Content-type: application/json" \
  -d '"note": { "content": "note all the things", "deal_id": 237 }' \
  "https://api.pipelinedeals.com/api/v3/notes.json?api_key=abc1234"
      

For both requests, the response comes back as:

{
  "user_id": 1,
  "company_id": 5,
  "title": null,
  "updated_at": "2012/05/25 11:36:37 -0400",
  "note_category": {
    "name": "Phone Call",
    "id": 1
  },
  "created_at": "2012/02/14 18:49:00 -0500",
  "deal_id": 2,
  "note_category_id": 1,
  "user": {
    "first_name": "admin",
    "last_name": "nick",
    "id": 1,
    "avatar_thumb_url": "https://s3.amazonaws.com/pipelinedeals/avatars/1/thumb/newavatar.png"
  },
  "person_id": 4,
  "id": 2,
  "content": "note test22"
}

    

Sample GET request

Here is an example of getting the contents of a deal.

GET /api/v3/deals/1234.json?api_key=abc1234

A breakdown of the request:

  • The first parameter is the object we are interested in, always in plural form.
  • Since we are simply GETting the deal details, we can just pass the deal ID.
  • All requests must include the api_key of the user in the account who is making the request.

Responses

Responses will always be in JSON format.

The success or failure of a request will be accompanied by a HTTP Code.

HTTP Codes

Code Meaning
200 Everything worked fine
422 A validation error had occurred
429 Rate limit exceeded, or you are not hitting the correct url. Please refer to the error message that came with the code.
500 An internal error has occurred, this is probably not your fault.

Specifying attributes

All requests allow you to specify individual attributes that come back, in case you do not need to pay attention to every attribute.

You can enable this by passing attrs parameter with a comma-separated list of attributes you want back.

Request

GET /api/v3/people.json?api_key=abcd1234&attrs=id,last_name

Response

{"id":3,"last_name":"Ajtai"}

Rate limits

You can make up to 5 requests per second. Once you exceed 5 requests, you will need to wait before making additional requests. This allows you to use the API within a web request cycle for up to 10 calls with no "sleep" in between.

If you have a registered API application, you can make up to 10 requests per second without being limited. To register your API application, please contact us.