Custom objects handbook

The Zendesk API lets you work with native objects such as tickets and users. Though you have many objects at your disposal, the available ones can't meet every possible need of every customer. Enter custom objects.

The Custom Objects API lets you define a new object type in Zendesk, then create objects from the new object type. The API stores your objects in the Zendesk infrastructure. You can also use it to define and manage relationships with other objects, including native Zendesk objects like tickets and users.

The API consists of the following resources:

• object types - templates for creating custom objects
• object records - instances of custom objects
• relationship types - templates for creating relationship records
• relationship records - instances of relationships between two object records
• jobs - batch operation jobs for object records and relationship records

Object types

An object type is a template for objects of that type. It consists of a key attribute and a schema attribute.

The key is the name that identifies the object type, like "ticket" or "user" in the Zendesk API.

The schema describes the data. The schema doesn't contain any information about a specific object. It just describes that information. You can also define validation rules in the schema to maintain the data integrity of your object records. For more information, see Creating a schema for a custom object.

Example:

{
  "data": {
    "key": "copier",
    "schema": {
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique identifier assigned to the copier by IT"
        },
        "model": {
          "type": "string",
          "description": "Make and model of the copier"
        },
        "networked": {
          "type": "boolean",
          "description": "Whether or not the copier is networked"
        }
      },
      "required": ["id", "model"]
    }
  }
}

API path

The API path for object types is /api/sunshine/objects/types. For details, see the API docs.

API docs

See Object Types in the API docs.

Object records

An object record is an instance of a given object type. It consists of a type string and an attributes object. The type is the name (or key) of any object type you defined. The attributes object contains the attributes you defined for the object type and their values.

Example:

{
  "data": {
    "type": "copier",
    "attributes": {
      "id": "1019 4C BW",
      "model": "OptiJet X55",
      "networked": true
    }
  }
}

API path

The API path for object records is /api/sunshine/objects/records. For details, see the API docs.

API docs

See Object Records in the API docs.

Relationship types

You can define relationships between objects to use your data in more meaningful ways. A relationship can be between:

• two custom objects
• one custom object and any of the following native Zendesk objects: tickets, users, articles, organizations, groups, or chats.
• two of the listed native Zendesk objects

The API supports three relationship types:

• One-to-one - Both object types can have only one object on either side of the relationship. For example, a ticket would only be associated with a unique copier, and a copier would only be associated with a unique ticket. This isn't a viable option in the IT department example. The number of copier objects would have to equal the number of ticket objects.

• One-to-many or Many-to-one - In a one-to-many relationship type, each object of the first object type relates to none, one, or many object of the second object type. For example, a copier can be associated with none, one, or many tickets. In a many-to-one relationship type, none, one, or many objects of the first object type can be associated with each object of the second object type. For example, none, one, or many tickets can be associated with a copier. This alternative perspective on the same data makes a difference on how you access your data.

• Many-to-many - You define a many-to-many relationship type with two one-to-many relationship types. Each object of the first object type relates to none, one, or many objects of the second object type, and each object of the second object type relates to none, one, or many objects of the first object type.

A relationship type consists of the following attributes: key, source, and target. The key is the name that identifies the relationship type. The source is the left-side "one" in a one-to-one or one-to-many relationship type, or the left-side "many" in a many-to-one relationship type. The target is the right-side "one" or "many". Their values can be the name of any object type you defined or any of the following names for native Zendesk object types:

• zen:ticket
• zen:user
• zen:article
• zen:organization
• zen:group
• zen:chat
• zen:brand
• zen:lead
• zen:contact
• zen:deal

The source and target can be two custom object types, a custom object type and a Zendesk object type, or two Zendesk object types, as either source or target.

To define a one-to-many relationship type, enclose the target value in square brackets. To define a many-to-one relationship type, enclose the source value in square brackets. Omit the square brackets for a one-to-one relationship type.

Defining a relationship type doesn't create an association between two specific objects. It just describes the relationship record. To associate two objects, you must create a relationship record between the two objects. See Relationship Records.

Example:

{
  "data": {
    "key": "copier_has_many_tickets",
    "source": "copier",
    "target": ["zen:ticket"]
  }
}

API path

The API path for relationship types is /api/sunshine/relationships/types. For details, see the API docs.

API docs

See Relationship Types in the API docs.

Relationship Records

A relationship record is an instance of a given relationship type. It ties two specific object records together. A relationship record consists of the ids of the two related object records and the relationship type. The record doesn't contain any actual object data -- just the ids of the object records.

Creating relationship records allows you to use the List Relationship Records by Object Record endpoint to get links to all the object records associated with a particular object. For example, a single request could return links to all the tickets associated to a particular copier.

Example:

{
  "data": {
    "relationship_type": "copier_has_many_tickets",
    "source": "1c771ee0-2c3f-11e7-bf60-e5c3f630b5aa",
    "target": "35437746"
  }
}

API path

The API path for relationship records is /api/sunshine/relationships/records. For details, see the API docs.

API docs

See Relationship Records in the API docs.

Jobs

You can use the Jobs API to define and run your own batch operation jobs for object records and relationship records. For example, you can define and run a job that creates many object records in Zendesk.

Batch operation jobs are asynchronous. Making a request kicks off the job but the API doesn't wait for the job to finish before sending a response. The response gives you a job id that you can use to poll the API for the status of the job. A job can be "queued", "processing", "failed", "completed", or "aborted".

You use a single endpoint, Create Job, for all batch operations:

POST api/custom_resources/jobs

The endpoint takes a JSON object with the following properties:

Name	Type	Comment
type	string	One of "resources" or "relationships"
action	string	Currently only "post" is supported
data	array	An array of object records or relationship records to process. The format is the same as the "data" object for the equivalent single-operation endpoints for object records or relationship records

Example:

{
  "type": "resources",
  "action": "post",
  "data": [
    {
      "type": "product",
      "external_id": "3",
      "attributes": {
        "id": "3",
        "name": "Strawberry Chewing Gum"
      }
    },
    {
      "type": "product",
      "external_id": "4",
      "attributes": {
        "id": "4",
        "name": "Coffee Chewing Gum"
      }
    }
  ]
}

API path

The API path for jobs is /api/custom_resources/jobs. For details, see the API docs.

API docs

See Jobs in the API docs.