# Paperless-ngx

> File paperwork in Paperless-ngx: add documents from links or text, find them by their words, tag them, note on them and keep their details tidy. Start a workflow when a document is added.

App · 16 actions. Web page: https://docs.lodol.com/docs/integrations/paperless-ngx

## Actions

### Add note

Add a note to a document, shown beside it in Paperless.

**Inputs**

- Document (`document`, text, required): The document's number, from 'Search documents' or the trigger, or its link.
- Note (`note`, text, required): What to note, such as Paid on 3 November.

**Outputs**

- `document_id` (number): The document's number
- `note` (text): The note added
- `notes` (number): How many notes it has now

**Example output**

```json
{
  "document_id": 412,
  "note": "Paid on 3 November",
  "notes": 1
}
```

### Add tag

Put a tag on a document.

**Inputs**

- Document (`document`, text, required): The document's number, from 'Search documents' or the trigger, or its link.
- Tag (`tag`, text, required): The tag.

**Outputs**

- `added` (text): When it was added to Paperless (ISO 8601)
- `archive_serial_number` (number): Its archive serial number; 0 if none
- `content` (text): Its text, as Paperless read it; cut short in a search
- `correspondent` (text): Who it's from
- `created` (text): The date on it (YYYY-MM-DD)
- `document_type` (text): What kind of document it is
- `file_name` (text): The name of the file it came from
- `id` (number): The document's number
- `link` (text): A link to it in Paperless
- `notes` (number): How many notes it has
- `snippet` (text): In a search by words, where they matched
- `tag_ids` (list): Its tags, by number
- `tags` (list): Its tags, by name
- `title` (text): Its title

**Example output**

```json
{
  "added": "2026-10-28T09:00:00.000000Z",
  "archive_serial_number": 0,
  "content": "City Power & Light. Amount due: $84.20 by 15 November 2026.",
  "correspondent": "City Power & Light",
  "created": "2026-10-21",
  "document_type": "Invoice",
  "file_name": "bill-2026-10.pdf",
  "id": 412,
  "link": "https://paperless.example.com/documents/412/details",
  "notes": 0,
  "snippet": "",
  "tag_ids": [
    3,
    7
  ],
  "tags": [
    "Bills",
    "To pay"
  ],
  "title": "Electricity bill October 2026"
}
```

### Create tag

Make a tag. Paperless puts it only where you or a workflow add it.

**Inputs**

- Name (`name`, text, required): What to call it, such as To pay.
- Colour (`color`, text): Its colour, such as #a6cee3. Leave blank for Paperless to pick one.

**Outputs**

- `color` (text): Its colour
- `document_count` (number): How many documents have it
- `id` (number): Its number
- `name` (text): Its name

**Example output**

```json
{
  "color": "#a6cee3",
  "document_count": 0,
  "id": 7,
  "name": "To pay"
}
```

### Delete document

Move a document to Paperless's trash, where it can be restored for 30 days by default.

**Inputs**

- Document (`document`, text, required): The document's number, from 'Search documents' or the trigger, or its link.

**Outputs**

- `deleted` (true/false): True once deleted
- `id` (number): The document's number

**Example output**

```json
{
  "deleted": true,
  "id": 412
}
```

### Delete tag

Delete a tag. Documents that had it keep everything else.

**Inputs**

- Tag (`tag`, text, required): The tag.

**Outputs**

- `deleted` (true/false): True once deleted
- `id` (number): The tag's number

**Example output**

```json
{
  "deleted": true,
  "id": 7
}
```

### Get current user

Who the connection acts as in Paperless.

**Inputs**: None.

**Outputs**

- `id` (number): The user's number
- `is_superuser` (true/false): Whether they're a Paperless administrator
- `name` (text): Their name
- `username` (text): Their username

**Example output**

```json
{
  "id": 1,
  "is_superuser": false,
  "name": "Ada Lovelace",
  "username": "ada"
}
```

### Get document

Get a document's details and its full text, as Paperless read it.

**Inputs**

- Document (`document`, text, required): The document's number, from 'Search documents' or the trigger, or its link.

**Outputs**

- `added` (text): When it was added to Paperless (ISO 8601)
- `archive_serial_number` (number): Its archive serial number; 0 if none
- `content` (text): Its text, as Paperless read it; cut short in a search
- `correspondent` (text): Who it's from
- `created` (text): The date on it (YYYY-MM-DD)
- `document_type` (text): What kind of document it is
- `file_name` (text): The name of the file it came from
- `id` (number): The document's number
- `link` (text): A link to it in Paperless
- `notes` (number): How many notes it has
- `snippet` (text): In a search by words, where they matched
- `tag_ids` (list): Its tags, by number
- `tags` (list): Its tags, by name
- `title` (text): Its title

**Example output**

```json
{
  "added": "2026-10-28T09:00:00.000000Z",
  "archive_serial_number": 0,
  "content": "City Power & Light. Amount due: $84.20 by 15 November 2026.",
  "correspondent": "City Power & Light",
  "created": "2026-10-21",
  "document_type": "Invoice",
  "file_name": "bill-2026-10.pdf",
  "id": 412,
  "link": "https://paperless.example.com/documents/412/details",
  "notes": 0,
  "snippet": "",
  "tag_ids": [
    3,
    7
  ],
  "tags": [
    "Bills",
    "To pay"
  ],
  "title": "Electricity bill October 2026"
}
```

### Get upload status

Check whether Paperless has finished reading a document you added, and get its number.

**Inputs**

- Task ID (`task_id`, text, required): The task ID an add action returned.

**Outputs**

- `document_id` (number): The new document's number, once added; 0 before
- `link` (text): A link to the new document, once added
- `message` (text): What Paperless said about the add
- `status` (text): added, queued (still being read) or failed
- `task_id` (text): Paperless's task ID for the add

**Example output**

```json
{
  "document_id": 412,
  "link": "https://paperless.example.com/documents/412/details",
  "message": "Success. New document id 412 created",
  "status": "added",
  "task_id": "6f1d3c1e-58a1-4c87-9a4b-2f5e1c9d7b20"
}
```

### List correspondents

List every correspondent, the people and companies documents come from.

**Inputs**: None.

**Outputs**

- `correspondents` (list): The correspondents
- `count` (number): How many

**Example output**

```json
{
  "correspondents": [
    {
      "document_count": 18,
      "id": 5,
      "name": "City Power & Light"
    }
  ],
  "count": 1
}
```

### List document types

List every document type, such as Invoice or Contract.

**Inputs**: None.

**Outputs**

- `count` (number): How many
- `document_types` (list): The document types

**Example output**

```json
{
  "count": 1,
  "document_types": [
    {
      "document_count": 96,
      "id": 2,
      "name": "Invoice"
    }
  ]
}
```

### List tags

List every tag, with how many documents have it.

**Inputs**: None.

**Outputs**

- `count` (number): How many
- `tags` (list): The tags

**Example output**

```json
{
  "count": 1,
  "tags": [
    {
      "color": "#a6cee3",
      "document_count": 41,
      "id": 3,
      "name": "Bills"
    }
  ]
}
```

### Remove tag

Take a tag off a document.

**Inputs**

- Document (`document`, text, required): The document's number, from 'Search documents' or the trigger, or its link.
- Tag (`tag`, text, required): The tag.

**Outputs**

- `added` (text): When it was added to Paperless (ISO 8601)
- `archive_serial_number` (number): Its archive serial number; 0 if none
- `content` (text): Its text, as Paperless read it; cut short in a search
- `correspondent` (text): Who it's from
- `created` (text): The date on it (YYYY-MM-DD)
- `document_type` (text): What kind of document it is
- `file_name` (text): The name of the file it came from
- `id` (number): The document's number
- `link` (text): A link to it in Paperless
- `notes` (number): How many notes it has
- `snippet` (text): In a search by words, where they matched
- `tag_ids` (list): Its tags, by number
- `tags` (list): Its tags, by name
- `title` (text): Its title

**Example output**

```json
{
  "added": "2026-10-28T09:00:00.000000Z",
  "archive_serial_number": 0,
  "content": "City Power & Light. Amount due: $84.20 by 15 November 2026.",
  "correspondent": "City Power & Light",
  "created": "2026-10-21",
  "document_type": "Invoice",
  "file_name": "bill-2026-10.pdf",
  "id": 412,
  "link": "https://paperless.example.com/documents/412/details",
  "notes": 0,
  "snippet": "",
  "tag_ids": [
    3
  ],
  "tags": [
    "Bills"
  ],
  "title": "Electricity bill October 2026"
}
```

### Save text as document

Keep words, such as an email or a form answer, as a document in Paperless.

**Inputs**

- Title (`title`, text, required): The document's title.
- Text (`text`, text, required): What the document says.
- Date (`created`, date): The date on the document. Leave blank to let Paperless find it.
- Correspondent (`correspondent`, text): Who it's from. Leave blank to let Paperless match one.
- Document type (`document_type`, text): What kind of document it is. Leave blank to let Paperless match one.
- Tags (`tags`, list): Tags to put on it, besides any Paperless matches.

**Outputs**

- `document_id` (number): The new document's number, once added; 0 before
- `link` (text): A link to the new document, once added
- `message` (text): What Paperless said about the add
- `status` (text): added, queued (still being read) or failed
- `task_id` (text): Paperless's task ID for the add

**Example output**

```json
{
  "document_id": 412,
  "link": "https://paperless.example.com/documents/412/details",
  "message": "Success. New document id 412 created",
  "status": "added",
  "task_id": "6f1d3c1e-58a1-4c87-9a4b-2f5e1c9d7b20"
}
```

### Search documents

Find documents by words in their text, a tag, a correspondent or a type. Newest first unless searching by words.

**Inputs**

- Words (`query`, text): Words to look for in the documents' text and titles. Leave blank to list the newest.
- Tag (`tag`, text): Only documents with this tag.
- Correspondent (`correspondent`, text): Only documents from this correspondent.
- Document type (`document_type`, text): Only documents of this type.
- How many (`limit`, number): The most to list. Defaults to 25. From 1 to 100.

**Outputs**

- `count` (number): How many are listed
- `documents` (list): The documents found
- `total` (number): How many match in all

**Example output**

```json
{
  "count": 1,
  "documents": [
    {
      "added": "2026-10-28T09:00:00.000000Z",
      "archive_serial_number": 0,
      "content": "City Power & Light. Amount due: $84.20 by 15 November 2026.",
      "correspondent": "City Power & Light",
      "created": "2026-10-21",
      "document_type": "Invoice",
      "file_name": "bill-2026-10.pdf",
      "id": 412,
      "link": "https://paperless.example.com/documents/412/details",
      "notes": 0,
      "snippet": "",
      "tag_ids": [
        3,
        7
      ],
      "tags": [
        "Bills",
        "To pay"
      ],
      "title": "Electricity bill October 2026"
    }
  ],
  "total": 1
}
```

### Update document

Change a document's title, correspondent, type, date or archive serial number.

**Inputs**

- Document (`document`, text, required): The document's number, from 'Search documents' or the trigger, or its link.
- Title (`title`, text): A new title. Leave blank to keep it.
- Correspondent (`correspondent`, text): Who it's from. Leave blank to keep it.
- Document type (`document_type`, text): What kind of document it is. Leave blank to keep it.
- Date (`created`, date): The date on the document. Leave blank to keep it.
- Archive serial number (`archive_serial_number`, number): The number on the paper original's label. Leave blank to keep it. At least 0.

**Outputs**

- `added` (text): When it was added to Paperless (ISO 8601)
- `archive_serial_number` (number): Its archive serial number; 0 if none
- `content` (text): Its text, as Paperless read it; cut short in a search
- `correspondent` (text): Who it's from
- `created` (text): The date on it (YYYY-MM-DD)
- `document_type` (text): What kind of document it is
- `file_name` (text): The name of the file it came from
- `id` (number): The document's number
- `link` (text): A link to it in Paperless
- `notes` (number): How many notes it has
- `snippet` (text): In a search by words, where they matched
- `tag_ids` (list): Its tags, by number
- `tags` (list): Its tags, by name
- `title` (text): Its title

**Example output**

```json
{
  "added": "2026-10-28T09:00:00.000000Z",
  "archive_serial_number": 0,
  "content": "City Power & Light. Amount due: $84.20 by 15 November 2026.",
  "correspondent": "City Power & Light",
  "created": "2026-10-21",
  "document_type": "Invoice",
  "file_name": "bill-2026-10.pdf",
  "id": 412,
  "link": "https://paperless.example.com/documents/412/details",
  "notes": 0,
  "snippet": "",
  "tag_ids": [
    3,
    7
  ],
  "tags": [
    "Bills",
    "To pay"
  ],
  "title": "Electricity bill October 2026"
}
```

### Upload document from link

Download a file, such as a PDF invoice, from a link and add it to Paperless.

**Inputs**

- Link (`url`, text, required): A link anyone can download the file from, starting with https://.
- Title (`title`, text): The document's title. Leave blank to use the file's name.
- Date (`created`, date): The date on the document. Leave blank to let Paperless find it.
- Correspondent (`correspondent`, text): Who it's from. Leave blank to let Paperless match one.
- Document type (`document_type`, text): What kind of document it is. Leave blank to let Paperless match one.
- Tags (`tags`, list): Tags to put on it, besides any Paperless matches.

**Outputs**

- `document_id` (number): The new document's number, once added; 0 before
- `link` (text): A link to the new document, once added
- `message` (text): What Paperless said about the add
- `status` (text): added, queued (still being read) or failed
- `task_id` (text): Paperless's task ID for the add

**Example output**

```json
{
  "document_id": 412,
  "link": "https://paperless.example.com/documents/412/details",
  "message": "Success. New document id 412 created",
  "status": "added",
  "task_id": "6f1d3c1e-58a1-4c87-9a4b-2f5e1c9d7b20"
}
```
