Correspondents

Correspondents represent the senders or recipients that Paperless-ngx associates with documents. They support the full CRUD lifecycle and permission management.

Models

See pypaperless/models/correspondents.py for all fields and pypaperless/models/types.py for enum and filter types, and the Paperless-ngx API docs for the upstream schema.

Fetch one

correspondent = await paperless.correspondents(7)
print(correspondent.name)            # "ACME Corp"
print(correspondent.document_count)  # 42

Iterate

async for c in paperless.correspondents:
    print(c.id, c.name)

# Collect everything into a list
all_correspondents = await paperless.correspondents.as_list()

# Fetch only a subset matching a filter
filtered = [
    c async for c in paperless.correspondents
    if c.document_count and c.document_count > 0
]

Create

draft = paperless.correspondents.create()
draft.name = "ACME Corp"

pk = await paperless.correspondents.save(draft)
print(pk)  # primary key of the new correspondent

Update

c = await paperless.correspondents(7)
c.name = "ACME Corp (renamed)"

changed = await paperless.correspondents.update(c)
# True  → server accepted the change
# False → nothing was sent (no fields actually changed)

Pass only_changed=False to force a full PUT instead of a PATCH:

await paperless.correspondents.update(c, only_changed=False)

Delete

c = await paperless.correspondents(7)
await paperless.correspondents.delete(c)

Raises DeletionError on failure. Pass silent_fail=True to suppress it.

Permissions

async with paperless.correspondents.with_permissions():
    c = await paperless.correspondents(7)
    print(c.owner)        # owner user id
    print(c.permissions)  # Permissions

See Permissions for details on reading and modifying permission sets.