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

# Create files

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

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.

## Request body

- object
  - `document` DocumentWritable
    - `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

## Response `200`

Successful Response

- DocumentAll
  - `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

## Other responses

- `422`: The request was understood but a value is missing, invalid or too long.

---

[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)