Freshdesk User Management API Guide

Auth method: HTTP Basic Auth with API key (API key as username, any string as password)

Setup steps

1. Log in to your Freshdesk account.
2. Navigate to Profile Settings (top-right avatar menu).
3. Copy the API key displayed under 'Your API Key'.
4. In API requests, use HTTP Basic Auth: set the username to your API key and the password to any non-empty string (e.g., 'X').
5. Encode credentials as Base64 and pass in the Authorization header: 'Authorization: Basic <base64(api_key:X)>'.

List all agents

• Method: GET
• URL: https://<domain>.freshdesk.com/api/v2/agents
• Watch out for: Returns only active agents by default. Use ?active=false to include deactivated agents. Max 100 per page.

Request example

GET /api/v2/agents?page=1&per_page=100
Authorization: Basic <base64(api_key:X)>

Response example

[
  {
    "id": 1,
    "name": "Jane Doe",
    "email": "jane@example.com",
    "active": true,
    "role_ids": [1],
    "created_at": "2023-01-10T08:00:00Z"
  }
]

Get a single agent

• Method: GET
• URL: https://<domain>.freshdesk.com/api/v2/agents/{agent_id}
• Watch out for: Returns 404 if agent_id does not exist or belongs to a different account.

Request example

GET /api/v2/agents/1
Authorization: Basic <base64(api_key:X)>

Response example

{
  "id": 1,
  "name": "Jane Doe",
  "email": "jane@example.com",
  "ticket_scope": 1,
  "role_ids": [1],
  "group_ids": [2]
}

Create an agent

• Method: POST
• URL: https://<domain>.freshdesk.com/api/v2/agents
• Watch out for: Newly created agents are inactive (active=false) until they confirm their email. Agent seat limits apply; exceeding them returns HTTP 400.

Request example

POST /api/v2/agents
Content-Type: application/json

{
  "name": "John Smith",
  "email": "john@example.com",
  "ticket_scope": 1,
  "role_ids": [1]
}

Response example

{
  "id": 42,
  "name": "John Smith",
  "email": "john@example.com",
  "active": false,
  "created_at": "2024-06-01T10:00:00Z"
}

Update an agent

• Method: PUT
• URL: https://<domain>.freshdesk.com/api/v2/agents/{agent_id}
• Watch out for: Uses PUT (full-style), but only supplied fields are updated. Email cannot be changed via this endpoint after creation.

Request example

PUT /api/v2/agents/42
Content-Type: application/json

{
  "job_title": "Support Lead",
  "group_ids": [3, 5]
}

Response example

{
  "id": 42,
  "name": "John Smith",
  "job_title": "Support Lead",
  "group_ids": [3, 5],
  "updated_at": "2024-06-02T09:00:00Z"
}

Delete (deactivate) an agent

• Method: DELETE
• URL: https://<domain>.freshdesk.com/api/v2/agents/{agent_id}
• Watch out for: DELETE deactivates the agent (sets active=false) rather than permanently deleting the record. The agent's contact record is retained.

Request example

DELETE /api/v2/agents/42
Authorization: Basic <base64(api_key:X)>

Response example

HTTP 204 No Content

List all contacts

• Method: GET
• URL: https://<domain>.freshdesk.com/api/v2/contacts
• Watch out for: Supports filter params: email, mobile, phone, company_id, updated_since. Deleted contacts require ?deleted=true.

Request example

GET /api/v2/contacts?page=1&per_page=100
Authorization: Basic <base64(api_key:X)>

Response example

[
  {
    "id": 101,
    "name": "Alice",
    "email": "alice@customer.com",
    "active": true,
    "company_id": 5
  }
]

Create a contact

• Method: POST
• URL: https://<domain>.freshdesk.com/api/v2/contacts
• Watch out for: At least one of email, phone, mobile, or twitter_id is required. Duplicate email returns HTTP 409.

Request example

POST /api/v2/contacts
Content-Type: application/json

{
  "name": "Bob Jones",
  "email": "bob@customer.com",
  "phone": "+14155550100"
}

Response example

{
  "id": 202,
  "name": "Bob Jones",
  "email": "bob@customer.com",
  "active": true,
  "created_at": "2024-06-01T11:00:00Z"
}

Convert contact to agent

• Method: PUT
• URL: https://<domain>.freshdesk.com/api/v2/contacts/{contact_id}/make_agent
• Watch out for: Consumes an agent seat. New agent is inactive until email is confirmed. Fails if seat limit is reached.

Request example

PUT /api/v2/contacts/202/make_agent
Content-Type: application/json

{
  "ticket_scope": 1,
  "role_ids": [1]
}

Response example

{
  "id": 43,
  "email": "bob@customer.com",
  "active": false,
  "ticket_scope": 1
}

• Rate limits: Rate limits are plan-based and applied per account. Limits are expressed as requests per minute (RPM). Freshdesk returns rate-limit headers on every response.
• Rate-limit headers: Yes
• Retry-After header: No
• Rate-limit notes: Headers returned: X-RateLimit-Total (limit), X-RateLimit-Remaining (remaining), X-RateLimit-Used-CurrentRequest (cost of last request). When limit is exceeded, HTTP 429 is returned. Retry after the current minute window resets.
• Pagination method: offset
• Default page size: 30
• Max page size: 100
• Pagination pointer: page (1-based) and per_page

• Webhooks available: Yes
• Webhook notes: Freshdesk supports webhooks via Automation rules (Ticket automations and Observer rules). Webhooks can be triggered on ticket events but are not natively available for agent/contact lifecycle events (create, update, delete) directly.
• Alternative event strategy: For agent/contact change events, poll the List Agents or List Contacts endpoints using the updated_since filter parameter, or use Freshdesk's native SCIM provisioning for identity lifecycle events via your IdP.
• Webhook events: ticket.created, ticket.updated, ticket.resolved, ticket.closed, ticket.reopened

• SCIM available: Yes

• SCIM version: 2.0

• Plan required: Enterprise

• Endpoint: https://.freshdesk.com/scim/v2

• Supported operations: GET /Users (list users), GET /Users/{id} (get user), POST /Users (provision user), PUT /Users/{id} (replace user), PATCH /Users/{id} (update user), DELETE /Users/{id} (deprovision user)

Limitations:

• Requires SSO (SAML) to be configured before enabling SCIM.
• Only available on the Enterprise plan ($79/agent/month billed annually).
• Group (team) provisioning support depends on IdP integration; not all IdPs support Freshdesk SCIM Groups.
• SCIM token is separate from the REST API key and is generated in the Security Settings page.
• Supported IdPs include Okta, Microsoft Entra ID (Azure AD), and OneLogin.

Three scenarios cover the majority of programmatic user management needs. For agent onboarding: POST /api/v2/agents with name, email, ticket_scope, and role_ids; the agent is created with active=false until email confirmation, so poll GET /api/v2/agents/{id} before treating the account as usable.

Seat limits are enforced at creation time - exceeding them returns HTTP 400, so verify available capacity before bulk provisioning. For contact sync from an external CRM: paginate GET `/api/v2/contacts?

updated_since=&per_page=100, deduplicate by email before posting (duplicate email returns HTTP 409), and track X-RateLimit-Remaining` to avoid throttling.

For SCIM-based deprovisioning on Enterprise: generate a SCIM bearer token separately from Admin > Security (it is not the REST API key), configure your IdP to send DELETE /scim/v2/Users/{id}, and confirm deactivation via GET /api/v2/agents/{id} checking active=false.

Onboard a new support agent

1. POST /api/v2/agents with name, email, ticket_scope, and role_ids to create the agent record.
2. Agent receives an invitation email; account is inactive (active=false) until confirmed.
3. Optionally PUT /api/v2/agents/{id} to assign group_ids and job_title after creation.
4. Poll GET /api/v2/agents/{id} to check active=true once the agent confirms their email.

Watch out for: Agent seat limits are enforced at creation time. Verify available seats before bulk provisioning to avoid HTTP 400 errors.

Bulk-sync contacts from an external CRM

1. GET /api/v2/contacts?updated_since=&page=1&per_page=100 to fetch recently changed contacts.
2. Paginate through all pages until a page returns fewer than per_page results.
3. For each contact not in Freshdesk, POST /api/v2/contacts with at minimum name and email.
4. For existing contacts, PUT /api/v2/contacts/{id} with changed fields.
5. Track X-RateLimit-Remaining and pause if approaching zero to avoid HTTP 429.

Watch out for: Duplicate email addresses return HTTP 409. Deduplicate by email before posting. The updated_since filter uses UTC ISO 8601 and is inclusive.

Deprovision an agent via SCIM (Enterprise)

1. Ensure SSO (SAML) is configured and SCIM is enabled in Admin > Security.
2. Generate a SCIM bearer token from the Security Settings page.
3. In your IdP (Okta, Entra ID, OneLogin), unassign the user from the Freshdesk SCIM application.
4. The IdP sends DELETE /scim/v2/Users/{scim_user_id} to Freshdesk automatically.
5. Freshdesk deactivates the agent; verify by GET /api/v2/agents/{id} and confirming active=false.

Watch out for: SCIM deprovisioning requires the Enterprise plan and an active SSO configuration. Removing SCIM access does not delete the agent's historical ticket data.

Several API behaviors are non-obvious and will cause silent failures if not handled explicitly. DELETE on /api/v2/agents/{id} deactivates the agent rather than permanently removing the record - the contact record is retained and the agent continues to appear in historical data.

The List Agents endpoint returns only active agents by default; pass ?active=false to include deactivated accounts, which matters for identity graph reconciliation where stale access must be detected. Pagination is 1-based with no cursor and no total-count header - the only termination signal is a page returning fewer results than per_page.

Freshdesk does not emit webhooks for agent or contact lifecycle events; change detection requires polling with the updated_since filter. Custom agent and contact fields must be pre-created in the admin UI before they can be written via API, making field-level provisioning dependent on out-of-band configuration.

Finally, SCIM provisioning requires an active SAML SSO configuration as a prerequisite - SCIM cannot be enabled independently.