A relationship type defines a relationship between object records. The relationship type can be one-to-one, one-to-many, or many-to-many. For more information, see Relationship types in the Custom objects handbook.

A relationship type can't be updated. You must create a new one.

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

JSON Format

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

Name Type Read-only Mandatory Description
created_at string true false The time the relationship type was created
key string false true A user-defined unique identifier. See key property
source string false true The key of an object type. See source and target properties
target false true The key of a different object type. See source and target properties. It can be either a string or an array
updated_at string true false The time of the last update of the relationship type

key property

The key property is a unique identifier for the relationship type that you define yourself. The key must be between 2 and 32 characters long. Examples:

  • "product_has_one_product_category"
  • "product_has_many_users"
  • "stores_have_many_products"

source and target properties

The source and target properties of a relationship type define the relationship between two object records.

The source must be one of the following:

  • the key of an object type, or
  • a Zendesk object type such as "zen:user" or "zen:ticket". See Zendesk object types

The target type varies depending on whether you want to define a one-to-one or a one-to-many relationship type.

To define a one-to-one relationship type, the target must be one of the following:

  • the key of an object type, or
  • a Zendesk object type such as "zen:user" or "zen:ticket". See Zendesk object types

To define a one-to-many relationship type, the target must be an array with one string that represents the key of an object type or a Zendesk object type.

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.

The following example creates a one-to-many relationship type named "users" that allows each object record of type "product" to have zero or many object records of type "zen:user":

{  "data": {    "key": "users",    "source": "product",    "target": ["zen:user"]  }}

The following example creates a one-to-one relationship type named "manufacturer" that allows each object record of type "product" to have zero or one object record of type "manufacturer". The one-to-one relationship type is denoted by the lack of square brackets for the target attribute.

{  "data": {    "key": "manufacturer",    "source": "product",    "target": "manufacturer"  }}

Zendesk object types

You can create a relationship type that defines a relationship record between a user-defined object type and a Zendesk object type such as tickets or users.

The following are the predefined Zendesk object types:

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

Use the identifiers as the source or target of a relationship type. Example:

{  "data": {    "key": "product_has_many_tickets",    "source": "product",    "target": ["zen:ticket"]  }}

Example

{  "key": "manufacturer",  "source": "product",  "target": "manufacturer"}

List Relationship Types

  • GET /api/sunshine/relationships/types

Returns the account's relationship types.

Allowed For

  • Everyone

Using curl

curl https://{subdomain}.zendesk.com/api/sunshine/relationships/types \  -v -u {email_address}:{password}

Example Response

Status 200 OK
{  "data": [    {      "created_at": "2017-01-01T10:20:30Z",      "key": "manufacturer",      "source": "product",      "target": "manufacturer",      "updated_at": "2017-01-01T10:20:30Z"    }  ]}

Show Relationship Type

  • GET /api/sunshine/relationships/types/{relationship_type_key}

Returns the relationship type with the specified key.

Allowed For

  • Everyone

Parameters

Name Type In Required Description
relationship_type_key string Path true The key of the relationship type

Using curl

curl https://{subdomain}.zendesk.com/api/sunshine/relationships/types/{key} \  -v -u {email_address}:{password}

Example Response

Status 200 OK
{  "data": {    "created_at": "2017-01-01T10:20:30Z",    "key": "manufacturer",    "source": "product",    "target": "manufacturer",    "updated_at": "2017-01-01T10:20:30Z"  }}

Create Relationship Type

  • POST /api/sunshine/relationships/types

Creates a relationship type.

The new key is validated against existing relationship types. If a duplicate key is detected, the relationship type is not created.

Allowed For

  • Admins

Using curl

curl https://{subdomain}.zendesk.com/api/sunshine/relationships/types \  -d '{"data":{"key": "manufacturer", "source": "product", "target": "manufacturer"}}' \  -H "Content-Type: application/json" -X POST \  -v -u {email_address}:{password}

Example Response

Status 201 Created
{  "data": {    "created_at": "2017-01-01T10:20:30Z",    "key": "manufacturer",    "source": "product",    "target": "manufacturer",    "updated_at": "2017-01-01T10:20:30Z"  }}

Delete Relationship Type

  • DELETE /api/sunshine/relationships/types/{relationship_type_key}

Deletes the relationship type with the specified key.

You can only delete a relationship type if all relationship records created from the type have been deleted. See Delete Relationship Record.

Allowed For

  • Admins

Parameters

Name Type In Required Description
relationship_type_key string Path true The key of the relationship type

Using curl

curl https://{subdomain}.zendesk.com/api/sunshine/relationships/types/{key} \  -X DELETE \  -v -u {email_address}:{password}

Example Response

Status 204 No Content