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:
- 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:
- 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:
- 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:
- 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:
- 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:
- 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:
- 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:
- 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:
- 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:
- 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:
- 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:
- 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:
- 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:
- 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:
- 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:
- 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 tofreshbooks.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:
- 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:
- 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:
- 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:
- 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:
- 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 tofreshbooks.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:
- 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:
- 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:
- 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:
- 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:
- 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 tofreshbooks.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:
- 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:
- 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:
- 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:
- 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:
- 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:
- 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:
- 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:
- Raises:
FreshBooksError – If the call is not successful.
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 tofreshbooks.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:
- 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:
- 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:
- 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:
- 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:
- 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:
- 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:
- 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.
- 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:
- Raises:
FreshBooksError – If the call is not successful.