Relationship Types

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

A relationship 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
source string yes yes The key of an object type. See source and target properties
target string or array yes yes The key of a different object type. See source and target properties
created_at date no no The time the relationship type was created
updated_at date no no The time of the last update of the relationship type
Example
{
  "data": {
    "key": "manufacturer",
    "source": "product",
    "target": "manufacturer"
  }
}
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"]
  }
}

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": [
    {
      "key": "manufacturer",
      "source": "product",
      "target": "manufacturer",
      "created_at": "2017-01-01T10:20:30Z",
      "updated_at": "2017-01-01T10:20:30Z"
    },
    {
      ...
    }
  ]
}

Show Relationship Type

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

Returns the relationship type with the specified key.

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

{
  "data": {
    "key": "manufacturer",
    "source": "product",
    "target": "manufacturer",
    "created_at": "2017-01-01T10:20:30Z",
    "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": {
    "key": "manufacturer",
    "source": "product",
    "target": "manufacturer",
    "created_at": "2017-01-01T10:20:30Z",
    "updated_at": "2017-01-01T10:20:30Z"
  }
}

Delete Relationship Type

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