Freshdesk Contacts & Companies

Overview

In Freshdesk, contacts are the people who raise tickets (requesters) and companies group those contacts into the organizations an MSP serves. Resolving a ticket's requester to a contact, and that contact to its company, is the foundation for account-level context, SLA association, and reporting. This skill covers contact and company operations through tools named freshdesk_contacts_<action> and freshdesk_companies_<action>.

Contacts

Key Contact Fields

A contact must have at least one of email, phone, mobile, twitter_id, or unique_external_id.

Contact Operations

Create a Contact

{
  "name": "John Smith",
  "email": "[email protected]",
  "company_id": 5001,
  "job_title": "Office Manager"
}

Search Contacts

GET /api/v2/search/contacts?query="email:'[email protected]'"

The query language wraps the expression in double quotes and quotes string values. Search returns up to 30 results per page and a maximum of 10 pages (300 records).

Merge Duplicate Contacts

POST /api/v2/contacts/merge

{
  "primary_contact_id": 1001,
  "secondary_contact_ids": [1002, 1003]
}

Tickets and history from the secondary contacts are re-pointed at the primary. Confirm which record should be primary before merging — merges are not easily reversible.

Make a Contact an Agent

PUT /api/v2/contacts/{id}/make_agent

Converts a customer contact into a Freshdesk agent. This is a privileged, billing-affecting change — flag it explicitly before invoking.

Companies

Key Company Fields

Company Operations

Search Companies

GET /api/v2/search/companies?query="name:'Acme'"

You can also locate a company by an autocomplete-style name lookup:

GET /api/v2/companies/autocomplete?name=Acme

Resolving Requester -> Contact -> Company

A core MSP workflow is enriching a ticket with full account context:

1. Start from the ticket — a ticket carries requester_id and, when set,

company_id. Read the ticket first.

1. Resolve the contact — GET /api/v2/contacts/{requester_id} (or search

by email if you only have an address). This yields the contact's company_id, job_title, and contact channels.

1. Resolve the company — GET /api/v2/companies/{company_id} for the

organization's domains, account_tier, and health_score.

1. Use domains to disambiguate — if a contact has no company_id, match

the email domain against company domains to infer the right account.

1. Cache reference data — companies and frequent contacts change rarely;

cache lookups within a session to stay under the per-minute rate limit.

Ticket #4821
  requester_id: 1001  ->  Contact "John Smith" ([email protected])
                            company_id: 5001
                              ->  Company "Acme Corporation"
                                    domains: ["acme.com"], tier: "Gold"

Error Handling

Best Practices

• Search before creating — avoid duplicate contacts by checking email

first; let ticket creation auto-create only when intentional.

• Maintain company domains — accurate domains let Freshdesk

auto-associate new contacts to the right company.

• Confirm the primary on merge — merges re-point history and are hard to

undo.

• Treat make_agent as privileged — it affects licensing; flag it before

running.

• Cache company lookups — they rarely change and reduce request volume.

Related Skills

• Freshdesk Ticketing - Tickets reference requesters and companies
• Freshdesk API Patterns - Search query language and pagination
• Freshdesk SLA & Business Hours - Company/tier-driven SLA association