Builders

Paginator

class freshbooks.builders.paginator.PaginateBuilder(page: int | None = None, per_page: int | None = None)

Bases: Builder

Builder for making paginated list queries.

Has two attributes, page and per_page. When a PaginateBuilder object is passed to a .list() call, the call will fetch only the per_page number of results and will fetch the results offset by page.

>>> from freshbooks import PaginateBuilder

>>> paginator = PaginateBuilder(2, 4)
>>> paginator
PaginateBuilder(page=2, per_page=4)

>>> clients = freshBooksClient.clients.list(account_id, builders=[paginator])
>>> clients.pages
PageResult(page=2, pages=3, per_page=4, total=9)
build(resource_name: str | None = None) → str

Builds the query string parameters from the PaginateBuilder.

Parameters:

resource_name – The type of resource to generate the query string for. Eg. AccountingResource, ProjectsResource

Returns:

The built query string

page(page: int | None = None) → int | None | Builder

Set the page you wish to fetch in a list call, or get the currently set the page. When setting, can be chained.

>>> paginator = PaginateBuilder(1, 3)
>>> paginator
PaginateBuilder(page=1, per_page=3)

>>> paginator.page()
1

>>> paginator.page(2).per_page(4)
>>> paginator
PaginateBuilder(page=2, per_page=4)
Parameters:

page – (Optional) The page of results to return in the API call

Returns:

The PaginateBuilder instance if a page value is provided, otherwise returns the current page value.

per_page(per_page: int | None = None) → int | None | Builder

Set the number of results you wish to fetch in a page of a list call, or get the currently set per_page. When setting, can be chained.

The page size is capped at 100.

>>> paginator = PaginateBuilder(1, 3)
>>> paginator
PaginateBuilder(page=1, per_page=3)

>>> paginator.per_page()
3

>>> paginator.per_page(4).page(2)
>>> paginator
PaginateBuilder(page=2, per_page=4)
Parameters:

per_page – (Optional) The number of results to return in each API call

Returns:

The PaginateBuilder instance if a per_page value is provided, otherwise the current per_page value.

Filters

class freshbooks.builders.filter.FilterBuilder

Bases: Builder

Builder for making filtered list queries.

Filters can be builts with the methods: equals, in_list, like, between, and boolean, date_time which can be chained together.

>>> from freshbooks import FilterBuilder

>>> f = FilterBuilder()
>>> f.like("email_like", "@freshbooks.com")
FilterBuilder(&search[email_like]=@freshbooks.com)

>>> f = FilterBuilder()
>>> f.in_list("clientids", [123, 456]).boolean("active", False)
FilterBuilder(&search[clientids][]=123&search[clientids][]=456&active=False)

>>> f = FilterBuilder()
>>> f.boolean("active", False).in_list("clientids", [123, 456])
FilterBuilder(&active=False&search[clientids][]=123&search[clientids][]=456)

>>> f = FilterBuilder()
>>> f.between("amount", 1, 10)
FilterBuilder(&search[amount_min]=1&search[amount_max]=10)

>>> f = FilterBuilder()
>>> f.between("start_date", date.today())
FilterBuilder(&search[start_date]=2020-11-21)
between(field: str, min: Any | None = None, max: Any | None = None) → Builder

Filters results where the provided field is between two values.

In general ‘between’ filters end in a _min or _max (as in amount_min or amount_max) or _date (as in start_date, end_date). If the provided field does not end in _min/_max or _date, then the appropriate _min/_max will be appended.

For date fields, you can pass the iso format 2020-10-17 or a datetime or date object, which will be converted to the proper string format.

Examples:

  • filter.between("amount", 1, 10) will yield filters &search[amount_min]=1&search[amount_max]=10

  • filter.between("amount_min", min=1) will yield filter &search[amount_min]=1

  • filter.between("amount_max", max=10) will yield filter &search[amount_max]=10

  • filter.between("start_date", "2020-10-17") will yield filter &search[start_date]=2020-10-17

  • filter.between("start_date", date(year=2020, month=10, day=17)) yields &search[start_date]=2020-10-17

Parameters:

  • field – The API response field to filter on

  • min – (Optional) The value the field should be greater than (or equal to)

  • max – (Optional) The value the field should be less than (or equal to)

Returns:

The FilterBuilder instance

boolean(field: str, value: bool) → Builder

Filters results where the field is equal to true or false.

Example: filter.boolean("active", False) will yield the filter &active=false

Parameters:

  • field – The API response field to filter on

  • value – True or False

Returns:

The FilterBuilder instance

build(resource_name: str | None = None) → str

Builds the query string parameters from the FilterBuilder.

Parameters:

resource_name – The type of resource to generate the query string for. Eg. AccountingResource, ProjectsResource

Returns:

The built query string

date_time(field: str, value: str | datetime) → Builder

Filters for entries that come before or after a particular time, as specified by the field. Eg. “updated_since” on Time Entries will return time entries updated after the provided time.

The url parameter must be in ISO 8601 format (eg. 2010-10-17T05:45:53Z)

Example:

  • filter.date_time("updated_since", "2020-10-17T13:14:07") will yield &updated_since=2020-10-17T13:14:07

Parameters:

  • field – The API response field to filter on

  • value – The datetime, or ISO 8601 format string value

Returns:

The FilterBuilder instance

equals(field: str, value: Any) → Builder

Filters results where the field is equal to the provided value.

Example: filter.equals("username", "Bob") will yield the filter &search[username]=Bob

Parameters:

  • field – The API response field to filter on

  • value – The value the field should equal

Returns:

The FilterBuilder instance

in_list(field: str, values: list) → Builder

Filters if the provided field matches a value in a list.

In general, an ‘in’ filter will be bound to the plural form of the field. Eg. userid for an equal filter, userids for a list filter.

Here we only append an ‘s’ to the field name if it doesn’t have one yet. This way we can be as forgiving as possible for developers by accepting: filter.in_list("userid", [1, 2]) or filter.in_list("userids", [1, 2]).

Of course the FreshBooks API is not 100% consistent, so there are a couple of unique cases that may not be handled.

Parameters:

  • field – The API response field to filter on

  • values – List of values the field should one of

Returns:

The FilterBuilder instance

like(field: str, value: Any) → Builder

Filters for a match contained within the field being searched. For example, “leaf” will Like-match “aleaf” and “leafy”, but not “leav”, and “leafs” would not Like-match “leaf”.

Parameters:

  • field – The API response field to filter on

  • value – The value the field should contain

Returns:

The FilterBuilder instance

Includes

class freshbooks.builders.includes.IncludesBuilder

Bases: Builder

Builder for including relationships, sub-resources, or additional data in the response.

>>> from freshbooks import IncludesBuilder

>>> includes = IncludesBuilder()
>>> includes.include("late_reminders")
IncludesBuilder(&include[]=late_reminders)
build(resource_name: str | None = None) → str

Builds the query string parameters from the IncludesBuilder.

Parameters:

resource_name – The type of resource to generate the query string for. Eg. AccountingResource, ProjectsResource

Returns:

The built query string

include(key: str) → Builder

Add an include key to the builder.

Example: includes.include("late_reminders") will yield the filter &include[]=late_reminders

Parameters:

key – The key for the resource or data to include

Returns:

The IncludesBuilder instance

Sort

class freshbooks.builders.sort.SortBuilder

Bases: Builder

Builder for including sort by field data in a list request.

>>> from freshbooks import SortBuilder

>>> sort = SortBuilder()
>>> sort.ascending("invoice_date")
SortBuilder(&sort=invoice_date_asc)
asc(key: str) → Builder

Alias for .ascending()

ascending(key: str) → Builder

Add a sort by the field in ascending order.

Parameters:

key – The field for the resource list to be sorted by

build(resource_name: str | None = None) → str

Builds the query string parameter from the SortBuilder.

Parameters:

resource_name – The type of resource to generate the query string for. Eg. AccountingResource, ProjectsResource

Returns:

The built query string

desc(key: str) → Builder

Alias for .descending()

descending(key: str) → Builder

Add a sort by the field in descending order.

Parameters:

key – The field for the resource list to be sorted by