---
title: "Add a file"
method: POST
path: "/files"
tags: ["Files"]
---

# Add a file

`POST /files`

## Request

- Base URL: `https://api.parley.so/v1`
- URL: `https://api.parley.so/v1/files`
- Auth: HTTP bearer

Add an uploaded file to a project, account, contact, intake, or the Library: pass exactly one of projectId, accountId, contactId, intakeId, or library. Create the upload with POST /uploads and PUT the file's bytes to its url first. Parley then extracts the file's text in the background, and the file can be read once its status is ready. Adding the same upload again returns the same file; adding it anywhere else returns 409 UPLOAD_ALREADY_ADDED.

## Request body

- object
  - `projectId` string: Add it to this project's files. Pass exactly one of projectId, accountId, contactId, intakeId, or library.
  - `accountId` string: Add it to this account's files. Pass exactly one of projectId, accountId, contactId, intakeId, or library.
  - `contactId` string: Add it to this contact's files. Pass exactly one of projectId, accountId, contactId, intakeId, or library.
  - `intakeId` string: Add it to this intake's files. Pass exactly one of projectId, accountId, contactId, intakeId, or library.
  - `library` unknown
  - `uploadId` string, required: The id of an upload, once its bytes have been PUT to its url, holding the file to add. It keeps its file name. Adding the same upload again returns the same file.
  - `folderId` string: Put it inside this folder. Omit for the top level.

## Response `201`

Created.

- union: A file or a folder, told apart by type.
  - FileItem
    - `type` 'file', required
    - `id` string, required: The file or folder ID.
    - `name` string, required: The name, including any file extension.
    - `location` union, required: Whose files these are: a project's, an account's, a contact's, or an intake's, or the organization's Library.
      - RecordRef: A reference to a project, account, or contact.
        - `type` 'project' | 'account' | 'contact', required: The kind of record: project, account, or contact.
        - `id` string, required: Its ID.
        - `name` string, required: The record's name. A contact's is its first and last name, or an email address when it has no name.
      - object: The intake's type, ID, and name.
        - `type` 'intake', required
        - `id` string, required: Its ID.
        - `name` string, required: The intake title.
      - object: The organization's shared Library.
        - `type` 'library', required
    - `folder` object, nullable, required: The folder's type, ID, and name.
      - `type` 'folder', required
      - `id` string, required: Its ID.
      - `name` string, required: The folder name.
    - `createdAt` string, date-time, required: When it was added.
    - `updatedAt` string, date-time, required: When it was last updated, including processing, renames, and moves.
    - `mediaType` string, nullable, required: The file's media type, such as application/pdf, from its extension, or null when the extension isn't recognized.
    - `status` 'pending' | 'processing' | 'ready' | 'failed', required: Whether Parley has extracted the file's text: pending (queued), processing, ready (its text can be read), or failed (download it instead).
  - FolderItem
    - `type` 'folder', required
    - `id` string, required: The file or folder ID.
    - `name` string, required: The name, including any file extension.
    - `location` union, required: Whose files these are: a project's, an account's, a contact's, or an intake's, or the organization's Library.
      - RecordRef: A reference to a project, account, or contact.
        - `type` 'project' | 'account' | 'contact', required: The kind of record: project, account, or contact.
        - `id` string, required: Its ID.
        - `name` string, required: The record's name. A contact's is its first and last name, or an email address when it has no name.
      - object: The intake's type, ID, and name.
        - `type` 'intake', required
        - `id` string, required: Its ID.
        - `name` string, required: The intake title.
      - object: The organization's shared Library.
        - `type` 'library', required
    - `folder` object, nullable, required: The folder's type, ID, and name.
      - `type` 'folder', required
      - `id` string, required: Its ID.
      - `name` string, required: The folder name.
    - `createdAt` string, date-time, required: When it was added.
    - `updatedAt` string, date-time, required: When it was last updated, including processing, renames, and moves.

## Other responses

- `400`: The request was invalid. VALIDATION_FAILED, INVALID_REFERENCE.
- `401`: Missing or invalid credentials. UNAUTHORIZED.
- `403`: You don't have permission. FORBIDDEN.
- `409`: The request conflicts with the current state. UPLOAD_ALREADY_ADDED.
- `429`: Too many requests, or a usage limit was reached. TOO_MANY_REQUESTS.

---

[API](https://skmtc.dev/parley/apis/parley-api.md) - [All operations](https://skmtc.dev/parley/apis/parley-api/llms.txt) - [OpenAPI document](https://skmtc.dev/parley/apis/parley-api/revisions/6b78aeee07bc?raw)