Files (Documents)

Create files

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 Pipeline 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 Pipeline.
  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.

post/documents

Request

  • Base URL: https://api.pipelinecrm.com/api/v3
  • URL: https://api.pipelinecrm.com/api/v3/documents
  • Auth: one of:
    • HTTP bearer
    • HTTP bearer and API key in header app-key
    • API key in query parameter api_key and API key in query parameter app_key

Request body

Example request

{
  "document": {
    "updated_at": "2026-09-01 14:22:07",
    "title": "Acme-renewal-quote-v2.pdf",
    "owner_id": 123,
    "person_id": 123,
    "deal_id": 123,
    "company_id": 123,
    "calendar_entry_id": 123,
    "primary_association_id": 123,
    "primary_association_type": "CalendarTask",
    "url": "https://app.pipelinecrm.com/documents/7710"
  }
}

Response

Successful Response

idinteger

Unique identifier

created_atstring

Timestamp when the record was created (time zone in user's time zone).

size_in_kinteger

The size of the document, in kilobytes

etagstring nullable

The hash that uniquely identifies the document

upload_statusinteger

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_messagestring nullable

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_statestring

If you created a document, this will identify the document's upload state. The state will be either "pending", "error", or "complete".

document_tag_idsinteger[]

An array of document tag ids this document is tagged with

public_linkstring

A link to get the document

updated_atstring

Timestamp when the record was last touched (time zone in user's time zone).

titlestring

The filename the document

owner_idinteger

The id of the document owner

person_idinteger nullable

The id of the person

deal_idinteger nullable

The id of the deal

company_idinteger nullable

The id of the company

calendar_entry_idinteger nullable

The id of the calendar entry (task or event)

primary_association_idinteger

The id of the primary association (Deal, Person, Company, or CalendarEntry). Alternative way to associate documents with entities.

primary_association_type'Deal' | 'Person' | 'Company' | 'CalendarTask' | 'CalendarEvent'

The type of the primary association. When associating with a calendar entry, use CalendarTask or CalendarEvent.

urlstring

The url the document is available at

Example response

{
  "id": 7710,
  "created_at": "2026-09-01 14:22:07",
  "size_in_k": 102,
  "owner": {
    "id": 13,
    "full_name": "Sam Okafor"
  },
  "person": {
    "id": 8802,
    "full_name": "Jane Rivera"
  },
  "deal": {
    "id": 4521,
    "name": "Acme Corporation - Q4 renewal"
  },
  "company": {
    "id": 3310,
    "name": "Acme Corporation"
  },
  "calendar_entry": {
    "id": 5602,
    "name": "Kickoff call with Acme"
  },
  "etag": "edd88e4bfa45c14de553c40d17c8f504",
  "upload_status": 2,
  "upload_status_error_message": "The server returned 404 Not Found",
  "upload_state": "pending",
  "document_tag_ids": [
    123,
    124
  ],
  "document_tags": [
    {
      "id": 5,
      "name": "Contract"
    }
  ],
  "public_link": "https://pipelinedeals.s3.amazonaws.com/document.txt",
  "updated_at": "2026-09-01 14:22:07",
  "title": "Acme-renewal-quote-v2.pdf",
  "owner_id": 123,
  "person_id": 123,
  "deal_id": 123,
  "company_id": 123,
  "calendar_entry_id": 123,
  "primary_association_id": 123,
  "primary_association_type": "CalendarTask",
  "url": "https://app.pipelinecrm.com/documents/7710"
}

Changes

No recorded changes to this operation across all 1 revision of this API.