Expenses

Usage

List expenses and expensables:

import asyncio
import factorialhr

async def main():
    auth = factorialhr.AccessTokenAuth("your_access_token")
    async with factorialhr.ApiClient(auth=auth) as api:
        expenses = factorialhr.ExpensesEndpoint(api)
        response = await expenses.get(params={"page": 1})
        for e in response.data():
            print(e.employee_id, e.amount, e.status)
        expensables = factorialhr.ExpensablesEndpoint(api)
        for ex in (await expensables.all()).data():
            print(ex.name, ex.expensable_type)

asyncio.run(main())

class factorialhr.Expensable(*, id: int, type: ExpensableType, company_id: int, employee_id: int, group_id: int | None = None, legal_entity_id: int | None = None, created_at: datetime, amount: int | None = None, currency: str, status: ExpenseStatus, description: str | None = None, reporter_id: int | None = None, status_updated_at: datetime, effective_on: datetime | None = None, review_request_at: datetime | None = None, paid_at: datetime | None = None, updated_at: datetime, reimbursable_amount: int | None = None, reimbursable_currency: str | None = None, reimbursement_method: ReimbursementMethod | None = None, internal_reference: str | None = None, expense_id: int | None = None, mileage_id: int | None = None, per_diem_id: int | None = None, budget_id: int | None = None, project_id: int | None = None, cost_center_ids: Sequence[int] | None = None)[source]

Model for expenses_expensable.

amount: int | None: The optional amount in cents

budget_id: int | None: The id of the budget

company_id: int: The ID of the company that owns the expensable

cost_center_ids: Sequence[int] | None: The ids of the cost centers

created_at: datetime: The date and time when the expensable was created

currency: str: The currency code in ISO 4217 format

description: str | None: The optional description of the expensable

effective_on: datetime | None: The optional date and time when the expensable was effective

employee_id: int: The ID of the employee that owns the expensable

expense_id: int | None: The optional ID of the expense that the expensable belongs to

group_id: int | None: The optional ID of the group that the expensable belongs to

id: int: Unique identifier for the expensable

internal_reference: str | None: The optional internal reference of the expensable

legal_entity_id: int | None: The optional ID of the legal entity that the expensable belongs to

mileage_id: int | None: The optional ID of the mileage that the expensable belongs to

paid_at: datetime | None: The optional date and time when the expensable was set as paid

per_diem_id: int | None: The optional ID of the per_diem that the expensable belongs to

project_id: int | None: The id of the project

reimbursable_amount: int | None: The optional reimbursable amount in cents

reimbursable_currency: str | None: The optional reimbursable currency code in ISO 4217 format

reimbursement_method: ReimbursementMethod | None: The optional reimbursement method

reporter_id: int | None: The optional ID of the employee that reported the expensable

review_request_at: datetime | None: The optional date and time when the expensable was requested for review

status: ExpenseStatus: The status of the expensable

status_updated_at: datetime: The optional date and time when the status was last updated

type: ExpensableType: Type of the expensable

updated_at: datetime: The date and time when the expensable was last updated

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

Endpoint for expenses/expensables operations.

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

Get all expensables records.

Official documentation: expenses/expensables

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[Expensable]

async bulk_set_to_paid(data: Mapping[str, Any], **kwargs) → Sequence[Expensable][source]

Bulk set expensables to paid status.

Official documentation: expenses/expensables

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:

Result.

Return type:

Sequence[Expensable]

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

Get expensables with pagination metadata.

Official documentation: expenses/expensables

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[Expensable]

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

Get a specific expensable by ID.

Official documentation: expenses/expensables

Parameters:

expensable_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:

Expensable

Model for expenses_expense.

access_token: str | None: The access token of the expense

amount: int | None: The optional amount in cents

budget_id: int | None: The id of the budget associated with this expense

card: Mapping[str, Any] | None: The card of the expense

card_payment_id: int | None: The id of the card payment

category: Mapping[str, Any] | None: The category of the expense

category_id: int | None: The id of the category

company_id: int: The id of the expense’s company

cost_center_ids: Sequence[int] | None: Array of cost center ids associated with this expense

creation_type: CreationType: How the expense was created

currency: str: The currency of the expense

description: str | None: The description of the expense

dispute_id: int | None: The id of the dispute

document_id: int | None: The id of the document

document_number: str | None: Number of the financial document associated to the expense

document_type: str | None: Type of the financial document associated to the expense

effective_on: date: The date when the expense was made

employee_id: int | None: The id of the expense’s owner

exchange_rate: float | None: The exchange rate of the payment

expenses_card_id: int | None: The id of the card

expenses_expensable_id: int | None: The id of the expensable

external_authorization_id: str | None: The id of the external authorization

files: Sequence[Any]: The files of the expense

id: int | None: The id of the expense

ledger_account_id: int | None: The id of the ledger account

merchant_name: str | None: The name of the merchant

merchant_tin: str | None: The tax identification number of the merchant

paid_at: datetime | None: The date and time when the expense was paid

payment: PaymentType | None: The payment of the expense

payment_method: str | None: The method of the payment

project_id: int | None: The id of the project associated with this expense

reference: str | None: The reference of the expense

reimbursable_amount: int | None: The optional reimbursable amount in cents

reimbursable_currency: str | None: The currency of the reimbursable amount

review_request_at: datetime | None: The date and time when the expense was reviewed

signed_document: Mapping[str, Any] | None: The signed document of the expense

status: ExpenseStatus: The status of the expense

status_updated_at: datetime: The date and time when the status was updated

subcategory: str | None: The subcategory of the expense

taxes: Sequence[Any]: The taxes of the expense

user_merchant: str | None: The user merchant of the expense

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

Endpoint for expenses/expenses operations.

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

Get all expenses records.

Official documentation: expenses/expenses

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[Expense]

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

Get expenses with pagination metadata.

Official documentation: expenses/expenses

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[Expense]

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

Get a specific expense by ID.

Official documentation: expenses/expenses

Parameters:

expense_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:

Expense

Model for expenses_mileage.

amount: int | None: The amount in cents

budget_id: int | None: The id of the budget associated with this mileage

calculated_mileage: int | None: The calculated mileage between origin and destination in decameters/10-milers

category: Mapping[str, Any] | None: The category of the mileage

category_id: int | None: The id of the category

company_id: int: Company identifier

cost_center_ids: Sequence[int] | None: Array of cost center ids associated with this mileage

currency: str: The currency code

description: str | None: The description of the mileage

destination_latitude: Mapping[str, Any] | None: The latitude of the destination of the mileage

destination_longitude: Mapping[str, Any] | None: The longitude of the destination of the mileage

effective_on: date | None: The effective date

employee_id: int | None: Employee identifier

expenses_expensable_id: int | None: Expensable identifier

files: Sequence[Any]: The files attached to the mileage

from_location: str | None: The origin location

id: int: Mileage identifier

ledger_account_id: int | None: The ledger account identifier

mileage: int | None: The mileage distance

origin_latitude: Mapping[str, Any] | None: The latitude of the origin of the mileage

origin_longitude: Mapping[str, Any] | None: The longitude of the origin of the mileage

paid_at: datetime | None: The date when paid

payment: PaymentType: The payment type

project_id: int | None: The id of the project associated with this mileage

rate: Mapping[str, Any] | None: The rate information

reimbursable_amount: int | None: The amount to be reimbursed for the mileage in cents

reimbursable_currency: str | None: The currency for the reimbursable amount

review_request_at: datetime | None: The review request date

round_trip: bool | None: Indicates if the mileage is a round trip

status: ExpenseStatus: The status of the mileage

subcategory: str | None: The subcategory of the mileage

to_location: str | None: The destination location

units: str | None: The units of measurement

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

Endpoint for expenses/mileages operations.

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

Get all mileages records.

Official documentation: expenses/mileages

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[Mileage]

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

Get mileages with pagination metadata.

Official documentation: expenses/mileages

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[Mileage]

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

Get a specific mileage by ID.

Official documentation: expenses/mileages

Parameters:

mileage_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:

Mileage

class factorialhr.PerDiem(*, id: int, employee_id: int | None = None, company_id: int, expenses_expensable_id: int | None = None, end_date: date | None = None, start_date: date | None = None, from_location: str | None = None, to: str | None = None, ledger_account_id: int | None = None, amount: int | None = None, currency: str, reimbursable_amount: int | None = None, reimbursable_currency: str | None = None, payment: PaymentType, paid_at: date | None = None, files: Sequence[Any], review_request_at: date | None = None, effective_on: date | None = None, description: str | None = None, budget_id: int | None = None, project_id: int | None = None, cost_center_ids: Sequence[int] | None = None, category: Mapping[str, Any] | None = None, subcategory: str | None = None, status: ExpenseStatus, rates: Sequence[Any])[source]

Model for expenses_per_diem.

amount: int | None: The amount of the per diem

budget_id: int | None: The id of the budget associated with this per diem

category: Mapping[str, Any] | None: The category of the per diem

company_id: int: The ID of the company the per diem is for

cost_center_ids: Sequence[int] | None: Array of cost center ids associated with this per diem

currency: str: The currency for the reimbursable amount

description: str | None: The description of the per diem

effective_on: date | None: The date the per diem is effective on

employee_id: int | None: The ID of the employee the per diem is for

end_date: date | None: The end date of the per diem

expenses_expensable_id: int | None: The ID of the expensable the per diem is for

files: Sequence[Any]: The files attached to the per diem

from_location: str | None: The location the per diem is from

id: int: The ID of the per diem

ledger_account_id: int | None: The ID of the ledger account the per diem is for

paid_at: date | None: The date the per diem was paid

payment: PaymentType: The payment method for the per diem

project_id: int | None: The id of the project associated with this per diem

rates: Sequence[Any]: The rates for the per diem

reimbursable_amount: int | None: The amount to be reimbursed by the per diem in cents

reimbursable_currency: str | None: The currency for the reimbursable amount

review_request_at: date | None: The date the per diem was requested for review

start_date: date | None: The start date of the per diem

status: ExpenseStatus: The status of the per diem

subcategory: str | None: The subcategory of the per diem

to_location: str | None: The location the per diem is to

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

Endpoint for expenses/per_diems operations.

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

Get all per diems records.

Official documentation: expenses/per_diems

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[PerDiem]

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

Get per diems with pagination metadata.

Official documentation: expenses/per_diems

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[PerDiem]

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

Get a specific per diem by ID.

Official documentation: expenses/per_diems

Parameters:

per_diem_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:

PerDiem