developers API Documentation

Documents are called "Files" in the PipelineDeals UI, but for historic reasons are still called "Documents" in the api.


Document Attributes

Name Type Example Description
id integer 1234 The unique id of the document
title string Screenshot.png The filename the document
created_at datetime 2012/02/07 15:26:10 -0500 Timestamp for when document was created
updated_at datetime 2012/02/07 15:26:10 -0500 Timestamp for when document was last updated
owner_id integer 1234 The id of the document owner
person_id integer 1234 The id of the person
public_link string https://pipelinedeals.s3.amazonaws.com/document.txt A link to get the document
size_in_k integer 102 The size of the document, in kilobytes
owner object {id: 1234, full_name: 'Bob Smith'} A convenience object to get the full name of the document owner
person object {id: 1234, full_name: 'Bob Smith'} A convenience object to get the full name of the person the document was uploaded to
deal object {id: 1234, name: 'Big Deal'} A convenience object to get the name of the deal the document was uploaded to
etag string edd88e4bfa45c14de553c40d17c8f504 The hash that uniquely identifies the document
upload_status number 1 If you created a document, this will identify the document's upload state. The state will be either 1, 2, or 3, which correspond to "pending", "complete", or "error". If the state is "error", the error message is available in upload_status_error_message.
upload_status_error_message string The server returned 404 Not Found If for some reason the document's url returned a non-200 response, the upload_state will be "error", and the upload_status_error_message will be the error returned.
upload_state string pending If you created a document, this will identify the document's upload state. The state will be either "pending", "error", or "complete".
document_tag_ids array [123, 124] An array of document tag ids this document is tagged with
document_tags object [{id: 123, name: 'Contract'}, {id: 124, name: 'Proposal'}] A convenience object to get the tag names

Receive a list of documents

Request format

GET api/v3/documents.json

Request Parameters

Param Type Default Description
page integer 1 The offset of documents.
per_page integer 30 The number of documents per page.
sort string The attribute to sort on.
conditions[document_name] string The documents with name like documents_name
conditions[document_type] string all Only documents with document_type [all, spreadsheets, images, documents, pds, presentations, others]
conditions[document_owner] integer logged in user Only documents owned by document owner
conditions[associated_with] string all Only documents associated with [all, companies, deals, email, people, shared]
conditions[document_uploaded][from_date] datetime 2012/02/07 15:26:10 -0500 Timestamp for the from field when the document was uploaded
conditions[document_uploaded][to_date] datetime 2012/02/07 15:26:10 -0500 Timestamp for the to field when the document was uploaded
conditions[document_owner] integer 1 The unique id of the owner
conditions[document_name] string The filename the document
conditions[document_modified] datetime range Companies updated within the specified date range. See the docs about datetime range for more info.

Examples

curl https://api.pipelinedeals.com/api/v3/documents.json?api_key=abc1234
HTTP Code
200
Body
      {
  "entries": [
    {
      "created_at": "2014/01/09 16:11:54 -0500",
      "deal_id": 154,
      "id": 1,
      "owner_id": 1,
      "person_id": null,
      "title": "aocbar58.jpg",
      "updated_at": "2014/01/09 16:11:54 -0500",
      "upload_status": 2,
      "public_link": "https://pipeline-dev-userdata.s3.amazonaws.com/uploaded_documents/2/aocbar58.jpg?AWSAccessKeyId=AKIAIG7CDR66ZRRYWPFA&Expires=1389306316&Signature=Uuxu0rxox8pCB0BDXFI1FKQGy48%3D&response-content-disposition=attachment&response-content-type=image%2Fjpeg",
      "size_in_k": 238,
      "upload_state": "complete",
      "etag": "ab7d82d93e533a96191455a1838080b9",
      "owner": {
        "id": 1,
        "first_name": "hobo",
        "last_name": "hoboson"
      },
      "deal": {
        "id": 154,
        "name": "maximize mission-critical interfaces"
      },
      "person": null,
      "company": null
    }
  ],
  "pagination": {
    "page": 1,
    "page_var": "page",
    "per_page": 5,
    "pages": 1,
    "total": 1
  }
}

    

Retrieve a single document

Request format

GET api/v3/documents/1234.json

Examples

curl https://api.pipelinedeals.com/api/v3/documents/1234.json?api_key=abc1234
HTTP Code
200
Body
{
    "created_at": "2014/01/09 16:31:25 -0500",
    "deal_id": 154,
    "id": 2,
    "owner_id": 1,
    "person_id": null,
    "title": "meme.jpg",
    "updated_at": "2014/01/09 16:31:25 -0500",
    "upload_status": 1,
    "public_link": "https://pipeline-dev-userdata.s3.amazonaws.com/uploaded_documents/3/meme.jpg?AWSAccessKeyId=AKIAIG7CDR66ZRRYWPFA&Expires=1389306689&Signature=4xZ2m%2F1TCUF3jVCHJmw57o5KkVI%3D&response-content-disposition=attachment&response-content-type=image%2Fjpeg",
    "size_in_k": 802,
    "upload_state": "pending",
    "etag": "395afc28d81c9591796613fe253f4067",
    "owner": {
        "id": 1,
        "first_name": "hobo",
        "last_name": "hoboson"
    },
    "deal": {
        "id": 154,
        "name": "maximize mission-critical interfaces"
    },
    "person": null,
    "company": null
}

Create a document

Request format

POST api/v3/documents.json

Request parameters

Param Type Description
title String The filename for the document that the user will see.
updated_at Datetime The time the document was last updated.
deal_id integer The id of the deal to associate with
person_id integer The id of the person to associate with
owner_id integer The id of the user who uploaded the document
url string The url the document is available at

To create a document using the api, you must pass a url as an attribute of the document. The url must be a publicly accessible url where the endpoint exists. We will then grab the document from that url and upload it to PipelineDeals in the background.

The steps are as follows:

  1. POST document with url attribute. The document will be created, and the upload_status will be "pending".
  2. In the background, we will attempt to grab that document from the url sent, and upload it to PipelineDeals.
  3. If the upload was successful, the document's upload_status will be set to "complete"
  4. If the upload was unsuccessful for any reason, the upload_status will be set to "error", and the upload_status_error_message attribute will be populated with any errors we received when trying to retrieve the document from the url specified.

If the document did not upload successfully, you can try another url by using a PUT against the document id. See more below about updating documents.

Examples

curl -X POST -d "document[deal_id]=1234&document[owner_id]=1234&document[title]=proposal.docx&document[url]=http://dropbox.com/file/proposal.pdf" https://api.pipelinedeals.com/api/v3/documents.json?api_key=abc1234
HTTP Code
200
Body
{
    "created_at": "2014/01/09 16:31:25 -0500",
    "deal_id": 154,
    "id": 2,
    "owner_id": 1,
    "person_id": null,
    "title": "meme.jpg",
    "updated_at": "2014/01/09 16:31:25 -0500",
    "upload_status": 1,
    "public_link": "https://pipeline-dev-userdata.s3.amazonaws.com/uploaded_documents/3/meme.jpg?AWSAccessKeyId=AKIAIG7CDR66ZRRYWPFA&Expires=1389306689&Signature=4xZ2m%2F1TCUF3jVCHJmw57o5KkVI%3D&response-content-disposition=attachment&response-content-type=image%2Fjpeg",
    "size_in_k": 802,
    "upload_state": "pending",
    "etag": "395afc28d81c9591796613fe253f4067",
    "owner": {
        "id": 1,
        "first_name": "hobo",
        "last_name": "hoboson"
    },
    "deal": {
        "id": 154,
        "name": "maximize mission-critical interfaces"
    },
    "person": null,
    "company": null
}

Update a document

Request format

PUT api/v3/documents/123.json

You can update a document's `url` if there was a problem when creating a document. If you update a document's `url`, we will attempt to get the document from that url again, and update the `upload_status` as described in the create documentation above.

Examples

curl -X PUT -d "document[deal_id]=1234&document[owner_id]=1234&document[title]=proposal.docx&document[url]=http://dropbox.com/Proposal.doc" https://api.pipelinedeals.com/api/v3/documents/123.json?api_key=abc1234
HTTP Code
200
Body
{
    "created_at": "2014/01/09 16:31:25 -0500",
    "deal_id": 154,
    "id": 2,
    "owner_id": 1,
    "person_id": null,
    "title": "meme.jpg",
    "updated_at": "2014/01/09 16:31:25 -0500",
    "upload_status": 1,
    "public_link": "https://pipeline-dev-userdata.s3.amazonaws.com/uploaded_documents/3/meme.jpg?AWSAccessKeyId=AKIAIG7CDR66ZRRYWPFA&Expires=1389306689&Signature=4xZ2m%2F1TCUF3jVCHJmw57o5KkVI%3D&response-content-disposition=attachment&response-content-type=image%2Fjpeg",
    "size_in_k": 802,
    "upload_state": "pending",
    "etag": "395afc28d81c9591796613fe253f4067",
    "owner": {
        "id": 1,
        "first_name": "hobo",
        "last_name": "hoboson"
    },
    "deal": {
        "id": 154,
        "name": "maximize mission-critical interfaces"
    },
    "person": null,
    "company": null
}

Update a document's tags

To update a document's tags supply an array with the set of tag ids you would like to be applied. Unknown tag ids will be ignored.

Examples

curl -X PUT -d "document[document_tag_ids][]=13&document[document_tag_ids][]=28" \"https://api.pipelinedeals.com/api/v3/documents/9.json?api_key=abc1234"

Delete a document

Request format

DELETE api/v3/documents/123.json

Examples

curl -X DELETE https://api.pipelinedeals.com/api/v3/documents/123.json?api_key=abc1234
HTTP Code
200
Body

No body returned for a delete request.