Custom Objects in Freshdesk

A custom field describes a ticket. Custom objects in Freshdesk are things in their own right that tickets can point at. Knowing which you need saves a rebuild.

Start free trial All guides

What custom objects in Freshdesk are

Freshdesk ships with a fixed set of things it knows about: tickets, contacts, companies, agents, groups, articles. Custom objects let you define your own, with your own fields, and hold records of them inside Freshdesk.

The vocabulary is worth getting straight because the docs use it consistently.

Schema. The definition. What the object is called and what fields it has, with types such as text, number, date, dropdown and lookup.

Record. One instance. If the schema is Subscription, a record is one specific subscription.

Lookup. A field that points at another record, including at a ticket or a contact. This is the relationship, and it is the entire point of the feature.

Availability sits on the higher Freshdesk plans and the details have moved over time, so check what your subscription includes before designing anything around it.

Custom fields or custom objects

This is the actual decision and it comes down to one question: is this thing owned by the ticket, or does it exist independently of any ticket?

Use a custom field when the value is an attribute of this ticket. Severity. Affected module. Refund amount. Order reference, if you only ever need the number written down and never anything else about the order.

Use a custom object when the thing has its own life, its own attributes, and shows up across many tickets. Devices under warranty. Subscriptions. Physical assets. Courses a student is enrolled on. Properties in a portfolio.

The test I use in practice: if you would ever want to see all the tickets about this thing, or store attributes of the thing that are not attributes of a ticket, it is an object. If you're about to add three related custom fields that always change together, that is an object trying to be born.

The symptom of getting this wrong is a text field containing a serial number, typed slightly differently on every ticket, with no way to answer "how many tickets has this device generated".

Designing a schema that will not embarrass you

Start narrower than you think. It's far easier to add a field later than to unpick an object that turned out to mean two different things.

One concept per object. If your Device object has fields describing the customer contract, you have two objects. Split them and relate them.

Give it a real identifier. A field that's genuinely unique and comes from a system of record, a serial number, an account number, a subscription ID. Without one, deduplicating records later is horrible.

Prefer dropdowns over free text for anything you will filter or report on. Same reasoning as custom fields, and the same failure mode when you skip it.

Decide the source of truth first. If the object mirrors data from a billing system or a CRM, that other system owns it and Freshdesk holds a synced copy. Write down which direction data flows before anyone builds, because bidirectional sync between two systems that both think they're authoritative is a permanent tax.

Then relate it to tickets with a lookup field on the ticket, so an agent picks the device or subscription while working, and the link is structured rather than typed.

Working with records

Records get created and edited in three ways: by hand in the admin area, in bulk by import, or programmatically.

Bulk import is how most implementations start. Export from the system that owns the data, map the columns, load it. Do a small batch first and check the field types came through as you expected, particularly dates, which are the usual casualty.

For anything ongoing you want a sync. Custom object schemas and records are addressable through the Freshworks developer platform, though the exact endpoints and the plan requirements differ from the plain ticket API, so read the current developer documentation for the shapes rather than assuming they mirror /api/v2/tickets. The general orientation in the API documentation guide still applies: same auth model, same rate limit discipline.

Whatever you build, give the sync a reconciliation pass. A nightly job that compares counts and flags records present in one system and not the other catches drift long before an agent does.

When not to bother

Custom objects are structure, and structure has a maintenance cost. Three cases where the answer is no.

If the data already lives in a system your agents can see through an existing integration, showing it in the sidebar is cheaper and always current. Copying it into Freshdesk creates a second version that will disagree with the first.

If nobody will maintain the records, stale objects are worse than no objects. An agent who finds a device record showing a warranty that expired last year will stop trusting the whole feature.

And if you are on a plan without them, do not contort the account trying to approximate them. A well-named custom field plus a link out to the real system is an honest solution that costs nothing.

FAQ

Frequently asked questions

How do you design the schema?

Start from what a ticket needs to point at. The Freshdesk data model is tickets, contacts and companies until you add objects, and a Freshdesk schema that mirrors your business rather than your spreadsheet survives longer. The Freshdesk custom object API is how records get in at volume.

What is the difference between a custom field and a custom object in Freshdesk?

A custom field is an attribute of a ticket or contact. A custom object is a separate thing with its own fields and records, which tickets can point at through a lookup. Use an object when the thing exists independently of any one ticket.

Which Freshdesk plans include custom objects?

They sit on the higher tiers, and the specifics have changed over time. Check your current plan details rather than relying on a figure from a blog post.

Can I link a custom object record to a ticket?

Yes, through a lookup field, so an agent selects the record while working the ticket. That structured link is the reason to use an object rather than a text field.

Can I manage custom objects through the API?

Schemas and records are addressable programmatically, though through the Freshworks developer platform rather than the plain v2 ticket endpoints. Read the current developer documentation for the exact paths.

Should I sync custom objects from another system?

Only with a clear source of truth and a one-way flow. Two systems that both consider themselves authoritative produce conflicts that nobody wants to own.