Noko Projects

The NokoClient offers multiple methods to interact with projects in Noko. On methods where keyword arguments are supported, parameter validation happens through Pydantic, allowing Python types other than what’s supported by the Noko API to be used when making requests, and providing a validation layer before the request is even made to the API.

class noko_client.client.NokoClient(access_token: str)

Simple Client for the Noko API.

Provide a friendlier interface to interact with the Noko API. Where Noko expects parameters to be passed in a specific way (for example, a list of strings for IDs, provide support for multiple types and handle formatting and validation.

This client does not currently support oAuth.

access_token

The Noko access token to authenticate the requests.

Type:

str

archive_projects(project_ids: list[int | str]) → None

Archive multiple projects.

If any projects in the list cannot be archived, they will be ignored and will not affect the response.

Parameters:

project_ids (list[str | int]) – The list of IDs of the projects to archive.

Returns:

Doesn’t return anything, if unsuccessful, will raise an exception.

Return type:

(None)

archive_single_project(project_id: str | int) → None

Archive a single project.

A project cannot be deleted if there are no entries, invoices or expenses associated with it. Consider deleting the project instead.

Parameters:

project_id (str | int) – The ID of the project to archive.

Returns:

Doesn’t return anything, if unsuccessful, will raise an exception.

Return type:

(None)

create_project(**kwargs) → list[dict]

Create new project in Noko.

Keyword Arguments:

  • name (str) – The name of the project to create.

  • billable (bool | None) – Whether the project is billable or unabillable. Defaults to True.

  • project_group_id (str | int | None) – The ID of the project group the project will be associated with. Defaults to None.

  • billing_increment (int | None) – The billing increment to use for the project. The default amount will be the account’s default billing increment (which is 15). Accepted values: 1, 5, 6, 10, 15, 20, 30, 60

  • color (str | None) – A hexadecimal color code to use as the project’s color.

Returns:

The project created with the provided information as a dictionary.

Return type:

(list[dict])

delete_projects(project_ids: list[int | str]) → None

Delete multiple projects.

If any projects in the list cannot be deleted, they will be ignored and will not affect the response.

Parameters:

project_ids (list[str | int]) – The list of IDs of the projects to delete.

Returns:

Doesn’t return anything, if unsuccessful, will raise an exception.

Return type:

(None)

delete_single_project(project_id: str | int) → None

Delete a single project.

A project cannot be deleted if there are entries, invoices or expenses associated with it. Consider archiving the project instead.

Parameters:

project_id (str | int) – The ID of the project to delete.

Returns:

Doesn’t return anything, if unsuccessful, will raise an exception.

Return type:

(None)

edit_project(project_id: str | int, **kwargs) → list[dict]

Edit an existing project.

Parameters:

project_id (int | str) – The ID of the project to edit.

Keyword Arguments:

  • name (str | None) – Name of the project. If not provided, date will not be changed.

  • project_group_id (str | int | None) – The ID of the project group the project will be associated with.

  • billing_increment (int | None) – Billing increment to be used by the project.

  • color (str | None) – The hexadecimal string representing a color to associate with the project.

Returns:

The edited project with the provided information as a dictionary.

Return type:

(list[dict])

get_all_entries_for_project(project_id: str | int, **kwargs) → list[dict]

Retrieve all time entries associated with a project.

Results can be filtered using the same keyword arguments as the ones used for the list entries endpoint. All keyword arguments are optional.

Parameters:

project_id (str | int) – The ID of the project to retrieve entries for.

Keyword Arguments:

  • user_ids (str | list | None) – IDs of users to filter. If provided as a string, must be comma separated. If provided as a list, can be provided as a list of integers or strings. Defaults to None.

  • description (str | None) – Only descriptions containing the provided text will be returned. Defaults to None.

  • project_ids (str | list | None) – IDs of projects to filter for. If provided as a string, must be comma separated. If provided as a list, can be provided as a list of integers or strings. Defaults to None.

  • tag_ids (str | list | None) – IDs of users to filter for. If provided as a string, must be comma separated. If provided as a list, can be provided as a list of integers or strings. Defaults to None.

  • tag_filter_type (str | None) – The type of filter to apply if filtering for tag_ids. Defaults to None.

  • from (str | datetime | None) – The date from which to search. Only entries logged on this day onwards will be returned. If provided as string, must be in ISO 8601 format (YYYY-MM-DD).

  • to (str | datetime | None) – The date up to which to search. Only entries logged up to this day will be returned. If provided as string, must be in ISO 8601 format (YYYY-MM-DD).

  • invoiced (bool | str | None) – Whether to filter for invoiced or uninvoiced entries. If provided as string, must be lower case. Defaults to None.

  • updated_from (str | datetime | None) – Only entries with updates from this timestamp onwards are returned. If provided as string, must be in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ). Defaults to None.

  • updated_to (str | datetime | None) – Only entries with updates up to this timestamp are returned. If provided as string, must be in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ). Defaults to None.

  • billable (bool | str | None) – Whether to filter for billable or unbillable entries. If provided as string, must be lower case. Defaults to None.

  • approved_at_from (str | datetime | None) – Only entries with approvals from this date on will be returned. If provided as string, must be in ISO 8601 format (YYYY-MM-DD). Defaults to None.

  • approved_at_to (str | datetime | None) – Only entries with approvals up to this date will be returned. If provided as string, must be in ISO 8601 format (YYYY-MM-DD). Defaults to None.

Returns:

A list of all retrieved entries meeting the specified criteria.

Return type:

(list[dict])

get_expenses_for_project(project_id: str | int, **kwargs) → list[dict]

Get all expenses associated with a project.

Results can be filtered using the same keyword arguments as the ones used for the list expenses endpoint. All keyword arguments are optional.

Parameters:

project_id (str | int) – The ID of the project to retrieve expenses for.

Keyword Arguments:

  • user_ids (str | list | None) – The IDs of the users to filter expenses by. If provided as string, must be a comma separated string. Defaults to None.

  • description (str | None) – Only expenses containing this text in their description are returned.

  • project_ids (str | list | None) – The IDs of the projects to filter expenses by. If provided as string, must be a comma separated string. Defaults to None.

  • invoice_ids (str | list | None) – The IDs of the invoices to filter expenses by. If provided as string, must be a comma separated string. Defaults to None.

  • from (str | datetime | None) – Only expenses from or after this date will be returned. If provided as string, must be in ISO 8601 format (YYY-MM-DD). Defaults to None.

  • to (str | datetime | None) – Only expenses on or before this date will be returned. If provided as string, must be in ISO 8601 format (YYY-MM-DD). Defaults to None.

  • price_from (int | float | None) – Only expenses with a price grater than or equal to this will be returned. Defaults to None.

  • price_to (int | float | None) – Only expenses with a price less than or equal to this will be returned. Defaults to None.

  • taxable (bool | str | None) – Return only expenses where taxes are applied or not applied. Defaults to both.

  • invoiced (bool | str | None) – Return only invoiced or uninvoiced expenses. Defaults to both.

Returns:

A list of all retrieved expenses meeting the specified criteria.

Return type:

(list[dict])

get_single_project(project_id: str | int) → list[dict]

Retrieve a single project based on the project ID.

Parameters:

project_id (str | int) – the ID of the entry to retrieve.

Returns:

The retrieved project as a dictionary.

Return type:

(list[dict])

list_projects(**kwargs) → list[dict]

List all projects from Noko.

By default, retrieves all projects. Projects to retrieve can be filtered based on accepted Keyword Arguments.

Keyword Arguments:

  • name (str | None) – Only projects containing this string in the name are returned. Defaults to None.

  • project_group_ids (str | list | None) – Only projects belonging to the group IDs provided are returned. Accepts a comma separated string of IDs or a list of IDs. Defaults to None.

  • billing_increment (int | None) – Only projects with the specified billing increment are returned. Accepted values: 1, 5, 6, 10, 15, 20, 30, 60. Defaults to None.

  • enabled (bool | None) – Return only active or inactive projects. Defaults to None.

  • billable (bool | None) – Return only billable or unbillable projects. Defaults to None.

Returns:

A list of retrieved projects.

Return type:

(list[dict])

merge_project_into_this_project(project_id: str | int, project_to_merge_id: str | int) → None

Merge a project into another one.

When one project is merged into another, the entries, expenses and invoices associated with the project are associated with the new tag, and the merged project will be deleted once the merge has completed. This action is permanent, so you cannot undo after you merge projects. A merge cannot be performed if either project is archived.

Parameters:

  • project_id (str | int) – The ID of the project to keep. This is the project the other project will be merged into.

  • project_to_merge_id (str | int) – The ID of the project to merge. This is the project that will be merged

  • one. (into the other) –

Returns:

Doesn’t return anything, if unsuccessful, will raise an exception.

Return type:

(None)

unarchive_projects(project_ids: list[int | str]) → None

Unarchive multiple projects.

If any projects in the list cannot be unarchived, they will be ignored and will not affect the response.

Parameters:

project_ids (list[str | int]) – The list of IDs of the projects to unarchive.

Returns:

Doesn’t return anything, if unsuccessful, will raise an exception.

Return type:

(None)

unarchive_single_project(project_id: str | int) → None

Unarchive a single project.

Turn an archived project active.

Parameters:

project_id (str | int) – The ID of the archived project to unarchive.

Returns:

Doesn’t return anything, if unsuccessful, will raise an exception.

Return type:

(None)