/contacts-companies

name: "Freshdesk Contacts & Companies"
description: >
  Freshdesk contacts and companies: contact fields and the required
  contact-channel rule, contact CRUD plus merge and make_agent, company fields
  and domain-based auto-association, search and autocomplete lookups, and the
  MSP workflow of resolving a ticket requester to a contact and then to its
  parent company through the Freshdesk REST API v2.
when_to_use: >-
  When working with Freshdesk contacts and companies — looking up, creating, updating, merging, or
  converting them, and resolving a ticket requester to a contact and company. Use when: freshdesk
  contact, freshdesk company, freshdesk requester, merge contact freshdesk, make agent freshdesk,
  search contacts freshdesk, resolve requester freshdesk, or freshdesk customer.

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

| Field | Type | Required | Description | |-------|------|----------|-------------| | `id` | Integer | System | Auto-generated unique identifier | | `name` | String | Yes | Full name | | `email` | String | One of email/phone/mobile | Primary email | | `phone` | String | One of email/phone/mobile | Landline | | `mobile` | String | One of email/phone/mobile | Mobile number | | `company_id` | Integer | No | Associated company | | `job_title` | String | No | Role at the company | | `tags` | Array | No | Free-form labels |

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

Contact Operations

| Action | Endpoint | Notes | |--------|----------|-------| | List | `GET /api/v2/contacts` | Filter with `email`, `mobile`, `phone`, `company_id`, `updated_since` | | Get | `GET /api/v2/contacts/{id}` | Single contact | | Search | `GET /api/v2/search/contacts?query="..."` | Query language; 300-result cap | | Create | `POST /api/v2/contacts` | `name` + one contact channel required | | Update | `PUT /api/v2/contacts/{id}` | Partial update | | Merge | `POST /api/v2/contacts/merge` | Combine duplicates into a primary | | Make agent | `PUT /api/v2/contacts/{id}/make_agent` | Convert a contact into an agent |

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

| Field | Type | Required | Description | |-------|------|----------|-------------| | `id` | Integer | System | Auto-generated unique identifier | | `name` | String | Yes | Company name (unique) | | `domains` | Array | No | Email domains used to auto-associate contacts | | `description` | String | No | Notes about the company | | `note` | String | No | Internal note | | `health_score` | String | No | Account health indicator | | `account_tier` | String | No | Service tier |

Company Operations

| Action | Endpoint | Notes | |--------|----------|-------| | List | `GET /api/v2/companies` | Paginated with `page` / `per_page` | | Get | `GET /api/v2/companies/{id}` | Single company | | Search | `GET /api/v2/search/companies?query="..."` | Query language; 300-result cap | | Create | `POST /api/v2/companies` | `name` required and unique | | Update | `PUT /api/v2/companies/{id}` | Partial update |

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 `