Object Types

An object type is a blueprint for creating object records of the same type. You can design an object type for creating people, contracts, products, or anything else. For more information, see Object types in the Custom objects handbook.

You can control access to the object type definition and object records of the type by adjusting its policies.

JSON Format

Object Types are represented as JSON objects with the following properties:

Name Type Read-only Mandatory Description
created_at string true false The time the object type was created
key string true true A user-defined unique identifier. Writable on create only. See key property
schema object false true A description of the object record, up to a maximum of 32 KB. See schema property
updated_at string true false The time of the last update of the object type
version integer false false The version of this schema
key property

The key property is a unique identifier for the object type that you define yourself. The key must be between 2 and 32 characters long. Examples include "product", "cell_phone", and "2019-car".

schema property

The schema property describes the properties of the object records created from the type. It can also validate property values. The schema follows the JSON Schema specification. To learn more, see Creating a schema for a custom object in the Develop Help Center.

Zendesk applies the following schema validation rules: * Empty schemas - The schema and the properties properties cannot be empty.

  • Property naming rules - Any property in the schema has to conform to the following naming rules:

    • Property names cannot be prefixed with an "_" character.
    • "*" cannot be used as schema property name.
    • Property names cannot contain the following characters: "\b", "\f", "\n", "\r", "\t", "\u0007", "\u0013"
  • Mandating additionalProperties as false - The additionalProperties property is an immutable property added to all new JSON Schemas and set to false. Any schema containing additionalProperties set to true will encounter an 400 Bad Request error. The validation rule restricts the ability to create object records that contain non-schema attributes.

  • Supported types - The type property supports the following types: "boolean", "integer", "number", "string", and "array". The value of the type property cannot be set to an array of supported types. For example, ["string"] is an invalid type value. When defining an array, the items property must be present alongside defining the type property of the array. The type property of the array can be one of the following values "boolean", "integer", "number", "string".

  • Supported keywords - Custom objects support the following JSON Schema keywords: "title", "description", "properties", "type", "items", "required", and "additionalProperties". The improper placement of the supported properties can also result in a 400 Bad Request error.

You can use the Validate Object Types endpoint to validate the schema of your object types. The error messages returned by the endpoint are outlined in Schema validation reference for object types .

Example
{
  "created_at": "2020-04-24T23:47:19.000Z",
  "key": "product",
  "schema": {
    "properties": {
      "id": {
        "description": "The unique identifier for a product",
        "type": "string"
      },
      "name": {
        "description": "The name of the product",
        "type": "string"
      }
    },
    "required": [
      "id",
      "name"
    ]
  },
  "updated_at": "2020-04-24T23:47:19.000Z"
}

List Object Types

  • GET /api/sunshine/objects/types

Returns the account's object types. Zendesk object types such as "zen:user" are not included.

Allowed For
  • Everyone
Using curl
curl https://{subdomain}.zendesk.com/api/sunshine/objects/types \
  -v -u {email_address}:{password}
Example Response
Status 200 OK

{
  "data": [
    {
      "created_at": "2018-01-01T10:20:30Z",
      "key": "product",
      "schema": {
        "properties": {
          "id": {
            "description": "product id",
            "type": "string"
          },
          "name": {
            "description": "product name",
            "type": "string"
          }
        },
        "required": [
          "id",
          "name"
        ]
      },
      "updated_at": "2018-01-01T10:20:30Z",
      "version": 1
    },
    {
      "created_at": "2018-01-01T10:20:30Z",
      "key": "user",
      "schema": {
        "properties": {
          "id": {
            "description": "user id",
            "type": "string"
          },
          "name": {
            "description": "user name",
            "type": "string"
          }
        },
        "required": [
          "id",
          "name"
        ]
      },
      "updated_at": "2018-01-01T10:20:30Z",
      "version": 2
    }
  ]
}

Create Object Type

  • POST /api/sunshine/objects/types

Creates an object type describing the properties of the object records to be created of that type.

Allowed For
  • Admins
Using curl

For clarity, the example places the JSON in a separate file and imports it into the cURL statement.

resource_type.json

{
  "data": {
    "key": "product",
    "schema": {
      "properties": {
        "id": {
          "type": "string",
          "description": "product id"
        },
        "name": {
          "type": "string",
          "description": "product name"
        }
      },
      "required": [
        "id",
        "name"
      ]
    }
  }
}

curl snippet

curl https://{subdomain}.zendesk.com/api/sunshine/objects/types \
  -d @resource_type.json \
  -H "Content-Type: application/json" -X POST \
  -v -u {email_address}:{password}
Example Response
Status 201 Created

{
  "data": {
    "created_at": "2018-01-01T10:20:30Z",
    "key": "product",
    "schema": {
      "properties": {
        "id": {
          "description": "product id",
          "type": "string"
        },
        "name": {
          "description": "product name",
          "type": "string"
        }
      },
      "required": [
        "id",
        "name"
      ]
    },
    "updated_at": "2018-01-01T10:20:30Z"
  }
}

Validate Object Types

  • GET /api/sunshine/objects/types/schema/report

Validates and generates a report of all the object types in the account. The report is based on the latest validations rules that have been implemented.

Allowed For
  • Admins
Using curl
curl https://{subdomain}.zendesk.com/api/sunshine/objects/types/schema/report/ \
  -X GET \
  -v -u {email_address}:{password}
Example Response
Status 200 OK

{
  "data": [
    {
      "message": [
        "The properties element of a schema cannot be empty."
      ],
      "object_type_key": "empty_schema_type"
    },
    {
      "message": [
        "data.schema instance value (\"object\") not found in enum (possible values: [\"boolean\",\"integer\",\"number\",\"string\",\"array\"])",
        "Invalid property name '_nested': Property name cannot start with '_'."
      ],
      "object_type_key": "nested_schema"
    }
  ]
}

Show Object Type

  • GET /api/sunshine/objects/types/{object_type_key}

Returns the object type with the specified key.

Allowed For
  • Everyone
Parameters
Name Type In Required Description
object_type_key string Path true The key property is a unique identifier for the object type that you define yourself
Using curl
curl https://{subdomain}.zendesk.com/api/sunshine/objects/types/{key} \
  -v -u {email_address}:{password}
Example Response
Status 200 OK

{
  "data": {
    "created_at": "2018-01-01T10:20:30Z",
    "key": "product",
    "schema": {
      "properties": {
        "id": {
          "description": "product id",
          "type": "string"
        },
        "name": {
          "description": "product name",
          "type": "string"
        }
      },
      "required": [
        "id",
        "name"
      ]
    },
    "updated_at": "2018-01-01T10:20:30Z"
  }
}

Update Object Type

  • PUT /api/sunshine/objects/types/{object_type_key}

Object type updating rules:

  • Updates the schema property of an object type. It does not update the key.

  • Include the full, updated object type in the request.

  • Even though you can only update one property, this is a PUT endpoint, not a PATCH one.

  • You can't update a Zendesk object type. For example, the key in the request path can't be "zen:user:123".

Object type schema updating rules:

  • Updating the type property of any schema properties is not supported.

  • Deleting schema properties is not supported.

Allowed For
  • Admins
Parameters
Name Type In Required Description
object_type_key string Path true The key property is a unique identifier for the object type that you define yourself
Using curl

For clarity, the example places the JSON in a separate file and imports it into the cURL statement.

updated_resource_type.json

{
  "data": {
    "schema": {
      "properties": {
        "id": {
          "type": "string",
          "description": "product id"
        },
        "name": {
          "type": "string",
          "description": "product name"
        },
        "features": {
          "type": "string",
          "description": "product features"
        }
      },
      "required": [
        "id",
        "name"
      ]
    }
  }
}

curl snippet

curl https://{subdomain}.zendesk.com/api/sunshine/objects/types/{key} \
-d @updated_resource_type.json \
-H "Content-Type: application/json" -X PUT \
-v -u {email_address}:{password}
Example Response
Status 200 OK

{
  "data": {
    "created_at": "2019-01-01T10:20:30Z",
    "key": "product",
    "schema": {
      "properties": {
        "features": {
          "description": "product features",
          "type": "string"
        },
        "id": {
          "description": "product id",
          "type": "string"
        },
        "name": {
          "description": "product name",
          "type": "string"
        }
      },
      "required": [
        "id",
        "name"
      ]
    },
    "updated_at": "2019-01-02T06:45:00Z"
  }
}

Delete Object Type

  • DELETE /api/sunshine/objects/types/{object_type_key}

Deletes the object type with the specified key.

You can only delete an object type if all object records created from the type have been deleted. See Delete Object Record.

Allowed For
  • Admins
Parameters
Name Type In Required Description
object_type_key string Path true The key property is a unique identifier for the object type that you define yourself
Using curl
curl https://{subdomain}.zendesk.com/api/sunshine/objects/types/{key} \
  -X DELETE \
  -v -u {email_address}:{password}
Example Response
Status 204 No Content