Resources

Accounting

class freshbooks.api.accounting.AccountingResource(client_config, accounting_path, single_name, list_name, delete_via_update=True, missing_endpoints=None)

Handles resources under the /accounting/account/ endpoints.

API_RETRIES = 3

Default number of retries

create(account_id, data, includes=None)

Create a resource.

Return type:

:sphinx_autodoc_typehints_type:\:py\:class\:\``~freshbooks.models.Result

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, resource_id)

Delete a resource.

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

Return type:

:sphinx_autodoc_typehints_type:\:py\:class\:\``~freshbooks.models.Result

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, resource_id, includes=None)

Get a single resource with the corresponding id.

Return type:

:sphinx_autodoc_typehints_type:\:py\:class\:\``~freshbooks.models.Result

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, has_data)

Get headers required for API calls

Return type:

:sphinx_autodoc_typehints_type:``:py:class:``~typing.Dict`[str, str]`

list(account_id, builders=None)

Get a list of resources.

Return type:

:sphinx_autodoc_typehints_type:\:py\:class\:\``~freshbooks.models.ListResult

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, resource_id, data, includes=None)

Update a resource.

Return type:

:sphinx_autodoc_typehints_type:\:py\:class\:\``~freshbooks.models.Result

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, path, resource_name, missing_endpoints=None)

Handles resources under the /accounting/businesses/ endpoints.

API_RETRIES = 3

Default number of retries

create(business_uuid, data)

Create a resource.

Return type:

:sphinx_autodoc_typehints_type:\:py\:class\:\``~freshbooks.models.Result

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, resource_uuid)

Delete a resource.

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

Return type:

:sphinx_autodoc_typehints_type:\:py\:class\:\``~freshbooks.models.Result

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, resource_uuid)

Get a single resource with the corresponding id.

Return type:

:sphinx_autodoc_typehints_type:\:py\:class\:\``~freshbooks.models.Result

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, has_data)

Get headers required for API calls

Return type:

:sphinx_autodoc_typehints_type:``:py:class:``~typing.Dict`[str, str]`

list(business_uuid)

Get a list of resources.

Return type:

:sphinx_autodoc_typehints_type:\:py\:class\:\``~freshbooks.models.ListResult

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, resource_uuid, data)

Update a resource.

Return type:

:sphinx_autodoc_typehints_type:\:py\:class\:\``~freshbooks.models.Result

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)

Handles resources under the /auth endpoints.

API_RETRIES = 3

Default number of retries

headers(method, has_data)

Get headers required for API calls

Return type:

:sphinx_autodoc_typehints_type:``:py:class:``~typing.Dict`[str, str]`

me_endpoint()

Get the identity details of the currently authenticated user.

See FreshBooks API - Business, Roles, and Identity

Return type:

:sphinx_autodoc_typehints_type:\:py\:class\:\``~freshbooks.models.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, list_resource_path, single_resource_path, list_name=None, single_name=None, missing_endpoints=None)

Bases: ProjectsBaseResource

Handles resources under the /projects endpoints.

create(business_id, data)

Create a resource.

Return type:

:sphinx_autodoc_typehints_type:\:py\:class\:\``~freshbooks.models.Result

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, resource_id)

Delete a resource.

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

Return type:

:sphinx_autodoc_typehints_type:\:py\:class\:\``~freshbooks.models.Result

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, resource_id, includes=None)

Get a single resource with the corresponding id.

Return type:

:sphinx_autodoc_typehints_type:\:py\:class\:\``~freshbooks.models.Result

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, builders=None)

Get a list of resources.

Return type:

:sphinx_autodoc_typehints_type:\:py\:class\:\``~freshbooks.models.ListResult

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, resource_id, data)

Update a resource.

Return type:

:sphinx_autodoc_typehints_type:\:py\:class\:\``~freshbooks.models.Result

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, list_resource_path, single_resource_path, list_name=None, single_name=None, missing_endpoints=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, data)

Create a resource.

Return type:

:sphinx_autodoc_typehints_type:\:py\:class\:\``~freshbooks.models.Result

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, resource_id)

Delete a resource.

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

Return type:

:sphinx_autodoc_typehints_type:\:py\:class\:\``~freshbooks.models.Result

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, resource_id, includes=None)

Get a single resource with the corresponding id.

Return type:

:sphinx_autodoc_typehints_type:\:py\:class\:\``~freshbooks.models.Result

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, has_data)

Get headers required for API calls

Return type:

:sphinx_autodoc_typehints_type:``:py:class:``~typing.Dict`[str, str]`

list(business_id, builders=None)

Get a list of resources.

Return type:

:sphinx_autodoc_typehints_type:\:py\:class\:\``~freshbooks.models.ListResult

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, resource_id, data)

Update a resource.

Return type:

:sphinx_autodoc_typehints_type:\:py\:class\:\``~freshbooks.models.Result

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, list_resource_path, single_resource_path, single_resource_sub_path=None, list_name=None, single_name=None, missing_endpoints=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, resource_id, data)

Create a resource.

Return type:

:sphinx_autodoc_typehints_type:\:py\:class\:\``~freshbooks.models.Result

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, resource_id)

Delete a resource.

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

Return type:

:sphinx_autodoc_typehints_type:\:py\:class\:\``~freshbooks.models.Result

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, resource_id)

Get a single resource with the corresponding id.

Return type:

:sphinx_autodoc_typehints_type:\:py\:class\:\``~freshbooks.models.Result

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, has_data)

Get headers required for API calls

Return type:

:sphinx_autodoc_typehints_type:``:py:class:``~typing.Dict`[str, str]`

list(business_id, builders=None)

Get a list of resources.

Return type:

:sphinx_autodoc_typehints_type:\:py\:class\:\``~freshbooks.models.ListResult

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, resource_id, data)

Update a resource.

Return type:

:sphinx_autodoc_typehints_type:\:py\:class\:\``~freshbooks.models.Result

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, list_resource_path, single_resource_path, list_name=None, single_name=None, missing_endpoints=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, data)

Create a resource.

Return type:

:sphinx_autodoc_typehints_type:\:py\:class\:\``~freshbooks.models.Result

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, resource_id)

Delete a resource.

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

Return type:

:sphinx_autodoc_typehints_type:\:py\:class\:\``~freshbooks.models.Result

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, resource_id, includes=None)

Get a single resource with the corresponding id.

Return type:

:sphinx_autodoc_typehints_type:\:py\:class\:\``~freshbooks.models.Result

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, has_data)

Get headers required for API calls

Return type:

:sphinx_autodoc_typehints_type:``:py:class:``~typing.Dict`[str, str]`

list(business_id, builders=None)

Get a list of resources.

Return type:

:sphinx_autodoc_typehints_type:\:py\:class\:\``~freshbooks.models.ListResult

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, resource_id, data)

Update a resource.

Return type:

:sphinx_autodoc_typehints_type:\:py\:class\:\``~freshbooks.models.Result

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, path, single_name, sub_path=None, defaults_path=None, static_params=None, missing_endpoints=None)

Handles resources under the /payments endpoints.

API_RETRIES = 3

Default number of retries

create(account_id, resource_id, data)

Create a resource.

Return type:

:sphinx_autodoc_typehints_type:\:py\:class\:\``~freshbooks.models.Result

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)

Get the default settings for an account resource.

Return type:

:sphinx_autodoc_typehints_type:\:py\:class\:\``~freshbooks.models.Result

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, resource_id)

Get a single resource with the corresponding id.

Return type:

:sphinx_autodoc_typehints_type:\:py\:class\:\``~freshbooks.models.Result

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, has_data)

Get headers required for API calls

Return type:

:sphinx_autodoc_typehints_type:``:py:class:``~typing.Dict`[str, str]`

Events

class freshbooks.api.events.EventsResource(client_config, accounting_path, single_name, list_name, delete_via_update=True, missing_endpoints=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, data, includes=None)

Create a resource.

Return type:

:sphinx_autodoc_typehints_type:\:py\:class\:\``~freshbooks.models.Result

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, resource_id)

Delete a resource.

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

Return type:

:sphinx_autodoc_typehints_type:\:py\:class\:\``~freshbooks.models.Result

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, resource_id, includes=None)

Get a single resource with the corresponding id.

Return type:

:sphinx_autodoc_typehints_type:\:py\:class\:\``~freshbooks.models.Result

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, has_data)

Get headers required for API calls

Return type:

:sphinx_autodoc_typehints_type:``:py:class:``~typing.Dict`[str, str]`

list(account_id, builders=None)

Get a list of resources.

Return type:

:sphinx_autodoc_typehints_type:\:py\:class\:\``~freshbooks.models.ListResult

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, resource_id)

Tell FreshBooks to resend the verification webhook for the callback

Return type:

:sphinx_autodoc_typehints_type:\:py\:class\:\``~freshbooks.models.Result

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, resource_id, data, includes=None)

Update a resource.

Return type:

:sphinx_autodoc_typehints_type:\:py\:class\:\``~freshbooks.models.Result

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, resource_id, verifier)

Verify webhook callback by making a put request

Return type:

:sphinx_autodoc_typehints_type:\:py\:class\:\``~freshbooks.models.Result

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, upload_path, single_name)

Bases: Resource

Handles resources under the /uploads endpoints.

API_RETRIES = 3

Default number of retries

get(jwt)

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

Requests Binary Response

Return type:

:sphinx_autodoc_typehints_type:\:py\:class\:\``~requests.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, has_data)

Get headers required for API calls

Return type:

:sphinx_autodoc_typehints_type:``:py:class:``~typing.Dict`[str, str]`

upload(account_id, file_stream=None, file_path=None)

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.

:rtype: :sphinx_autodoc_typehints_type:`\:py\:class\:\`\~freshbooks.models.Result\``

>>> 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.