Freshdesk Contacts & Companies

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>.

Anti-triggers

In Freshdesk a contact is a customer who raises tickets; an agent is your own helpdesk staff. freshdesk_contacts_make_agent crosses that line permanently — it consumes a licensed seat and grants access to every ticket in the account, so it is not a labelling change.

• Technician rosters and team capacity — this skill only converts a contact into an agent. For looking up who your technicians are and which teams they sit in, the PSA carries the richer model; use halopsa-agents.
• The same customer in another system — a HaloPSA client, a ConnectWise company, or an Autotask company is a different record with different required fields; use halopsa-clients, connectwise-psa-companies, or autotask-crm. Do not assume IDs or domains map across.
• Assets, sites, or contracts belonging to the customer — Freshdesk companies carry no CMDB or billing model; use halopsa-assets and halopsa-contracts.
• Anything about the customer's tickets — listing, replying, or triaging is freshdesk-ticketing; this skill resolves who the requester is.

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": "john.smith@acme.com",
  "company_id": 5001,
  "job_title": "Office Manager"
}

Search Contacts

GET /api/v2/search/contacts?query="email:'john.smith@acme.com'"

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.
2. 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.
3. Resolve the company — GET /api/v2/companies/{company_id} for the organization's domains, account_tier, and health_score.
4. Use domains to disambiguate — if a contact has no company_id, match the email domain against company domains to infer the right account.
5. 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" (john.smith@acme.com)
                            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.

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