Primary Modules

This section provides details around the primary modules used in the freshpy package, which are listed below.


Init Module (freshpy)

The Init Module is covered on this page.


Core Module (freshpy.core)

The Core Module is covered on this page.


API Module (freshpy.api)

This module handles interactions with the Freshservice API.

Module:

freshpy.api

Synopsis:

This module handles interactions with the Freshservice REST API

Created By:

Jeff Shurtliff

Last Modified:

Jeff Shurtliff

Modified Date:

02 Jan 2026

freshpy.api.api_call_with_payload(freshpy_object, method, uri, payload, params=None, headers=None, timeout=30, show_full_error=True, return_json=True, verify_ssl=True)[source]

This method performs an API call (POST, PUT, or PATCH) that includes a JSON-formatted payload.

Added in version 3.0.0.

Parameters:

  • freshpy_object (class[freshpy.FreshPy]) – The core freshpy.FreshPy object

  • method (str) – The API method (post, put, or patch)

  • uri (str) – The API endpoint to query

  • payload (dict) – The payload to leverage in the API call

  • params (dict, None) – The query parameters (where applicable)

  • headers (dict, None) – Specific API headers to use when performing the API call

  • timeout (int, str, None) – The timeout period in seconds (defaults to 30)

  • show_full_error (bool) – Determines if the full error message should be displayed (True by default)

  • return_json – Determines if the response should be returned in JSON format (True by default)

  • verify_ssl (bool) – Determines if SSL verification should occur (True by default)

Returns:

The API response in JSON format or as a requests response object

Raises:

freshpy.errors.exceptions.DELETERequestError, freshpy.errors.exceptions.PATCHRequestError, freshpy.errors.exceptions.POSTRequestError, freshpy.errors.exceptions.PUTRequestError, freshpy.errors.exceptions.APIRequestError, freshpy.errors.exceptions.APIConnectionError

freshpy.api.define_auth(api_key)[source]

This function defines the authentication dictionary to use in API calls.

Added in version 1.0.0.

Returns:

Tuple in the appropriate format to be used as API credentials

freshpy.api.define_headers()[source]

This function defines the headers to use in API calls.

Added in version 1.0.0.

Returns:

Dictionary defining the minimum required header keys and values for API calls

freshpy.api.get_request_with_retries(freshpy_object, uri, headers=None, params=None, return_json=True, timeout=30, verify_ssl=True)[source]

This function performs a GET request and will retry several times if a failure occurs.

Changed in version 3.0.0: Several improvements were introduced to promote scalability and reliability with GET requests.

Added in version 1.0.0.

Parameters:

  • freshpy_object (class[freshpy.FreshPy]) – The core freshpy.FreshPy object

  • uri (string) – The URI to query

  • headers (dict, None) – The HTTP headers to utilize in the REST API call

  • params (dict, None) – The query parameters (where applicable)

  • return_json (bool) – Determines if JSON data should be returned

  • timeout (int, str, None) – The timeout period in seconds (defaults to 30)

  • verify_ssl (bool) – Determines if SSL verification should occur (True by default)

Returns:

The JSON data from the response or the raw requests response.

Raises:

freshpy.errors.exceptions.APIConnectionError, freshpy.errors.exceptions.GETRequestError, freshpy.errors.exceptions.APIRequestError

Return to Top


Agents Module (freshpy.agents)

This module handles interactions with Freshservice agents.

Module:

freshpy.agents

Synopsis:

Functions for interacting with Freshservice agents

Created By:

Jeff Shurtliff

Last Modified:

Jeff Shurtliff

Modified Date:

02 Jan 2026

freshpy.agents.get_agent_group(freshpy_object, group_id, verify_ssl=True)[source]

This function returns data for a specific agent group.

Added in version 3.0.0.

Parameters:

  • freshpy_object (class[freshpy.FreshPy]) – The core freshpy.FreshPy object

  • group_id (str, int) – The numeric ID of the agent group

  • verify_ssl (bool) – Determines if SSL verification should occur (True by default)

Returns:

A JSON-formatted dictionary with the agent group data

Raises:

freshpy.errors.exceptions.APIConnectionError, freshpy.errors.exceptions.GETRequestError, freshpy.errors.exceptions.APIRequestError

freshpy.agents.get_agent_id(freshpy_object, email, verify_ssl=True)[source]

This function retrieves the Agent ID value for a specific agent.

Added in version 2.0.0.

Parameters:

  • freshpy_object (class[freshpy.FreshPy]) – The core freshpy.FreshPy object

  • email (str) – The email address of the agent

  • verify_ssl (bool) – Determines if SSL verification should occur (True by default)

Returns:

The Agent ID of the agent as an integer

Raises:

freshpy.errors.exceptions.APIConnectionError, freshpy.errors.exceptions.GETRequestError, freshpy.errors.exceptions.APIRequestError, freshpy.errors.exceptions.NotFoundResponseError, freshpy.errors.exceptions.InvalidFieldError

freshpy.agents.get_agent_role(freshpy_object, role_id, verify_ssl=True)[source]

This function returns data for a specific agent role.

Added in version 3.0.0.

Parameters:

  • freshpy_object (class[freshpy.FreshPy]) – The core freshpy.FreshPy object

  • role_id (str, int) – The numeric ID of the agent role

  • verify_ssl (bool) – Determines if SSL verification should occur (True by default)

Returns:

A JSON-formatted dictionary with the agent role data

Raises:

freshpy.errors.exceptions.APIConnectionError, freshpy.errors.exceptions.GETRequestError, freshpy.errors.exceptions.APIRequestError

freshpy.agents.get_all_agent_groups(freshpy_object, verify_ssl=True)[source]

This function returns data for all agent groups.

Added in version 3.0.0.

Parameters:
Returns:

A JSON-formatted dictionary with the agent group data

Raises:

freshpy.errors.exceptions.APIConnectionError, freshpy.errors.exceptions.GETRequestError, freshpy.errors.exceptions.APIRequestError

freshpy.agents.get_all_agent_roles(freshpy_object, verify_ssl=True)[source]

This function returns data for all agent roles.

Added in version 3.0.0.

Parameters:
Returns:

A JSON-formatted dictionary with the agent role data

Raises:

freshpy.errors.exceptions.APIConnectionError, freshpy.errors.exceptions.GETRequestError, freshpy.errors.exceptions.APIRequestError

freshpy.agents.get_all_agents(freshpy_object, only_active=None, only_inactive=None, verify_ssl=True)[source]

This function returns data for all agents with an optional filters for active or inactive users.

Added in version 2.0.0.

Parameters:

  • freshpy_object (class[freshpy.FreshPy]) – The core freshpy.FreshPy object

  • only_active (bool, None) – Filters for only active agents when True

  • only_inactive (bool, None) – Filters for only inactive agents when True

  • verify_ssl (bool) – Determines if SSL verification should occur (True by default)

Returns:

JSON data with user data for all agents

Raises:

freshpy.errors.exceptions.APIConnectionError, freshpy.errors.exceptions.GETRequestError, freshpy.errors.exceptions.APIRequestError

freshpy.agents.get_assignment_history(freshpy_object, lookup_value, verify_ssl=True)[source]

This function retrieves the user assignment history for a specific agent.

Added in version 2.0.0.

Parameters:

  • freshpy_object (class[freshpy.FreshPy]) – The core freshpy.FreshPy object

  • lookup_value – An Agent ID or email address with which to look up the user

  • verify_ssl (bool) – Determines if SSL verification should occur (True by default)

Tyype lookup_value:

str, int

Returns:

JSON data for the assignment history for the agent

Raises:

freshpy.errors.exceptions.APIConnectionError, freshpy.errors.exceptions.GETRequestError, freshpy.errors.exceptions.APIRequestError, freshpy.errors.exceptions.NotFoundResponseError, freshpy.errors.exceptions.InvalidFieldError

freshpy.agents.get_user_info(freshpy_object, lookup_value, verify_ssl=True)[source]

This function retrieves user data for a specific agent.

Added in version 2.0.0.

Parameters:

  • freshpy_object (class[freshpy.FreshPy]) – The core freshpy.FreshPy object

  • lookup_value – An Agent ID or email address with which to look up the user

  • verify_ssl (bool) – Determines if SSL verification should occur (True by default)

Tyype lookup_value:

str, int

Returns:

JSON data with the agent user data

Raises:

freshpy.errors.exceptions.APIConnectionError, freshpy.errors.exceptions.GETRequestError, freshpy.errors.exceptions.APIRequestError, freshpy.errors.exceptions.InvalidFieldError

Return to Top


Tickets Module (freshpy.tickets)

This module handles interactions with Freshservice tickets.

Module:

freshpy.tickets

Synopsis:

Functions for interacting with Freshservice tickets

Created By:

Jeff Shurtliff

Last Modified:

Jeff Shurtliff

Modified Date:

05 Jan 2026

freshpy.tickets.get_ticket(freshpy_object, ticket_number, include=None, verify_ssl=True)[source]

This function returns the data for a specific ticket.

Changed in version 3.0.0: The ticket number is now validated before being used in the API call.

Changed in version 1.1.0: Added the ability to disable SSL verification on API calls.

Added in version 1.0.0.

Parameters:
Returns:

JSON data for the given ticket

Raises:

freshpy.errors.exceptions.APIConnectionError, freshpy.errors.exceptions.GETRequestError, freshpy.errors.exceptions.APIRequestError

freshpy.tickets.get_ticket_field(freshpy_object, field_id=None, field_label=None, field_name=None, match_case=True, ticket_data=None, workspace_id=None, verify_ssl=True)[source]

This function retrieves a specific ticket field based on a provided ID, Label, and/or Name.

Added in version 3.0.0.

Parameters:

  • freshpy_object (class[freshpy.FreshPy]) – The core freshpy.FreshPy object

  • field_id (int, str, None) – The id value for the field

  • field_label (str, None) – The label value for the field

  • field_name (str, None) – The name value for the field

  • match_case (bool) – Determines if the label value should be case-sensitive (True by default)

  • ticket_data (dict, list, None) – Dictionary or list containing all ticket field data (optional)

  • workspace_id (str, int, None) – The ID of a specific workspace (defaults to primary workspace if not specified)

  • verify_ssl (bool) – Determines if SSL verification should occur (True by default)

Returns:

A JSON-formatted dictionary with the field data (or an empty dictionary if the field is not found)

Raises:

freshpy.errors.exceptions.InvalidPredefinedFilterError, freshpy.errors.exceptions.APIConnectionError, freshpy.errors.exceptions.GETRequestError, freshpy.errors.exceptions.APIRequestError

freshpy.tickets.get_ticket_fields(freshpy_object, workspace_id=None, verify_ssl=True)[source]

This function retrieves the standard and custom fields that exist for tickets.

Added in version 3.0.0.

Parameters:

  • freshpy_object (class[freshpy.FreshPy]) – The core freshpy.FreshPy object

  • workspace_id (str, int, None) – The ID of a specific workspace (defaults to primary workspace if not specified)

  • verify_ssl (bool) – Determines if SSL verification should occur (True by default)

Returns:

Dictionary (JSON) with the ticket field data

Raises:

freshpy.errors.exceptions.APIConnectionError, freshpy.errors.exceptions.GETRequestError, freshpy.errors.exceptions.APIRequestError

freshpy.tickets.get_tickets(freshpy_object, include=None, predefined_filter=None, filters=None, filter_logic='AND', requester_id=None, requester_email=None, ticket_type=None, updated_since=None, ascending=None, descending=None, per_page=None, page=None, verify_ssl=True)[source]

This function returns a sequence of tickets with optional filters.

Changed in version 1.1.0: Added the ability to disable SSL verification on API calls.

Added in version 1.0.0.

Parameters:

  • freshpy_object (class[freshpy.FreshPy]) – The core freshpy.FreshPy object

  • include (str, tuple, list, set, None) –

    A string or iterable of embedding options

  • predefined_filter (str, None) – One of the predefined filters (‘new_and_my_open’, ‘watching’, ‘spam’, ‘deleted’)

  • filters (str, dict, None) – Query filter(s) in the form of a structured query string or a dictionary of values

  • filter_logic – Defines the logic to use as necessary in a filter query string (default is AND)

  • requester_id (str, int, None) – The numeric ID of a requester

  • requester_email (str, None) – The email address of a requester

  • ticket_type (str, None) – The type of ticket (e.g. Incident, Service Request, etc.)

  • updated_since (str, None) – A date or timestamp (in UTC format) to be a threshold for when the ticket was last updated

  • ascending (bool, None) – Determines if the tickets should be sorted in ascending order

  • descending (bool, None) – Determines if the tickets should be sorted in descending order (default)

  • per_page (str, int, None) – Displays a certain number of results per query

  • page (str, int, None) – Returns a specific page number (used for paginated results)

  • verify_ssl (bool) – Determines if SSL verification should occur (True by default)

Returns:

A list of JSON objects for tickets

Raises:

freshpy.errors.exceptions.InvalidPredefinedFilterError, freshpy.errors.exceptions.APIConnectionError, freshpy.errors.exceptions.GETRequestError, freshpy.errors.exceptions.APIRequestError

Return to Top