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

An object type consists of an object named data with the following properties.

Name Type Writable Required Comment
key string yes* yes A user-defined unique identifier. See key property. *Writable on create only
schema string yes yes A description of the object record, up to a maximum of 32 KB. See schema property
created_at date no no The time the object type was created
updated_at date no no The time of the last update of the object type
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.

Note: We plan to disallow property names prefixed with an underscore (`"_"`) and using the asterisk (`"*"`) as an attribute name in new schemas in the future. The underscore prefix will be reserved for internal use and the `"*"` will be used as a wildcard to enable a query for a value across all attributes. If you create a schema with such a property name before the restriction is enforced, you may not be able to search using that property. To avoid any possible future conflicts, please update any object type schemas that you created with such property names by renaming the property in the schema and in any records of that object type.

Example
{
  "data": {
    "key": "product",
    "schema": {
      "properties": {
        "id": {
          "type": "string",
          "description": "The unique identifier for a product"
        },
        "name": {
          "type": "string",
          "description": "The name of the product"
        }
      },
      "required": ["id", "name"]
    }
  }
}

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": [
    {
      "key": "product",
      "version": 1,
      "schema": {
        "properties": {
          "id": {
            "type": "string",
            "description": "product id"
          },
          "name": {
            "type": "string",
            "description": "product name"
          }
        },
        "required": ["id", "name"]
      },
      "created_at": "2018-01-01T10:20:30Z",
      "updated_at": "2018-01-01T10:20:30Z"
    },
    {
      "key": "user",
      "version": 2,
      "schema": {
        "properties": {
          "id": {
            "type": "string",
            "description": "user id"
          },
          "name": {
            "type": "string",
            "description": "user name"
          }
        },
        "required": ["id", "name"]
      },
      "created_at": "2018-01-01T10:20:30Z",
      "updated_at": "2018-01-01T10:20:30Z"
    },
    ...
  ]
}

Show Object Type

GET /api/sunshine/objects/types/{key}

Returns the object type with the specified key.

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

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

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 statement

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": {
    "key": "product",
    "schema": {
      "properties": {
        "id": {
          "type": "string",
          "description": "product id"
        },
        "name": {
          "type": "string",
          "description": "product name"
        }
      },
      "required": [
        "id",
        "name"
      ]
    },
    "created_at": "2019-01-01T10:20:30Z",
    "updated_at": "2019-01-01T10:20:30Z"
  }
}

Update Object Type

PUT /api/sunshine/objects/types/{key}

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".

Allowed For
  • Admins
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 statement

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": {
    "key": "product",
    "schema": {
      "properties": {
        "id": {
          "type": "string",
          "description": "product id"
        },
        "name": {
          "type": "string",
          "description": "product name"
        },
        "features": {
          "type": "string",
          "description": "product features"
        }
      },
      "required": [
        "id",
        "name"
      ]
    },
    "created_at": "2019-01-01T10:20:30Z",
    "updated_at": "2019-01-02T06:45:00Z"
  }
}

Delete Object Type

DELETE /api/sunshine/objects/types/{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
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