{"id":13591710,"url":"https://github.com/sjkingo/python-freshdesk","last_synced_at":"2025-04-05T03:11:30.649Z","repository":{"id":25222989,"uuid":"28647308","full_name":"sjkingo/python-freshdesk","owner":"sjkingo","description":"An API for the Freshdesk helpdesk","archived":false,"fork":false,"pushed_at":"2023-12-06T12:24:32.000Z","size":193,"stargazers_count":88,"open_issues_count":19,"forks_count":67,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-03-29T02:05:04.225Z","etag":null,"topics":["freshdesk","freskdesk-api","helpdesk","python","python3"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sjkingo.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2014-12-30T22:15:02.000Z","updated_at":"2025-02-09T07:23:29.000Z","dependencies_parsed_at":"2024-01-16T22:23:33.205Z","dependency_job_id":null,"html_url":"https://github.com/sjkingo/python-freshdesk","commit_stats":{"total_commits":145,"total_committers":28,"mean_commits":5.178571428571429,"dds":0.5517241379310345,"last_synced_commit":"87ccfb3d945c5867bfa92d55aad03dc98466a2aa"},"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sjkingo%2Fpython-freshdesk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sjkingo%2Fpython-freshdesk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sjkingo%2Fpython-freshdesk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sjkingo%2Fpython-freshdesk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sjkingo","download_url":"https://codeload.github.com/sjkingo/python-freshdesk/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247280272,"owners_count":20912967,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["freshdesk","freskdesk-api","helpdesk","python","python3"],"created_at":"2024-08-01T16:01:01.001Z","updated_at":"2025-04-05T03:11:30.631Z","avatar_url":"https://github.com/sjkingo.png","language":"Python","funding_links":[],"categories":["python3"],"sub_categories":[],"readme":"# python-freshdesk\n\n[![Build Status](https://travis-ci.org/sjkingo/python-freshdesk.svg)](https://travis-ci.org/sjkingo/python-freshdesk)\n[![Coverage Status](https://img.shields.io/coveralls/sjkingo/python-freshdesk.svg)](https://coveralls.io/r/sjkingo/python-freshdesk)\n[![Latest version](https://img.shields.io/pypi/v/python-freshdesk.svg)](https://pypi.python.org/pypi/python-freshdesk)\n\nThis is a library for the [Freshdesk](http://freshdesk.com/) helpdesk system for Python 2.7 and 3.6+.\n\nIt includes the following features from the [Freshdesk v2 API](https://developers.freshdesk.com/api/):\n\n* [Tickets](http://developer.freshdesk.com/api/#tickets)\n  - [Get](http://developer.freshdesk.com/api/#view_a_ticket)\n  - [Create](http://developer.freshdesk.com/api/#create_ticket)\n  - [Update](http://developer.freshdesk.com/api/#update_ticket)\n  - [Delete](http://developer.freshdesk.com/api/#delete_a_ticket)\n  - [Create OutBound Email](http://developer.freshdesk.com/api/#create_outbound_email)\n  - [List](http://developer.freshdesk.com/api/#list_all_tickets)\n  - [Filter](https://developer.freshdesk.com/api/#filter_tickets) (from 1.2.6)\n  - [List Time Entries](https://developers.freshdesk.com/api/#list_all_ticket_timeentries) (from 1.2.4)\n  - Custom ticket fields (from 1.1.1)\n* [Ticket Fields](http://developer.freshdesk.com/api/#ticket_fields)\n    - [List](http://developer.freshdesk.com/api/#list_all_ticket_fields)\n* [Comments](http://developer.freshdesk.com/api/#conversations) (known as Conversations in Freshdesk)\n  - [List](http://developer.freshdesk.com/api/#list_all_ticket_notes)\n  - [Create note](http://developer.freshdesk.com/api/#add_note_to_a_ticket)\n  - [Create reply](http://developer.freshdesk.com/api/#reply_ticket)\n* [Groups](http://developer.freshdesk.com/api/#groups)\n  - [List](http://developer.freshdesk.com/api/#list_all_groups)\n  - [Get](http://developer.freshdesk.com/api/#view_group)\n* [Contacts](http://developer.freshdesk.com/api/#contacts)\n    - [Get](http://developer.freshdesk.com/api/#view_contact)\n    - [List](http://developer.freshdesk.com/api/#list_all_contacts)\n    - [Create](http://developer.freshdesk.com/api/#create_contact)\n    - [Update](http://developer.freshdesk.com/api/#update_contact) (from 1.2.3)\n    - [Filter](https://developers.freshdesk.com/api/#filter_contacts) (from 1.3.9)\n    - [Delete](http://developer.freshdesk.com/api/#delete_contact)\n    - [Restore](http://developer.freshdesk.com/api/#restore_contact) (from 1.2.3)\n    - [Make agent](http://developer.freshdesk.com/api/#make_agent)\n* [Company](https://developers.freshdesk.com/api/#companies)\n    - [Get](http://developer.freshdesk.com/api/#view_company)\n    - [List](http://developer.freshdesk.com/api/#list_all_companies) (from 1.2.8)\n    - [Filter](https://developers.freshdesk.com/api/#filter_companies) (from 1.3.2)\n    - [Delete](https://developers.freshdesk.com/api/#delete_company) (from 1.3.5)\n    - [Create](https://developers.freshdesk.com/api/#create_company) (from 1.3.6)\n    - [Update](https://developers.freshdesk.com/api/#update_company) (from 1.3.6)\n* [Roles](https://developers.freshdesk.com/api/#roles) (from 1.1.1)\n    - [Get](http://developer.freshdesk.com/api/#view_role)\n    - [List](http://developer.freshdesk.com/api/#list_role)\n* [Agents](https://developers.freshdesk.com/api/#agents) (from 1.1.1)\n    - [Get](http://developer.freshdesk.com/api/#view_agent)\n    - [List](http://developer.freshdesk.com/api/#list_all_agents)\n    - [Update](http://developer.freshdesk.com/api/#update_agent)\n    - [Delete](http://developer.freshdesk.com/api/#delete_agent)\n* [Solutions](http://developer.freshdesk.com/api/#solutions) (from master)\n    - [Solution Category](https://developer.freshdesk.com/api/#solution_category_attributes) (from 1.3.8)\n      - Get\n      - Get Translated\n      - List\n      - List Translated\n      - Create\n      - Create Translated\n      - Update\n      - Update Translated\n      - Delete\n    - [Solution Folder](https://developer.freshdesk.com/api/#solution_folder_attributes) (from 1.3.8)\n      - Get\n      - Get Translated\n      - List\n      - List Translated\n      - Create\n      - Create Translated\n      - Update\n      - Update Translated\n      - Delete\n    - [Solution Article](https://developer.freshdesk.com/api/#solution_article_attributes) (from 1.3.8)\n      - Get\n      - Get Translated\n      - List\n      - List Translated\n      - Create\n      - Create Translated\n      - Update\n      - Update Translated\n      - Delete\n\n\nFrom version 1.3.0, this library uses the Freshdesk v2 API by default.\n\n## Installation\n\nThe easiest way to install is from [PyPi](https://pypi.python.org/pypi/python-freshdesk) inside a virtualenv:\n\n1. Create the virtualenv (Python 2.7 and 3.6+ supported) and activate it:\n\n   ```\n   $ virtualenv cool_app\n   $ cd cool_app \u0026\u0026 source bin/activate\n   ```\n\n2. Install from PyPi:\n\n   ```\n   $ pip install python-freshdesk\n   ```\n\n3. Optionally, run the test suite:\n\n   ```\n   $ pip install pytest\n   $ pytest\n   ```\n\n## Usage\n\nPlease note the domain and API key are not real and the example will not work without changing these.\n\n```python\n\u003e\u003e\u003e from freshdesk.api import API\n\u003e\u003e\u003e a = API('company.freshdesk.com', 'q8dnkjaS554Aol21dmnas9d92')\n```\n\nTo find your API key, follow Freshdesk's step-by-step solution article\n[How to find your API key](https://support.freshdesk.com/support/solutions/articles/215517).\n\nThe `API` class provides access to all the methods exposed by the Freshdesk API.\n\nOptionally, the API can be given SSL verification and/or proxy settings to obey for all requests:\n\n```python\n\u003e\u003e\u003e a = API('company.freshdesk.com', 'q8dnkjaS554Aol21dmnas9d92', verify=False)\n```\n\n```python\n\u003e\u003e\u003e proxies = {\n...     'http': 'http://example.proxy:8000',\n...     'https': 'https://example.proxy:8443'\n... }\n\u003e\u003e\u003e a = API('company.freshdesk.com', 'q8dnkjaS554Aol21dmnas9d92', proxies=proxies)\n```\n\n### Tickets\n\nThe Ticket API is accessed by using the methods assigned to the `a.tickets` instance. Tickets are loaded as instances\nof the `freshdesk.v2.models.Ticket` class, and can be iterated over:\n\n```python\n\u003e\u003e\u003e a.tickets.list_tickets()\n[\u003cTicket 'New ticket'\u003e, \u003cTicket 'Some tests should be created'\u003e, \u003cTicket 'Library needs to be uploaded to PyPi'\u003e]\n\u003e\u003e\u003e a.tickets.list_deleted_tickets()\n[\u003cTicket 'This is a sample ticket'\u003e]\n```\n\nTo see which attributes were loaded for a ticket:\n\n```python\n\u003e\u003e\u003e ticket = a.tickets.get_ticket(4)\n\u003e\u003e\u003e repr(ticket)\n\"\u003cTicket 'I keep typing Freskdesk instead of Freshdesk!\u003e\"\n\u003e\u003e\u003e ticket._keys\nset([u'status', u'source_name', u'ticket_type', u'updated_at', ...])\n```\n\nAttributes are automatically converted to native Python objects where appropriate:\n\n```python\n\u003e\u003e\u003e a.tickets.list_tickets()[0].created_at\ndatetime.datetime(2014, 12, 5, 14, 7, 44)\n```\n\nOr converted from indexes to their descriptions:\n\n```python\n\u003e\u003e\u003e ticket.priority\n'medium'\n\u003e\u003e\u003e ticket.status\n'closed'\n\u003e\u003e\u003e ticket.source\n'phone'\n```\n\nYou can get additional details of the ticket in the response using extra arguments (from 1.3.5).\n\nPlease take a look at the FreshDesk documentation for more details: [View a Ticket](http://developer.freshdesk.com/api/#view_a_ticket)\n\n```python\n\u003e\u003e\u003e ticket = a.tickets.get_ticket(4, \"conversation\", \"requester\", \"company\", \"stats\")\n\u003e\u003e\u003e ticket.stats\n{'agent_responded_at': '2020-06-26T01:23:39Z',\n 'requester_responded_at': '2020-06-25T23:10:15Z',\n 'first_responded_at': '2020-06-17T20:23:43Z',\n 'status_updated_at': '2020-07-24T15:35:21Z',\n 'reopened_at': None,\n 'resolved_at': '2020-07-24T15:35:21Z',\n 'closed_at': None,\n 'pending_since': None}\n```\n\nCreating a ticket can be done by calling `create_ticket()`:\n\n```python\nticket = a.tickets.create_ticket('This is a sample ticket',\n                                 email='example@example.com',\n                                 description='This is the description of the ticket',\n                                 tags=['example'])\n```\n\nTo create a ticket with attachments, pass a list of fully quilified file paths with key name `attachments`:\n\n```python\nticket = a.tickets.create_ticket('This is a sample ticket',\n                                 email='example@example.com',\n                                 description='This is the description of the ticket',\n                                 tags=['example'],\n                                 attachments=[\n                                 '/path/to/file1',\n                                 '/path/to/file2']\n                                 )\n```\n\nThe only positional argument is the subject, which is always required.\n\nYou will need to specify at least one of: `requester_id`, `email`, `facebook_id`, `phone` or `twitter_id` as the\nrequester of the ticket, or the request will fail. All other [keyword arguments](http://developer.freshdesk.com/api/#create_ticket) are optional.\n\nYou can get the list of tickets by calling `list_tickets()`:\n\n```python\nticket = a.tickets.list_tickets(filter_name=None, updated_since='2014-01-01T00:00:00.000Z', page=1, per_page=10)\n``` \n\nAll arguments given above are optional.\n\nBy default the `new_and_my_open` filter is used. If you want to list all the tickets without any filter, pass\n`filter_name=None`.\n\nOnly the tickets that have been created within the past 30 days will be returned by default.\nFor fetching older tickets, use the `updated_since` argument to pass a datetime in isoformat (from 1.3.3).\n\nPagination is supported. If `page` argument is not passed, all pages are fetched, else the specified page is returned.\n\nUpdating a ticket is similar to creating a ticket. The only differences are that the ticket ID becomes the first\npositional argument, and subject becomes an optional named argument.\n\nIn this example, we update the subject and set the priority of the ticket as urgent:\n\n```python\nticket = a.tickets.update_ticket(4,\n                                 subject='This is an urgent ticket',\n                                 priority=4)\n```\n\nThe full list of named arguments you can pass can be found in [updating a ticket](http://developer.freshdesk.com/api/#update_ticket).\n\nTo delete a ticket, just pass the ticket ID value to `delete_ticket()`:\n\n```python\na.tickets.delete_ticket(4)\n```\n\n### Ticket Fields\n\nTo view ticket fields, call `list_ticket_fields()` with a field type:\n\n```python\n\u003e\u003e\u003e a.ticket_fields.list_ticket_fields(type='default_requester')\n[\u003cTicketFields Requester Email of Requester \u003e, \u003cTicketFields Type Type of Ticket \u003e]\n\n```\n\n### Comments\n\nTo view comments on a ticket (note or reply), pass the ticket number to `list_comments()`:\n\n```python\n\u003e\u003e\u003e a.comments.list_comments(4)\n[\u003cComment for \u003cTicket 'Some tests should be created'\u003e\u003e]\n\u003e\u003e\u003e ticket.comments[0]\n'We could use Travis CI'\n```\n\nPagination is supported. If `page` option is not specified, then all the pages are fetched, else specified page is returned. \n\nThe original comment (called \"description\" in Freshdesk) is available on the `Ticket` instance:\n\n```python\n\u003e\u003e\u003e ticket.description\n'nose is a good suite'\n```\n\nIf you want to add a comment to an existing ticket, you can do it via a note or a reply.\n\nThe differences between notes and replies are that notes can be private (only visible to the agents, default).\nReplies are intended to be comments that are sent to the user (e.g. as an email).\n\nTo create a note:\n\n```python\n\u003e\u003e\u003e comment = a.comments.create_note(4,\n                                     'This is a public note',\n                                     private=False)\n'\u003cComment for Ticket #4\u003e'\n```\n\nTo create a reply:\n\n```python\n\u003e\u003e\u003e a.comments.create_reply(4, 'This is the body of a reply')\n'\u003cComment for Ticket #4\u003e'\n```\n\nThe documentaion for [creating a reply](http://developer.freshdesk.com/api/#reply_ticket) and [creating a\nnote](http://developer.freshdesk.com/api/#add_note_to_a_ticket) will provide details of the fields available, which\nyou can pass as named arguments.\n\nIn both methods, the ticket ID and body must be given as positional arguments.\n\n### Contacts\n\nFreshdesk mixes up the naming of contacts and users, depending on whether they are an agent or not.\n`python-freshdesk` simply calls them all contacts and are represented as `Contact` instances:\n\n```python\n\u003e\u003e\u003e repr(a.contacts.get_contact(1234))\n\"\u003cContact 'Rachel'\u003e\"\n```\n\nGet the list of contacts using:\n\n```python\n\u003e\u003e\u003e repr(a.contacts.list_contacts(page=1, per_page=10))\n[\"\u003cContact 'Rachel'\u003e\"]\n```\n\nPagination is supported. If `page` option is not specified, then all the pages are fetched, else specified page is\nreturned. Contact can be filtered using name or email by passing the filter as `email=abc@xyz.com` or\n`mobile=123792182138` or `state=deleted`\n\nOther supported methods are `create_contact`, `update_contact`, `soft_delete_contact`, `permanently_delete_contact`,\n`restore_contact`\n\nTo convert a contact to an agent, use:\n\n```python\n\u003e\u003e\u003e repr(a.contacts.make_agent(1))\n[\"\u003cAgent 'Rachel'\u003e\"]\n```\n\n### Agents\n\nTo get a specific agent instance, use:\n\n```python\n\u003e\u003e\u003e repr(a.agents.get_agent(1234))\n\"\u003cAgent 'Rachel'\u003e\"\n```\n\nYou can list all agents by calling `list_agents()`:\n\n```python\n\u003e\u003e\u003e repr(a.agents.list_agents(page=1, per_page=10))\n[\"\u003cAgent 'Rachel'\u003e\"]\n```\n\nPagination is supported. If `page` option is not specified, then all the pages are fetched, else specified page is\nreturned. Agent can be filtered using name or email by passing the filter as `email=abc@xyz.com` or\n`mobile=123792182138`\n\nOther supported methods are `update_agent`, `delete_agent`\n\n### Groups\n\nTo get the list of groups, use:\n\n```python\n\u003e\u003e\u003e repr(a.groups.list_groups(page=1, per_page=10))\n[\"\u003cGroup 'Service Managers'\u003e\"]\n```\n\nPagination is supported. If `page` option is not specified, then all the pages are fetched, else specified page is returned.\n \nTo get a group, use:\n\n```python\n\u003e\u003e\u003e repr(a.groups.get_group(1))\n[\"\u003cGroup 'Service Managers'\u003e\"]\n``` \n\n### Companies\n\nTo get the list of companies, use:\n\n```python\n\u003e\u003e\u003e repr(a.companies.list_companies(page=1, per_page=10))\n[\"\u003cCompany 'Super Nova'\u003e\"]\n```\n\nPagination is supported. If `page` option is not specified, then all the pages are fetched, else specified page is returned.\n \nTo get a company, use:\n\n```python\n\u003e\u003e\u003e repr(a.companies.get_company(1))\n\"\u003cCompany 'Super Nova'\u003e\"\n``` \n\n[Filtering is also supported](https://developers.freshdesk.com/api/#filter_companies):\n```python\na.companies.filter_companies(query=\"updated_at:\u003e'2020-07-12'\")\n```\n\nTo delete a company (from 1.3.5), call `delete_company()` and pass the Freshdesk company ID.\n\n## Solutions\n\n### Solution Categories\n\nTo get the list of solution categories, use:\n\n```python\n\u003e\u003e\u003e repr(a.solutions.categories.list_categories())\n[\"\u003cSolutionCategory 'General Category' #2\u003e\"]\n```\n\nTo get the translated solution categories, use:\n\n```python\n\u003e\u003e\u003e repr(a.solutions.categories.list_categories_translated('fr'))\n[\"\u003cSolutionCategory 'Catégorie générale' #2\u003e\"]\n```\n\n### Solution Folders\n\nTo get the list of folders from a solution category, use:\n\n```python\n\u003e\u003e\u003e repr(a.solutions.folders.list_from_category(2))\n[\"\u003cSolutionFolder 'Getting Started' #3\u003e\"]\n```\n\nTo get the list of translated folders from a solution category, use:\n\n```python\n\u003e\u003e\u003e repr(a.solutions.folders.list_from_category_translated(2, 'fr'))\n[\"\u003cSolutionFolder 'Commencer' #3\u003e\"]\n```\n### Solution Articles\n\nTo get list of solution articles within a folder, use:\n\n```python\n\u003e\u003e\u003e repr(a.solutions.articles.list_from_foldery(3))\n[\"\u003cSolutionArticle 'Changing account details' #4\u003e\"]\n```\n\nTo get list of solution translatied articles within a folder, use:\n\n```python\n\u003e\u003e\u003e repr(a.solutions.articles.list_from_foldery_translated(3, 'fr'))\n[\"\u003cSolutionArticle 'Modifier les détails du compte' #4\u003e\"]\n```\n\nTo get a specific article by number, use:\n\n```python\n\u003e\u003e\u003e repr(a.solutions.articles.get_article(5))\n[\"\u003cSolutionArticle 'Adding a payment method' #5\u003e\"]\n```\n\nTo get a translated solution article, use:\n\n```python\n\u003e\u003e\u003e repr(a.solutions.articles.get_article_translated(5, 'fr'))\n[\"\u003cSolutionArticle 'Ajouter un moyen de paiement' #5\u003e\"]\n```\n\n## Credits\n\nThank you to all the people who have worked on this library and made it great for everyone.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsjkingo%2Fpython-freshdesk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsjkingo%2Fpython-freshdesk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsjkingo%2Fpython-freshdesk/lists"}