Resources

Accounting

class freshbooks.api.accounting.AccountingResource(client_config: SimpleNamespace, accounting_path: str, single_name: str, list_name: str, delete_via_update: bool = True, missing_endpoints: List[str] | None = None)

Handles resources under the /accounting/account/ endpoints.

API_RETRIES = 3: Default number of retries

create(account_id: str, data: dict, includes: IncludesBuilder | None = None) → Result

Create a resource.

Parameters:

account_id – The alpha-numeric account id
data – Dictionary of data to populate the resource
builders – (Optional) IncludesBuilder object for including additional data, sub-resources, etc.

Returns:

Result object with the new resource’s response data.

Return type:

Result

Raises:

FreshBooksError – If the call is not successful.

delete(account_id: str, resource_id: int) → Result

Delete a resource.

Note: Most FreshBooks resources are soft-deleted, See FreshBooks API - Active and Deleted Objects

Parameters:

account_id – The alpha-numeric account id
resource_id – Id of the resource to delete

Returns:

An empty Result object.

Return type:

Result

Raises:

FreshBooksError – If the call is not successful.

get(account_id: str, resource_id: int, includes: IncludesBuilder | None = None) → Result

Get a single resource with the corresponding id.

Parameters:

account_id – The alpha-numeric account id
resource_id – Id of the resource to return
includes – (Optional) IncludesBuilder object for including additional data, sub-resources, etc.

Returns:

Result object with the resource’s response data.

Return type:

Result

Raises:

FreshBooksError – If the call is not successful.

headers(method: str, has_data: bool) → Dict[str, str]: Get headers required for API calls

list(account_id: str, builders: List[Builder] | None = None) → ListResult

Get a list of resources.

Parameters:

account_id – The alpha-numeric account id
builders – (Optional) List of builder objects for filters, pagination, etc.

Returns:

ListResult object with the resources response data.

Return type:

ListResult

Raises:

FreshBooksError – If the call is not successful.

update(account_id: str, resource_id: int, data: dict, includes: IncludesBuilder | None = None) → Result

Update a resource.

Parameters:

account_id – The alpha-numeric account id
resource_id – Id of the resource to update
data – Dictionary of data to update the resource to
builders – (Optional) IncludesBuilder object for including additional data, sub-resources, etc.

Returns:

Result object with the updated resource’s response data.

Return type:

Result

Raises:

FreshBooksError – If the call is not successful.

class freshbooks.api.accounting_business.AccountingBusinessResource(client_config: SimpleNamespace, path: str, resource_name: str, missing_endpoints: List[str] | None = None)

Handles resources under the /accounting/businesses/ endpoints.

API_RETRIES = 3: Default number of retries

create(business_uuid: str, data: dict) → Result

Create a resource.

Parameters:

business_uuid – The business uuid
data – Dictionary of data to populate the resource

Returns:

Result object with the new resource’s response data.

Return type:

Result

Raises:

FreshBooksError – If the call is not successful.

delete(business_uuid: str, resource_uuid: str) → Result

Delete a resource.

Note: Most FreshBooks resources are soft-deleted, See FreshBooks API - Active and Deleted Objects

Parameters:

business_uuid – The business uuid
resource_uuid – Id of the resource to return

Returns:

An empty Result object.

Return type:

Result

Raises:

FreshBooksError – If the call is not successful.

get(business_uuid: str, resource_uuid: str) → Result

Get a single resource with the corresponding id.

Parameters:

business_uuid – The business uuid
resource_uuid – Id of the resource to return

Returns:

Result object with the resource’s response data.

Return type:

Result

Raises:

FreshBooksError – If the call is not successful.

headers(method: str, has_data: bool) → Dict[str, str]: Get headers required for API calls

list(business_uuid: str) → ListResult

Get a list of resources.

Parameters:: business_uuid – The business uuid
Returns:: ListResult object with the resources response data.
Return type:: ListResult
Raises:: FreshBooksError – If the call is not successful.

update(business_uuid: str, resource_uuid: str, data: dict) → Result

Update a resource.

Parameters:

business_uuid – The business uuid
resource_uuid – Id of the resource to return
data – Dictionary of data to update the resource to

Returns:

Result object with the updated resource’s response data.

Return type:

Result

Raises:

FreshBooksError – If the call is not successful.

Auth

class freshbooks.api.auth.AuthResource(client_config: SimpleNamespace)

Handles resources under the /auth endpoints.

API_RETRIES = 3: Default number of retries

headers(method: str, has_data: bool) → Dict[str, str]: Get headers required for API calls

me_endpoint() → Identity

Get the identity details of the currently authenticated user.

See FreshBooks API - Business, Roles, and Identity

Returns:: Result object with the authenticated user’s identity and business details.
Return type:: Result
Raises:: FreshBooksError – If the call is not successful.

Projects

class freshbooks.api.projects.ProjectsResource(client_config: SimpleNamespace, list_resource_path: str, single_resource_path: str, list_name: str | None = None, single_name: str | None = None, missing_endpoints: List[str] | None = None)

Bases: ProjectsBaseResource

Handles resources under the /projects endpoints.

create(business_id: int, data: dict) → Result

Create a resource.

Parameters:

business_id – The business id
data – Dictionary of data to populate the resource

Returns:

Result object with the new resource’s response data.

Return type:

Result

Raises:

FreshBooksError – If the call is not successful.

delete(business_id: int, resource_id: int) → Result

Delete a resource.

Note: Most FreshBooks resources are soft-deleted, See FreshBooks API - Active and Deleted Objects

Parameters:

business_id – The business id
resource_id – Id of the resource to delete

Returns:

An empty Result object.

Return type:

Result

Raises:

FreshBooksError – If the call is not successful.

get(business_id: int, resource_id: int, includes: IncludesBuilder | None = None) → Result

Get a single resource with the corresponding id.

Parameters:

business_id – The business id
resource_id – Id of the resource to return
includes – (Optional) IncludesBuilder object for including additional data, sub-resources, etc.

Returns:

Result object with the resource’s response data.

Return type:

Result

Raises:

FreshBooksError – If the call is not successful.

list(business_id: int, builders: List[Builder] | None = None) → ListResult

Get a list of resources.

Parameters:

business_id – The business id
builders – (Optional) List of builder objects for filters, pagination, etc.

Returns:

ListResult object with the resources response data.

Return type:

ListResult

Raises:

FreshBooksError – If the call is not successful.

update(business_id: int, resource_id: int, data: dict) → Result

Update a resource.

Parameters:

business_id – The business id
resource_id – Id of the resource to update
data – Dictionary of data to update the resource to

Returns:

Result object with the updated resource’s response data.

Return type:

Result

Raises:

FreshBooksError – If the call is not successful.

Comments

class freshbooks.api.comments.CommentsResource(client_config: SimpleNamespace, list_resource_path: str, single_resource_path: str, list_name: str | None = None, single_name: str | None = None, missing_endpoints: List[str] | None = None)

Bases: ProjectsResource

Handles resources under the /comments endpoints.

These are handled identically to /projects endpoints. Refer to freshbooks.api.projects.ProjectsResource.

API_RETRIES = 3: Default number of retries

create(business_id: int, data: dict) → Result

Create a resource.

Parameters:

business_id – The business id
data – Dictionary of data to populate the resource

Returns:

Result object with the new resource’s response data.

Return type:

Result

Raises:

FreshBooksError – If the call is not successful.

delete(business_id: int, resource_id: int) → Result

Delete a resource.

Note: Most FreshBooks resources are soft-deleted, See FreshBooks API - Active and Deleted Objects

Parameters:

business_id – The business id
resource_id – Id of the resource to delete

Returns:

An empty Result object.

Return type:

Result

Raises:

FreshBooksError – If the call is not successful.

get(business_id: int, resource_id: int, includes: IncludesBuilder | None = None) → Result

Get a single resource with the corresponding id.

Parameters:

business_id – The business id
resource_id – Id of the resource to return
includes – (Optional) IncludesBuilder object for including additional data, sub-resources, etc.

Returns:

Result object with the resource’s response data.

Return type:

Result

Raises:

FreshBooksError – If the call is not successful.

headers(method: str, has_data: bool) → Dict[str, str]: Get headers required for API calls

list(business_id: int, builders: List[Builder] | None = None) → ListResult

Get a list of resources.

Parameters:

business_id – The business id
builders – (Optional) List of builder objects for filters, pagination, etc.

Returns:

ListResult object with the resources response data.

Return type:

ListResult

Raises:

FreshBooksError – If the call is not successful.

update(business_id: int, resource_id: int, data: dict) → Result

Update a resource.

Parameters:

business_id – The business id
resource_id – Id of the resource to update
data – Dictionary of data to update the resource to

Returns:

Result object with the updated resource’s response data.

Return type:

Result

Raises:

FreshBooksError – If the call is not successful.

class freshbooks.api.comments.CommentsSubResource(client_config: SimpleNamespace, list_resource_path: str, single_resource_path: str, single_resource_sub_path: str | None = None, list_name: str | None = None, single_name: str | None = None, missing_endpoints: List[str] | None = None)

Bases: ProjectsBaseResource

Handles sub-resources under the /comments endpoints.

Eg. /comments/business/{business_id}/services/{service_id}/rate

These are handled similarly to /projects endpoints. Refer to freshbooks.api.projects.ProjectsResource.

API_RETRIES = 3: Default number of retries

create(business_id: int, resource_id: int, data: dict) → Result

Create a resource.

Parameters:

business_id – The business id
resource_id – Id of the parent resource to create this resource under
data – Dictionary of data to populate the resource

Returns:

Result object with the new resource’s response data.

Return type:

Result

Raises:

FreshBooksError – If the call is not successful.

delete(business_id: int, resource_id: int) → Result

Delete a resource.

Note: Most FreshBooks resources are soft-deleted, See FreshBooks API - Active and Deleted Objects

Parameters:

business_id – The business id
resource_id – Id of the resource to delete

Returns:

An empty Result object.

Return type:

Result

Raises:

FreshBooksError – If the call is not successful.

get(business_id: int, resource_id: int) → Result

Get a single resource with the corresponding id.

Parameters:

business_id – The business id
resource_id – Id of the resource to return

Returns:

Result object with the resource’s response data.

Return type:

Result

Raises:

FreshBooksError – If the call is not successful.

headers(method: str, has_data: bool) → Dict[str, str]: Get headers required for API calls

list(business_id: int, builders: List[Builder] | None = None) → ListResult

Get a list of resources.

Parameters:

business_id – The business id
builders – (Optional) List of builder objects for filters, pagination, etc.

Returns:

ListResult object with the resources response data.

Return type:

ListResult

Raises:

FreshBooksError – If the call is not successful.

update(business_id: int, resource_id: int, data: dict) → Result

Update a resource.

Parameters:

business_id – The business id
resource_id – Id of the resource to update
data – Dictionary of data to update the resource to

Returns:

Result object with the updated resource’s response data.

Return type:

Result

Raises:

FreshBooksError – If the call is not successful.

Time-Tracking

class freshbooks.api.timetracking.TimetrackingResource(client_config: SimpleNamespace, list_resource_path: str, single_resource_path: str, list_name: str | None = None, single_name: str | None = None, missing_endpoints: List[str] | None = None)

Bases: ProjectsResource

Handles resources under the /timetracking endpoints.

These are handled identically to /projects endpoints. Refer to freshbooks.api.projects.ProjectsResource.

API_RETRIES = 3: Default number of retries

create(business_id: int, data: dict) → Result

Create a resource.

Parameters:

business_id – The business id
data – Dictionary of data to populate the resource

Returns:

Result object with the new resource’s response data.

Return type:

Result

Raises:

FreshBooksError – If the call is not successful.

delete(business_id: int, resource_id: int) → Result

Delete a resource.

Note: Most FreshBooks resources are soft-deleted, See FreshBooks API - Active and Deleted Objects

Parameters:

business_id – The business id
resource_id – Id of the resource to delete

Returns:

An empty Result object.

Return type:

Result

Raises:

FreshBooksError – If the call is not successful.

get(business_id: int, resource_id: int, includes: IncludesBuilder | None = None) → Result

Get a single resource with the corresponding id.

Parameters:

business_id – The business id
resource_id – Id of the resource to return
includes – (Optional) IncludesBuilder object for including additional data, sub-resources, etc.

Returns:

Result object with the resource’s response data.

Return type:

Result

Raises:

FreshBooksError – If the call is not successful.

headers(method: str, has_data: bool) → Dict[str, str]: Get headers required for API calls

list(business_id: int, builders: List[Builder] | None = None) → ListResult

Get a list of resources.

Parameters:

business_id – The business id
builders – (Optional) List of builder objects for filters, pagination, etc.

Returns:

ListResult object with the resources response data.

Return type:

ListResult

Raises:

FreshBooksError – If the call is not successful.

update(business_id: int, resource_id: int, data: dict) → Result

Update a resource.

Parameters:

business_id – The business id
resource_id – Id of the resource to update
data – Dictionary of data to update the resource to

Returns:

Result object with the updated resource’s response data.

Return type:

Result

Raises:

FreshBooksError – If the call is not successful.

Payments

class freshbooks.api.payments.PaymentsResource(client_config: SimpleNamespace, path: str, single_name: str, sub_path: str | None = None, defaults_path: str | None = None, static_params: str | None = None, missing_endpoints: List[str] | None = None)

Handles resources under the /payments endpoints.

API_RETRIES = 3: Default number of retries

create(account_id: str, resource_id: int, data: dict) → Result

Create a resource.

Parameters:

account_id – The alpha-numeric account id
resource_id – Id of the resource to create payment details for
data – Dictionary of data to populate the resource

Returns:

Result object with the new resource’s response data.

Return type:

Result

Raises:

FreshBooksError – If the call is not successful.

defaults(account_id: str) → Result

Get the default settings for an account resource.

Parameters:: account_id – The alpha-numeric account id
Returns:: Result object with the default data.
Return type:: Result
Raises:: FreshBooksError – If the call is not successful.

get(account_id: str, resource_id: int) → Result

Get a single resource with the corresponding id.

Parameters:

account_id – The alpha-numeric account id
resource_id – Id of the resource to return payment details for

Returns:

Result object with the resource’s response data.

Return type:

Result

Raises:

FreshBooksError – If the call is not successful.

headers(method: str, has_data: bool) → Dict[str, str]: Get headers required for API calls

Events

class freshbooks.api.events.EventsResource(client_config: SimpleNamespace, accounting_path: str, single_name: str, list_name: str, delete_via_update: bool = True, missing_endpoints: List[str] | None = None)

Bases: AccountingResource

Handles resources under the /events endpoints.

These are handled almost similarly to /accounting endpoints. Refer to freshbooks.api.accounting.AccountingResource.

API_RETRIES = 3: Default number of retries

create(account_id: str, data: dict, includes: IncludesBuilder | None = None) → Result

Create a resource.

Parameters:

account_id – The alpha-numeric account id
data – Dictionary of data to populate the resource
builders – (Optional) IncludesBuilder object for including additional data, sub-resources, etc.

Returns:

Result object with the new resource’s response data.

Return type:

Result

Raises:

FreshBooksError – If the call is not successful.

delete(account_id: str, resource_id: int) → Result

Delete a resource.

Note: Most FreshBooks resources are soft-deleted, See FreshBooks API - Active and Deleted Objects

Parameters:

account_id – The alpha-numeric account id
resource_id – Id of the resource to delete

Returns:

An empty Result object.

Return type:

Result

Raises:

FreshBooksError – If the call is not successful.

get(account_id: str, resource_id: int, includes: IncludesBuilder | None = None) → Result

Get a single resource with the corresponding id.

Parameters:

account_id – The alpha-numeric account id
resource_id – Id of the resource to return
includes – (Optional) IncludesBuilder object for including additional data, sub-resources, etc.

Returns:

Result object with the resource’s response data.

Return type:

Result

Raises:

FreshBooksError – If the call is not successful.

headers(method: str, has_data: bool) → Dict[str, str]: Get headers required for API calls

list(account_id: str, builders: List[Builder] | None = None) → ListResult

Get a list of resources.

Parameters:

account_id – The alpha-numeric account id
builders – (Optional) List of builder objects for filters, pagination, etc.

Returns:

ListResult object with the resources response data.

Return type:

ListResult

Raises:

FreshBooksError – If the call is not successful.

resend_verification(account_id: str, resource_id: int) → Result

Tell FreshBooks to resend the verification webhook for the callback

Parameters:

account_id – The alpha-numeric account id
resource_id – Id of the resource to update

Returns:

Result object with the resource’s response data.

Return type:

Result

Raises:

FreshBooksError – If the call is not successful.

update(account_id: str, resource_id: int, data: dict, includes: IncludesBuilder | None = None) → Result

Update a resource.

Parameters:

account_id – The alpha-numeric account id
resource_id – Id of the resource to update
data – Dictionary of data to update the resource to
builders – (Optional) IncludesBuilder object for including additional data, sub-resources, etc.

Returns:

Result object with the updated resource’s response data.

Return type:

Result

Raises:

FreshBooksError – If the call is not successful.

verify(account_id: str, resource_id: int, verifier: str) → Result

Verify webhook callback by making a put request

Parameters:

account_id – The alpha-numeric account id
resource_id – Id of the resource to update
verifier – The string verifier received by the webhook callback URI

Returns:

Result object with the resource’s response data.

Return type:

Result

Raises:

FreshBooksError – If the call is not successful.

Uploads

class freshbooks.api.uploads.UploadsResource(client_config: SimpleNamespace, upload_path: str, single_name: str)

Bases: Resource

Handles resources under the /uploads endpoints.

API_RETRIES = 3: Default number of retries

get(jwt: str) → Response

Get an uploaded file. This returns a requests.Response object to provide flexibility in handling the data.

Requests Binary Response

Parameters:: jwt – JWT provided by FreshBooks when the file was uploaded.
Returns:: The requests Response object.
Return type:: requests.Response
Raises:: FreshBooksError – If the call is not successful.

headers(method: str, has_data: bool) → Dict[str, str]: Get headers required for API calls

upload(account_id: str, file_stream: BufferedReader | None = None, file_path: str | None = None) → Result

Upload a file to FreshBooks’ file storage. This returns a Result object with the JWT required to access the file, and in the case of an image, a link to the image itself.

The file to upload can be either a byte stream, or a path to the file itself.

Eg.

>>> uploaded = freshBooksClient.images.upload(account_id, file_path="/path/to/image.png")
>>> uploaded = freshBooksClient.images.upload(account_id, file_stream=open("/path/to/image.png", "rb")

>>> print(uploaded.jwt)
<some jwt>

>>> print(uploaded.link)
https://my.freshbooks.com/service/uploads/images/<some jwt>

Parameters:

account_id – The alpha-numeric account id
file_stream – (Optional) Byte stream of the file
file_path – (Optional) Path to the file

Returns:

Result object with the new resource’s response data.

Return type:

Result

Raises:

FreshBooksError – If the call is not successful.