Legacy Relationship Types

A legacy 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 Legacy relationship types in the Legacy 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 legacy relationship type was created
key	string	false	true	A user-defined unique identifier. See key property
source	string	false	true	The key of a legacy object type. See source and target properties
target		false	true	The key of a different legacy 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 legacy relationship type

key property

The key property is a unique identifier for the legacy 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 a legacy custom 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 a legacy custom 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 a legacy custom 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 legacy custom 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 legacy 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 legacy relationship type that defines a relationship record between a legacy custom object type and a standard 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 Legacy Relationship Types

• GET /api/sunshine/relationships/types

Returns the account's legacy relationship types.

Allowed for

• Everyone

Code Samples

curl

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

Go

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://support.zendesk.com/api/sunshine/relationships/types"
	method := "GET"
	req, err := http.NewRequest(method, url, nil)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Content-Type", "application/json")

	client := &http.Client {}
	res, err := client.Do(req)
	if err != nil {
		fmt.Println(err)
		return
	}
	defer res.Body.Close()

	body, err := io.ReadAll(res.Body)
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(string(body))
}

Java

import com.squareup.okhttp.*;
OkHttpClient client = new OkHttpClient();
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://support.zendesk.com/api/sunshine/relationships/types")
		.newBuilder();

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("GET", null)
		.addHeader("Content-Type", "application/json")
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');

var config = {
  method: 'GET',
  url: 'https://support.zendesk.com/api/sunshine/relationships/types',
  headers: {
	'Content-Type': 'application/json',
  },
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

Python

import requests

url = "https://support.zendesk.com/api/sunshine/relationships/types"
headers = {
	"Content-Type": "application/json",
}

response = requests.request(
	"GET",
	url,
	headers=headers
)

print(response.text)

Ruby

require "net/http"
uri = URI("https://support.zendesk.com/api/sunshine/relationships/types")
request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

Example response(s)

200 OK

// 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 Legacy Relationship Type

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

Returns the legacy 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 legacy relationship type

Code Samples

curl

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

Go

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://support.zendesk.com/api/sunshine/relationships/types/suppliers"
	method := "GET"
	req, err := http.NewRequest(method, url, nil)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Content-Type", "application/json")

	client := &http.Client {}
	res, err := client.Do(req)
	if err != nil {
		fmt.Println(err)
		return
	}
	defer res.Body.Close()

	body, err := io.ReadAll(res.Body)
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(string(body))
}

Java

import com.squareup.okhttp.*;
OkHttpClient client = new OkHttpClient();
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://support.zendesk.com/api/sunshine/relationships/types/suppliers")
		.newBuilder();

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("GET", null)
		.addHeader("Content-Type", "application/json")
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');

var config = {
  method: 'GET',
  url: 'https://support.zendesk.com/api/sunshine/relationships/types/suppliers',
  headers: {
	'Content-Type': 'application/json',
  },
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

Python

import requests

url = "https://support.zendesk.com/api/sunshine/relationships/types/suppliers"
headers = {
	"Content-Type": "application/json",
}

response = requests.request(
	"GET",
	url,
	headers=headers
)

print(response.text)

Ruby

require "net/http"
uri = URI("https://support.zendesk.com/api/sunshine/relationships/types/suppliers")
request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

Example response(s)

200 OK

// 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 Legacy Relationship Type

• POST /api/sunshine/relationships/types

Creates a legacy relationship type.

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

Allowed for

• Admins

Code Samples

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}/token:{api_token}

Go

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://support.zendesk.com/api/sunshine/relationships/types"
	method := "POST"
	req, err := http.NewRequest(method, url, nil)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Content-Type", "application/json")

	client := &http.Client {}
	res, err := client.Do(req)
	if err != nil {
		fmt.Println(err)
		return
	}
	defer res.Body.Close()

	body, err := io.ReadAll(res.Body)
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(string(body))
}

Java

import com.squareup.okhttp.*;
OkHttpClient client = new OkHttpClient();
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://support.zendesk.com/api/sunshine/relationships/types")
		.newBuilder();
RequestBody body = RequestBody.create(MediaType.parse("application/json"),
		"""
""");

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("POST", body)
		.addHeader("Content-Type", "application/json")
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');

var config = {
  method: 'POST',
  url: 'https://support.zendesk.com/api/sunshine/relationships/types',
  headers: {
	'Content-Type': 'application/json',
  },
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

Python

import requests

url = "https://support.zendesk.com/api/sunshine/relationships/types"
headers = {
	"Content-Type": "application/json",
}

response = requests.request(
	"POST",
	url,
	headers=headers
)

print(response.text)

Ruby

require "net/http"
uri = URI("https://support.zendesk.com/api/sunshine/relationships/types")
request = Net::HTTP::Post.new(uri, "Content-Type": "application/json")
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

Example response(s)

201 Created

// 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 Legacy Relationship Type

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

Deletes the legacy relationship type with the specified key.

You can only delete a legacy relationship type if all legacy 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 legacy relationship type

Code Samples

curl

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

Go

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://support.zendesk.com/api/sunshine/relationships/types/suppliers"
	method := "DELETE"
	req, err := http.NewRequest(method, url, nil)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Content-Type", "application/json")

	client := &http.Client {}
	res, err := client.Do(req)
	if err != nil {
		fmt.Println(err)
		return
	}
	defer res.Body.Close()

	body, err := io.ReadAll(res.Body)
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(string(body))
}

Java

import com.squareup.okhttp.*;
OkHttpClient client = new OkHttpClient();
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://support.zendesk.com/api/sunshine/relationships/types/suppliers")
		.newBuilder();

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("DELETE", null)
		.addHeader("Content-Type", "application/json")
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');

var config = {
  method: 'DELETE',
  url: 'https://support.zendesk.com/api/sunshine/relationships/types/suppliers',
  headers: {
	'Content-Type': 'application/json',
  },
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

Python

import requests

url = "https://support.zendesk.com/api/sunshine/relationships/types/suppliers"
headers = {
	"Content-Type": "application/json",
}

response = requests.request(
	"DELETE",
	url,
	headers=headers
)

print(response.text)

Ruby

require "net/http"
uri = URI("https://support.zendesk.com/api/sunshine/relationships/types/suppliers")
request = Net::HTTP::Delete.new(uri, "Content-Type": "application/json")
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

Example response(s)

204 No Content

// Status 204 No Content

null