Noko Users

The NokoClient offers multiple methods to interact with users 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

create_user(**kwargs) → list[dict]

Create a new Noko user.

If your account has per-user billing, adding a new user will affect the total of your next invoice.

Keyword Arguments:

  • email (str) – The email address of the user to create.

  • first_name (str | None) – The first name of the user to create. Defaults to None.

  • last_name (str | None) – The first name of the user to create. Defaults to None.

  • role (str | None) – The user’s role in Noko. Defaulta to leader. Accepted values are: supervisor, leader, coworker, contractor

Returns:

The created user’s information as a dictionary.

Return type:

(list[dict])

deactivate_user(user_id: str | int) → None

Deactivate a user from Noko.

The account owner cannot be deactivated, and the authenticated user cannot deactivate themselves. If the user does not have entries associated with themselves, they can also not be deactivated and should be deleted instead.

Parameters:

user_id (str | int) – The ID of the user to deactivate.

Returns:

Does not return anything, if unsuccessful, will raise an exception.

Return type:

(None)

delete_user(user_id: str | int) → None

Delete a user from Noko.

A user cannot be deleted if there are any entries associated with them. You can deactivate the user, which will remove this user from the list of active users and increment the number of users available until the account limit is reached.

The account user also cannot be deleted, and the authenticate user cannot delete themselves.

Parameters:

user_id (str | int) – The ID of the user to delete.

Returns:

Does not return anything, if unsuccessful, will raise an exception.

Return type:

(None)

edit_user(user_id: str | int, **kwargs) → list[dict]

Edit a Noko user’s details.

Parameters:

user_id (str | int) – The ID of the user to edit.

Keyword Arguments:

  • first_name (str | None) – The first name of the user to create. Defaults to None.

  • last_name (str | None) – The first name of the user to create. Defaults to None.

  • role (str | None) – The user’s role in Noko. Defaulta to None. Accepted values are: supervisor, leader, coworker, contractor

Returns:

The edited user’s information as a dictionary.

Return type:

(list[dict])

get_single_user(user_id: int | str) → list[dict]

Retrieve a single user from Noko.

Parameters:

user_id (str | int) – The ID of the user to retrieve.

Returns:

The retrieved user’s information as a dictionary.

Return type:

(list[dict])

get_user_entries(user_id: int | str, **kwargs) → list[dict]

Get all entries associated with a user.

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

Parameters:

user_id (str | int) – The ID of the user 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_user_expenses(user_id: str | int, **kwargs) → list[dict]

Retrieve all expenses associated with a user.

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

Parameters:

user_id (str | int) – The ID of the user 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])

give_user_access_to_projects(user_id: str | int, project_ids: list[str | int]) → None

Give a Noko user access to a set of projects.

If the user is deactivated, access cannot be granted and the action will fail. The authenticated user cannot change their own access rules.

Parameters:

  • user_id (str | int) – The ID of the user to grant access to.

  • project_ids (list[str | int]) – The IDs of the projects to grant the user access to.

Returns:

Does not return anything, if unsuccessful, will raise an exception.

Return type:

(None)

list_users(**kwargs) → list[dict]

List all Noko users in the account.

Keyword Arguments:

  • name (str | None) – Only users with this string in their name are returned. Defaults to None.

  • email (str | None) – Only users with this string in their email address are returned. Defaults to None.

  • role (str | None) – Only users with this role will be returned. Defaults to all. Accepted values are: supervisor, leader, coworker, contractor

  • state (str | None) – Only users in this state will be returned. Defaults to all. Accepted values are: disabled, pending, active, suspended

Returns:

A list of all users matching the specified criteria.

Return type:

(list[dict])

reactivate_user(user_id: str | int) → None

Reactivate a deactivated Noko user.

If your account has per-user billing, this action will affect your next invoice’s total.

If the user is not deactivated, the action will fail. Similarly, if the maximum number of users in the account has been reached, the action will fail.

Parameters:

user_id (str | int) – The ID of the deactivated user to reactivate.

Returns:

Does not return anything, if unsuccessful, will raise an exception.

Return type:

(None)

revoke_user_access_to_all_projects(user_id: str | int) → None

Revoke a user’s access to all projects.

Cannot revoke access from deactivated users or users that can access all projects. The authenticated user cannot change their own access rules.

Parameters:

user_id (str | int) – The ID of the user to revoke all access.

Returns:

Does not return anything, if unsuccessful, will raise an exception.

Return type:

(None)

revoke_user_access_to_projects(user_id: str | int, project_ids: list[str | int]) → None

Revoke a user’s access to projects.

Revoking a User’s access to a project prevents them from viewing the entries and expenses for the project. The user’s entries and expenses logged for the project are not deleted. Any projects that the user does not have access to are ignored.

Cannot remove access from a deactivated user or a user that already has access to all projects. The authenticated user cannot change their own access rules.

Any projects in the list the user does not have access to will be ignored and will not affect the response.

Parameters:

  • user_id (str | int) – The ID of the user to revoke access from.

  • project_ids (list[str | int]) – The IDs of the projects to remove the user’s access from.

Returns:

Does not return anything, if unsuccessful, will raise an exception.

Return type:

(None)