Custom Objects in Zendesk
Zendesk ships with three nouns: tickets, users, organizations. A custom object in Zendesk is how you add a fourth one your business actually cares about.
A custom object in Zendesk has three layers
People say "custom object" and mean three different things at once. Separate them before you build anything, because the mistakes all live in the seams.
device, a display name, and the shape every record of that type follows.The key you hand an object type is the piece you cannot casually rename later, because API paths, lookup filters and half your integration code all hang off it. Pick it slowly. Lowercase, singular, no version numbers.
When a custom field stops being enough
The test is boring and it works. Count the things.
One value per ticket? That is a custom field. One value per account? That's an organization field. Many records of the same shape, each with attributes of its own, that a ticket needs to point at and that you need to report on? Now you want an object.
Made concrete: a serial number typed into a text box is a string nobody can report on and everybody mistypes. A device record with a model, a warranty end date and an owner is a thing that exists. Tickets reference it. Explore groups by it. An agent opens the ticket and sees the warranty status without asking.
The counter-argument is real, though, and worth saying out loud. Objects mean more admin surface, more onboarding, and a dataset somebody has to keep current. If nothing populates them automatically, they rot inside a quarter and then actively mislead your agents. Our broader take on when custom objects earn their place goes further on that.
Relating records to tickets
An object on its own is a spreadsheet with extra steps. The value arrives when a ticket points at a record, which happens through a lookup relationship field.
You add a field to the ticket form, set its target to your object type, and the field stores the record id rather than a copy of the text. Change the warranty date on the device and every ticket referencing it is instantly correct. That is the whole trick, and it is the reason objects beat fields for anything that changes.
Lookup fields also accept a filter, so a device field can be limited to records belonging to the requester organization instead of offering agents all forty thousand rows.
The API
Records are managed through their own endpoints, namespaced by the object type key. Listing them looks like this.
# every record of the device object type
curl -s -u you@example.com/token:APITOKEN \
https://acme.zendesk.com/api/v2/custom_objects/device/records.jsonCreating one is a POST with the record wrapped in a custom_object_record envelope. Keeping the payload in a file saves you a fight with shell quoting.
curl -s -u you@example.com/token:APITOKEN -X POST \
-H "Content-Type: application/json" \
-d @device.json \
https://acme.zendesk.com/api/v2/custom_objects/device/records.jsonAnd device.json:
{
"custom_object_record": {
"name": "SN-4471",
"external_id": "erp-SN-4471",
"custom_object_fields": {
"model": "X200",
"warranty_end": "2027-03-01"
}
}
}Set external_id to the primary key from whatever system owns the data. It turns a sync from "search, compare, decide" into an upsert, and it's the difference between a nightly job you trust and one you babysit. Endpoint paths and field names do drift, so check the current Zendesk developer docs before you commit a client library to them.
Limits and the things that bite
Custom objects sit on the higher plan tiers, and there are ceilings on how many object types and how many records an account may hold. Both have moved over time. Check what your plan includes before you design around them, not after.
Frequently asked questions
How does this change the underlying data model?
It extends it. The Zendesk data model is tickets, users and organizations until you add a custom object, at which point relationships become yours to design.
What is a custom object in Zendesk?
A record type you define yourself, with its own fields, sitting alongside tickets, users and organizations. Tickets reference individual records through lookup relationship fields.
Custom object or custom field?
Field for a single value on a ticket. Object when you have many records of one shape that tickets need to point at and you need to report across them.
Can I create custom object records through the API?
Yes, records have their own endpoints namespaced by the object type key. Set an external_id so your sync can upsert instead of guessing.
Which Zendesk plans include custom objects?
The higher tiers, with limits on object types and total records. Those limits change, so check the current Zendesk docs against your plan.
Can I rename an object type key later?
Treat it as permanent. The key appears in API paths and integrations, so changing it breaks things quietly rather than loudly.
Cleaner data, fewer duplicates
The more precisely Zendesk knows what a ticket is about, the more confidently Ticket Merger can tell two tickets apart.
Start free trial14-day free trial. No credit card required.