Documents

Usage

List documents and folders:

import asyncio
import factorialhr

async def main():
    auth = factorialhr.AccessTokenAuth("your_access_token")
    async with factorialhr.ApiClient(auth=auth) as api:
        docs = factorialhr.DocumentsEndpoint(api)
        response = await docs.get(params={"page": 1})
        for doc in response.data():
            print(doc.name, doc.document_type)
        folders = factorialhr.FoldersEndpoint(api)
        for folder in (await folders.all()).data():
            print(folder.name)

asyncio.run(main())

class factorialhr.Document(*, author_id: int | None = None, company_id: int | None = None, content_type: str | None = None, created_at: datetime, employee_id: int | None = None, extension: str | None = None, file_size: int | None = None, filename: str, folder_id: int | None = None, id: int, is_company_document: bool | None = None, is_management_document: bool | None = None, is_pending_assignment: bool | None = None, leave_id: int | None = None, public: bool, signature_status: SignatureStatus | None = None, signees: Sequence[int] | None = None, space: str, updated_at: datetime, deleted_at: datetime | None = None)[source]

Model for documents_document.

author_id: int | None: Access identifier of the author, refers to /employees/employees endpoint

company_id: int | None: Company identifier, refers to /api/me endpoint

content_type: str | None: Document content type

created_at: datetime: Creation date of the document

deleted_at: datetime | None: Deletion date of the document

employee_id: int | None: Employee identifier associated to the document

extension: str | None: Document extension

file_size: int | None: Document file size in bytes

filename: str: Name of the document

folder_id: int | None: Folder identifier, references to documents/folders endpoint

id: int: Document identifier

is_company_document: bool | None: Flag that indicates if the document is a company document

is_management_document: bool | None: Flag that indicates if the document is a management document

is_pending_assignment: bool | None: Flag that indicates if the document is pending assignment

leave_id: int | None: Leave identifier associated to the document, refers to /timeoff/leaves endpoint

public: bool: Flag to indicate if the document is public

signature_status: SignatureStatus | None: Document signature status

signees: Sequence[int] | None: List of signee access identifiers associated to the document, refers to /employees/employees endpoint

space: str: Document space

updated_at: datetime: Last update date of the document

class factorialhr.DocumentsEndpoint(api: ApiClient)[source]

Endpoint for documents/documents operations.

async all(**kwargs) → ListApiResponse[Document][source]

Get all documents records.

Official documentation: documents/documents

Parameters:: kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.
Raises:: httpx.HTTPStatusError – When the API returns an error status code.
Returns:: Response containing the list of records.
Return type:: ListApiResponse[Document]

async create(data: Mapping[str, Any], **kwargs) → Document[source]

Create a new document.

Official documentation: documents/documents

Parameters:

data (Mapping[str, Any]) – Payload for the new record (key-value mapping).
kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

The created record.

Return type:

Document

async delete(document_id: int | str, **kwargs) → Document[source]

Delete a document.

Official documentation: documents/documents

Parameters:

document_id (int | str) – The unique identifier of the record to delete.
kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

The deleted record.

Return type:

Document

async get(**kwargs) → MetaApiResponse[Document][source]

Get documents with pagination metadata.

Official documentation: documents/documents

Parameters:: kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.
Raises:: httpx.HTTPStatusError – When the API returns an error status code.
Returns:: Response containing records and pagination metadata.
Return type:: MetaApiResponse[Document]

async get_by_id(document_id: int | str, **kwargs) → Document[source]

Get a specific document by ID.

Official documentation: documents/documents

Parameters:

document_id (int | str) – The unique identifier.
kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

The record.

Return type:

Document

async move_to_trash_bin(document_ids: Sequence[int], **kwargs) → Sequence[Document][source]

Move documents to trash bin.

Official documentation: documents/documents

Parameters:

document_ids (int | str) – The unique identifier.
kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

Result.

Return type:

Sequence[Document]

async restore_from_trash_bin(document_ids: Sequence[int], **kwargs) → Sequence[Document][source]

Restore documents from trash bin.

Official documentation: documents/documents

Parameters:

document_ids (int | str) – The unique identifier.
kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

Result.

Return type:

Sequence[Document]

async update(document_id: int | str, data: Mapping[str, Any], **kwargs) → Document[source]

Update a document.

Official documentation: documents/documents

Parameters:

document_id (int | str) – The unique identifier of the record to update.
data (Mapping[str, Any]) – Payload with fields to update (key-value mapping).
kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

The updated record.

Return type:

Document

class factorialhr.DownloadUrl(*, id: int, url: str)[source]

Model for documents_download_url.

id: int: Document identifier

url: str: Temporal document url

class factorialhr.DownloadUrlsEndpoint(api: ApiClient)[source]

Endpoint for documents/download_urls operations.

async bulk_create(document_ids: Sequence[int], **kwargs) → Sequence[DownloadUrl][source]

Bulk create download URLs for documents.

Official documentation: documents/download_urls

Parameters:

document_ids (int | str) – The unique identifier.
kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

The created record.

Return type:

Sequence[DownloadUrl]

class factorialhr.Folder(*, active: bool, company_id: int | None = None, id: int, name: str, parent_folder_id: int | None = None, space: str)[source]

Model for documents_folder.

active: bool: Whether the folder is active or not

company_id: int | None: Company ID of the folder

id: int: Folder ID

name: str: Folder name

parent_folder_id: int | None: Id of the parent folder

space: str: The space of the folder is related to the place where the folder is displayed

class factorialhr.FoldersEndpoint(api: ApiClient)[source]

Endpoint for documents/folders operations.

async all(**kwargs) → ListApiResponse[Folder][source]

Get all folders records.

Official documentation: documents/folders

Parameters:: kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.
Raises:: httpx.HTTPStatusError – When the API returns an error status code.
Returns:: Response containing the list of records.
Return type:: ListApiResponse[Folder]

async create(data: Mapping[str, Any], **kwargs) → Folder[source]

Create a new folder.

Official documentation: documents/folders

Parameters:

data (Mapping[str, Any]) – Payload for the new record (key-value mapping).
kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

The created record.

Return type:

Folder

async get(**kwargs) → MetaApiResponse[Folder][source]

Get folders with pagination metadata.

Official documentation: documents/folders

Parameters:: kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.
Raises:: httpx.HTTPStatusError – When the API returns an error status code.
Returns:: Response containing records and pagination metadata.
Return type:: MetaApiResponse[Folder]

async get_by_id(folder_id: int | str, **kwargs) → Folder[source]

Get a specific folder by ID.

Official documentation: documents/folders

Parameters:

folder_id (int | str) – The unique identifier.
kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

The record.

Return type:

Folder

async update(folder_id: int | str, data: Mapping[str, Any], **kwargs) → Folder[source]

Update a folder.

Official documentation: documents/folders

Parameters:

folder_id (int | str) – The unique identifier of the record to update.
data (Mapping[str, Any]) – Payload with fields to update (key-value mapping).
kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

The updated record.

Return type:

Folder