What we do
Tools
Industries
Department
How we workLet's talk →
Home/Freshdesk/Freshdesk API Documentation, Mapped by Endpoint
Freshdesk API reference

The Freshdesk API Documentation, Read Endpoint Group by Endpoint Group

developers.freshdesk.com/api is one page that scrolls for a very long time: every endpoint, every field and every error in a single document. Miss one rule in it, like the 100-a-page cap or a custom field's internal name, and a sync can run for weeks while quietly skipping tickets or leaving fields blank. If you need the auth line and a first ticket call, start on the Freshdesk API quick start.

Before you read the reference

Which version: v2. The legacy v1 API is deprecated and closed to new users, so skip any forum answer or library built on v1 paths.

Format: JSON only, since XML is deprecated. Every path starts at https://yourdomain.freshdesk.com/api/v2/, and requests carry your API key over Basic auth.

Paging: page and per_page, with 30 a page by default and 100 the maximum. Asking for more than 100 is an error, not a silent cap. The next page's URL comes in the link header.

Changes: Freshdesk gives 60 days' notice of breaking changes, with rare exceptions. Code samples live on GitHub for Java, Node.js, PHP, Python, Ruby and C#.

Freshdesk API endpoints, grouped the way you'll use them

Group in the docs Paths and operations Read closely
Tickets /api/v2/tickets: create, view, update, list, delete and restore, plus forward, merge, associations and bulk update or delete at /tickets/bulk_update and /tickets/bulk_delete. Status and priority are numbers, not labels. Embedding related data with include costs extra calls from your per-minute budget.
Conversations /tickets/{id}/reply for a public reply, /tickets/{id}/notes for a note (public or private), and a list call for the whole thread. A reply emails the requester. Use a private note when the integration is only recording something for agents.
Contacts and companies /api/v2/contacts and /api/v2/companies: create, view, list, update, delete, plus merge, import and export. Contacts also have autocomplete search and a filter call. Contacts have soft and hard delete. A soft-deleted contact can be restored; a hard delete is permanent.
Time entries /tickets/{id}/time_entries per ticket and /api/v2/time_entries for everything, including starting and stopping a timer. Useful for billing exports. Pull by date range rather than ticket by ticket.
Ticket fields /api/v2/ticket_fields to read definitions, /api/v2/admin/ticket_fields to change them, along with sections and forms. Read this at startup and map custom fields by their internal names. Labels change; internal names don't.
Filter tickets /api/v2/search/tickets?query= with a URL-encoded query up to 512 characters, supporting greater-than and less-than on dates and numbers. Results are capped and archived tickets aren't included. For bulk pulls, list with updated_since instead.

Freshdesk API documentation questions

Where do I get my Freshdesk API key?

Click your profile picture, open Profile settings, and the key is shown below the change password section. Each agent has their own, and it acts with that agent's permissions. Send it as the Basic auth username with any placeholder, such as X, as the password.

Does Freshdesk have a sandbox for testing integrations?

Yes, on the Enterprise plan, where a sandbox copy of your help desk lets you test rules and API calls away from customers. On Growth or Pro, test against a trial account or a separate low-traffic help desk before pointing code at live tickets.

Does Freshdesk have an official SDK?

No official SDK in the usual sense. Freshdesk publishes code samples on GitHub for Java, Node.js, PHP, Python, Ruby and C#, and most integrations, ours included, call the HTTP endpoints directly. Community client libraries exist; check they target v2 before you use one.

Can the Freshdesk API trigger actions on its own, or does it only respond to requests?

It only responds. Something has to call it. For Freshdesk to tell another system that a ticket changed, an automation rule with the Trigger Webhook action sends the request out, and that rule is set up in the admin screens, not through the API.

What can the Freshdesk API not do?

Anything missing from the reference, which includes parts of admin configuration and some newer features. Tickets, conversations, contacts, companies, time entries and field definitions, the data most integrations move, are all covered. Where a step has no endpoint, n-frames automates it in the Freshdesk interface.

Is the Freshdesk API documentation public?

Yes, at developers.freshdesk.com/api, with no sign-in needed to read it. Making calls needs a Freshdesk account and an agent's API key. Freshworks documents Freshservice and its other products separately, with their own APIs.

Decoding a Freshdesk API error response

Every error body has a description and an errors array naming the field, a message and a code. Read the array before guessing.

400 with missing_field or invalid_value

How you'll know: The ticket or contact wasn't created, and the response names a field.

Fix: A required field was left out, or a dropdown got a value it doesn't list. Check the field definition from the ticket fields endpoint and send one of its allowed values, under its internal cf_ name.

duplicate_value on a contact

How you'll know: Creating a contact fails for an email you can't find in the list.

Fix: That email already belongs to another contact. Look it up first and update it, or restore it, instead of creating a new one.

401 invalid_credentials

How you'll know: Calls that worked yesterday all fail.

Fix: The key was reset, the agent behind it was deactivated, or the apikey:X pair isn't Base64-encoded in the header. Integrations should run on a key belonging to a dedicated agent, not a person.

403 access_denied

How you'll know: Tickets work, but admin endpoints or some groups refuse.

Fix: The call runs with the permissions of the agent who owns the key. Give that agent the role the integration needs, or use a different key for admin tasks.

406 or 415 on a request that looks right

How you'll know: A body you'd swear is valid JSON is rejected.

Fix: Set Content-Type: application/json on writes and don't ask for anything but JSON in Accept. Some HTTP libraries send form encoding unless told otherwise.

429 Too Many Requests

How you'll know: A burst of calls, then refusals.

Fix: Wait the seconds in Retry-After, then resend. Newer responses add X-RateLimit-Account-* and X-RateLimit-Sublimit-* headers, so you can see whether the account budget or an endpoint's own sublimit ran out.

Integrations the Freshdesk docs leave for you to design

The reference tells you what each call accepts. It doesn't tell you when to make it. The builds that matter sit between Freshdesk and a system the Marketplace doesn't cover: a form submission, an inbound webhook or an order exception that opens a ticket already tagged, prioritized and assigned to the right group; a homegrown order system kept in two-way sync, so a status change on either side shows on the other.

Outbound events come from automation rules with the Trigger Webhook action rather than a subscription endpoint, so the design usually pairs a rule in Freshdesk with a small service that receives the call, checks a shared secret and calls back for anything the payload left out. For ready-made apps, see Freshdesk integrations; for help desk numbers next to business numbers, Freshdesk reporting.

Let's talk

Tell us the one thing your team does manually that eats up time. We read every message and reply within a day.