---
title: "List files"
method: GET
path: "/documents"
tags: ["Files (Documents)"]
---

# List files

`GET /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`

**Filtered request example** — Documents on one deal whose name contains proposal:

```
curl -g -H "Authorization: Bearer pcrm_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  "https://api.pipelinecrm.com/api/v3/documents.json?conditions[document_deal_id]=4521&conditions[document_name]=proposal&per_page=50"
```

## Query parameters

- `sort` string
- `conditions` DocumentConditions
  - `associated_with` 'all' | 'companies' | 'deals' | 'email' | 'people' | 'shared': Returns records with given association
  - `document_association` string: Documents whose primary association is one of the given records, each written as `<name>:<Type>:<id>` (the name is ignored), for example `Acme:Company:3310`.
  - `document_company_id` union: Returns records associated with the given company IDs
    - integer
    - integer[]
  - `document_deal_id` union: Returns records associated with the given deal IDs
    - integer
    - integer[]
  - `document_id` union: Returns records with the given IDs
    - integer
    - integer[]
  - `document_modified` union: A date or datetime filter. Send ONE of the forms below (see the Filtering guide): a single day `2026-01-15`; a bounded range `[from_date]=2026-01-01&[to_date]=2026-03-31` (either side optional); a relative period `[selection]=last_30` or `[selection]=this_quarter`; or a relative count `[selection]=last_x_days&[duration]=14`.
    - string: A single day (`YYYY-MM-DD`) or a relative period keyword such as `today`, `yesterday`, `this_week`, `last_week`, `next_week`, `this_month`, `last_month`, `next_month`, `this_quarter`, `last_quarter`, `next_quarter`, `this_year`, `last_year`, `year_to_date`, `last_7`, `last_30`, `last_60`, `last_90`, `next_7`, `next_30`, `next_60`, `next_90`, `last_3_months`, `next_3_months`, `last_6_months`, `next_6_months`, `last_12_months`, `next_12_months`, `past_due`, `future`.
    - object: An explicit range. Either bound may be omitted.
      - `from_date` string, date
      - `to_date` string, date
    - object: A relative period counted in whole units.
      - `selection` 'last_x_days' | 'next_x_days' | 'last_x_weeks' | 'next_x_weeks' | 'last_x_months' | 'next_x_months' | 'last_x_quarters' | 'next_x_quarters' | 'last_x_years' | 'next_x_years' | 'older_than', required
      - `duration` integer, required
  - `document_name` string: Returns records with name like documents_name
  - `document_owner` integer: Returns records owned by document owner (defaults to current user)
  - `document_person_id` union: Returns records associated with the given person IDs
    - integer
    - integer[]
  - `document_primary_association_name` string: Returns records that match a `LIKE` query on the primary association name
  - `document_shared` 'Yes' | 'No': Returns records that are shared or not
  - `document_tags` union: Returns records that are tagged with the given tag ids
    - integer
    - integer[]
  - `document_type` 'all' | 'spreadsheets' | 'images' | 'documents' | 'pds' | 'presentations' | 'others': Returns records with given document_type
  - `document_uploaded` object
    - `from_date` string: Timestamp for the from field when the record was uploaded
    - `to_date` string: Timestamp for the to field when the record was uploaded
  - `status` 'complete' | 'incomplete': Upload state: `complete` (the file has been received) or `incomplete` (the upload was started but never finished).
- `calendar_entry_id` integer

## Response `200`

Successful Response

- object
  - `entries` DocumentAll[], required
    - `id` integer: Unique identifier
    - `created_at` string: Timestamp when the record was created (time zone in user's time zone).
    - `size_in_k` integer: The size of the document, in kilobytes
    - `owner` object: A convenience object to get the full name of the document owner
      - `id` integer
      - `full_name` string
    - `person` object, nullable: A convenience object to get the full name of the person the document was uploaded to
      - `id` integer
      - `full_name` string
    - `deal` object, nullable: A convenience object to get the name of the deal the document was uploaded to
      - `id` integer
      - `name` string
    - `company` object, nullable: A convenience object to get the name of the company the document was uploaded to
      - `id` integer
      - `name` string
    - `calendar_entry` object, nullable: A convenience object to get the name and type of the calendar entry (task or event) the document was uploaded to
      - `id` integer
      - `name` string
      - `type` 'CalendarTask' | 'CalendarEvent'
    - `etag` string, nullable: The hash that uniquely identifies the document
    - `upload_status` integer: 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, 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_state` string: 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` integer[]: An array of document tag ids this document is tagged with
    - `document_tags` object[]: The document's tags, with names
      - `id` integer
      - `name` string
    - `public_link` string: A link to get the document
    - `updated_at` string: Timestamp when the record was last touched (time zone in user's time zone).
    - `title` string: The filename the document
    - `owner_id` integer: The id of the document owner
    - `person_id` integer, nullable: The id of the person
    - `deal_id` integer, nullable: The id of the deal
    - `company_id` integer, nullable: The id of the company
    - `calendar_entry_id` integer, nullable: The id of the calendar entry (task or event)
    - `primary_association_id` integer: 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.
    - `url` string: The url the document is available at
  - `pagination` Pagination, required: Paging details returned alongside `entries` on every paginated list.
    - `page` integer: The page returned. Request another with `?page=N`.
    - `per_page` integer: Page size. `?per_page=N`, capped at 200.
    - `total` integer: Total number of records matching the request across all pages.
    - `pages` integer: Number of pages at this `per_page`.
    - `total_in_account` integer, nullable: Total number of records of this type visible to you before filters were applied. Null when not computed for the endpoint.
    - `page_var` string: Name of the query parameter that selects the page. Always `page`.
    - `url` string, nullable: Path of the request, when the endpoint reports it.

---

[API](https://skmtc.dev/pipelinecrm/apis/pipeline-crm-api.md) · [All operations](https://skmtc.dev/pipelinecrm/apis/pipeline-crm-api/llms.txt) · [OpenAPI document](https://skmtc.dev/pipelinecrm/apis/pipeline-crm-api/revisions/53ebfcc83597?raw)