Legacy custom objects handbook

Note: There is a new custom objects experience. See the Custom Object APIs.

The Zendesk API lets you work with standard 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 Legacy Custom Objects API lets you define a new legacy object type in Zendesk, then create legacy objects from the object type. The API stores your legacy objects in the Zendesk infrastructure. You can also use it to define and manage relationships with other objects, including standard Zendesk objects like tickets and users.

The API consists of the following resources:

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

Legacy object types

A legacy 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 legacy 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 legacy 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 Legacy Object Types in the API docs.

Legacy 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 legacy object type you defined. The attributes object contains the attributes you defined for the legacy 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 Legacy Object Records in the API docs.

Legacy relationship types

You can define legacy 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 legacy custom object types, a legacy custom object type and a standard Zendesk object type, or two standard 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 Legacy 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 Legacy Relationship Types in the API docs.

Legacy Relationship Records

A legacy relationship record is an instance of a given legacy relationship type. It ties two specific object records together. A legacy 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 legacy relationship records allows you to use the List Legacy 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 Legacy Relationship Records in the API docs.

Jobs

You can use the Jobs API to define and run your own batch operation jobs for legacy object records and legacy-relationship records. For example, you can define and run a job that creates many legacy 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 legacy object records or relationship records to process. The format is the same as the "data" object for the equivalent single-operation endpoints for legacy 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.