What we do
Tools
Industries
Department
How we workLet's talk →
Home/Freshdesk
Freshdesk developer guide

The Freshdesk API: Authentication, a First Ticket Call, Rate Limits and Webhooks

Freshdesk is Freshworks' help desk, and its API is plain REST over HTTPS with JSON. Most first builds go wrong in the same three places: an auth header that isn't what people expect, list and search calls that quietly return less than you asked for, and outbound events that only exist if someone creates an automation rule. Each is covered below. The longer endpoint-by-endpoint notes live on our Freshdesk API documentation page.

Where Freshdesk stops

It doesn't know what's in your order system, CRM or accounting software, which is exactly where an agent gets stuck.

Stuck on Freshdesk? Let's solve it →
The Freshdesk API in four lines

Base URL: https://{yourdomain}.freshdesk.com/api/v2/. HTTPS only, and it must be the freshdesk.com domain, not a custom CNAME you point at the help desk.

Auth: your API key as the Basic auth username and any placeholder as the password, e.g. curl -u YOUR_API_KEY:X. There's no OAuth flow for a plain script.

Where the key is: click your profile picture, open Profile settings, and it's shown below the change password section. Each agent has their own, and calls run with that agent's permissions.

Profile picture Profile settings Your API Key

Outbound events: there's no webhook subscription endpoint. You create an automation rule that runs on ticket creation or update and pick the Trigger Webhook action.

Your first integration: a ticket in, a webhook out

The smallest useful build: another system opens a Freshdesk ticket, and Freshdesk tells that system when the ticket is resolved.

  1. 1

    Use a dedicated agent for the key

    Create an agent seat (or pick an admin) that exists only for the integration, and use its key. If you build on a real person's key, the integration breaks the day they leave and every API note shows their name.

  2. 2

    Create the ticket

    POST /api/v2/tickets with a requester (an email, requester_id, phone or unique_external_id), a subject, a description, and status and priority as numbers. Status 2 is Open, 3 Pending, 4 Resolved, 5 Closed. Priority runs 1 (Low) to 4 (Urgent).

    Watch for: custom fields. They go in a custom_fields object under their internal names, which usually start with cf_ (for example cf_order_number), not the label agents see. Dates are YYYY-MM-DD.

  3. 3

    Read the rate-limit headers on the response

    Every reply carries X-RateLimit-Total, X-RateLimit-Remaining and X-RateLimit-Used-CurrentRequest. Log them from day one. They tell you your real per-minute allowance, which is safer than any table, including ours.

  4. 4

    Add the rule that sends events out

    Admin Workflows Automations Ticket updates

    Create a rule with a condition such as status changed to Resolved, and the action Trigger Webhook. Set the method and URL, and build the JSON body with placeholders like {{ticket.id}} and {{ticket.status}}. Under Advanced you can add your own headers.

    Watch for: the request isn't signed. Put a secret in a custom header or use basic auth on your endpoint, and reject anything without it.

  5. 5

    Test somewhere that isn't live

    Enterprise plans include a sandbox. On other plans, use a trial account. A rule firing on every ticket update is easy to get wrong, and on a live desk it fires on real customers.

Where one minute of API calls goes

The limit is per minute for the whole account, not per key or per IP, and failed requests count too. Embedding related records with include= costs an extra call each time.

Example · one minute of a sync on a Growth plan
Account allowance per minute (Growth; Pro is 400, Enterprise 700, trials 50) 100 calls
20 ticket list pages with include=requester (each embed adds a call) − 40
20 ticket views with include=conversations − 40
12 ticket updates writing status back − 12
3 requests that failed on a bad field (still counted) − 3
Left for agents' Marketplace apps this minute 5 calls

Apps your agents use in the ticket sidebar spend the same budget, so a sync running at full speed can make their apps slow or fail. Endpoints also have their own sublimits, such as ticket list calls on Growth. On a 429, wait the seconds in Retry-After and resend. Freshdesk sells higher limits (1,000 or 2,000 a minute) if a real workload needs it.

Why a Freshdesk API call returns less than you expected

The ticket list only goes back 30 days

How you'll know: A full export comes back with a month of tickets.

Fix: GET /api/v2/tickets returns tickets created in the last 30 days unless you pass updated_since. Page through with per_page=100 (the maximum) and follow the link header until there's no rel="next". The list stops at 300 pages, so split large pulls by date.

Filtered search stops at 300 results

How you'll know: A query that should match thousands of tickets returns exactly 300.

Fix: /api/v2/search/tickets gives 30 results a page and won't go past page 10. Narrow the query by date or status and run several, or use the list endpoint with updated_since for bulk work. Archived tickets never appear in search.

The webhook rule exists but never fires

How you'll know: The rule is saved, the endpoint is up, and nothing arrives.

Fix: Check the rule type first: creation rules don't run on updates. Then check the order of rules and whether rules are set to run only the first match, because an earlier rule can catch the ticket.

Custom field values silently missing

How you'll know: The ticket is created, but the order number field is blank.

Fix: You sent the label, not the internal cf_ name, or the field type doesn't match (a dropdown only accepts one of its set values). Pull the field definitions from the ticket fields endpoint when the integration starts and map them there.

What the API is for, once it works

Freshdesk's own automation rules already handle routing, SLA escalation and canned responses inside the help desk. What they can't do is look anything up in a system Freshdesk has never heard of. An agent opening a "where's my order" ticket still leaves Freshdesk to look it up: the store admin for the order, the carrier for tracking, sometimes the books for a payment hold. The API is how that context gets onto the ticket and how an agent's decision gets back out.

n-frames builds that layer: order status, tracking, invoice and payment history and CRM account data on the ticket, routing that uses account tier or order value instead of subject-line keywords, and refunds or replacement shipments started in Freshdesk that post to QuickBooks, NetSuite or your warehouse system. Freshdesk's Marketplace covers a lot of common pairings. A homegrown order system, unusual pricing or a CRM field that doesn't map to what a ready-made app expects is where the custom build earns its keep. For the sales side, see Freshdesk and CRM; for ready-made apps, Freshdesk integrations.

A specialty retailer answering "where's my order?"

Specialty retailer · Freshdesk fed by email, orders in a separate system

Before

Agents asked every customer for an order number, then looked up shipping status in another tab before they could write a reply.

After

Order history, shipping status and tracking now show on the ticket itself.

Where-is-my-order tickets get answered without opening a second system.

Questions people ask

What is Freshdesk?

Freshworks' customer support help desk: ticketing, a shared team inbox, a self-service knowledge base and automation rules for routing and escalation. Freshworks also sells Freshservice for IT service management and Freshchat for messaging, as separate products.

Does Freshdesk have a free plan?

Not a permanent one now. The pricing page lists Growth, Pro and Enterprise, each with a 14-day trial, and Freshdesk has run limited free programs for very small teams. Check freshdesk.com/pricing for what's open to new accounts. n-frames doesn't sell Freshdesk plans; we build on whichever one you have.

Does Freshdesk work as a CRM?

No. It tracks tickets, contacts and companies, not deals or a sales pipeline. Freshworks' CRM is a separate product, Freshsales. What helps most is connecting Freshdesk to the CRM you already run so agents see account and deal context on the ticket. More on Freshdesk and CRM.

What's the difference between Freshdesk and Freshservice?

Freshdesk is for supporting customers. Freshservice is IT service management for internal requests, incidents and assets. They share Freshworks underpinnings, but a business can run either, both or neither, and their APIs are separate.

Does Freshdesk have an API for custom integrations?

Yes, a documented REST API (v2) covering tickets, conversations, contacts, companies, agents, groups, time entries, canned responses and automation rules. Auth is your API key over Basic auth. It's what Marketplace apps use, and what n-frames builds custom integrations on.

How does Freshdesk compare to Zendesk?

Freshdesk is generally quicker to set up and priced for smaller teams. Zendesk is more configurable and aimed at larger, more complex operations, and its API now runs on OAuth rather than keys. The full Freshdesk vs Zendesk comparison covers which fits whom.

Does Freshdesk have its own automation rules?

Yes. Automations route, escalate and update tickets on creation, on updates and on a schedule. The Trigger Webhook action lets a rule call another system, which is how Freshdesk sends events out. Anything that has to read data back or act across several systems is custom integration work.

What are the Freshdesk API rate limits?

A per-minute limit for the whole account that depends on your plan: Freshdesk's table shows 100 on Growth, 400 on Pro and 700 on Enterprise, and 50 on a trial, with lower sublimits on some endpoints. Embeds and failed requests count. The X-RateLimit-Total header on any response shows your account's actual figure.

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.