Legacy relationship records create associations between legacy object records based on a pre-defined legacy relationship type. For more information, see Legacy Relationship Records in the Legacy custom objects handbook.

For example, a car rental company could create the following legacy relationship records after creating legacy object records for its locations and cars:

  • Associate the Minnesota Motors location to a specific Duesenberg car based on the pre-defined relationship type that specifies a rental location can have many cars

  • Associate the Duesenberg to a Zendesk user based on the pre-defined relationship type that specifies a car can be rented to many Zendesk users

Once created, a relationship record can't be modified because the relationship_type property of a relationship record has fundamental implications on how associations between two object records are stored.

JSON format

Relationships are represented as JSON objects with the following properties:

NameTypeRead-onlyMandatoryDescription
created_atstringtruefalseThe time the relationship record was created
idstringtruefalseAutomatically assigned when the legacy relationship record is created
relationship_typestringfalsetrueThe key of the legacy relationship type that defines the relationship record
sourcestringfalsetrueThe id of the legacy object record that's the source of the relationship
targetstringfalsetrueThe id of the legacy object record that's the target of the relationship.

Example

{  "created_at": "2019-01-01T10:20:30Z",  "id": "6ea29370-a224-11e7-b1f0-191589292d4f",  "relationship_type": "zen_users",  "source": "e5f3f5b2-536a-4f1d-bca2-985c454362bb",  "target": "zen:user:10002"}

List Legacy Relationship Records by Type

  • GET /api/sunshine/relationships/records?type={type}

Returns all the legacy relationship records of the specified relationship type. For the type, specify a legacy relationship type key.

The response includes a links object with "previous" and "next" url properties for pagination. See Pagination in the Zendesk v2 API documentation.

Allowed for

  • Everyone

Parameters

NameTypeInRequiredDescription
orderstringQueryfalseOrder of the items (by creation time). Default is ascending. Allowed values are "asc", or "desc".
per_pagestringQueryfalseNumber of items returned per page from 1 to 1000
typestringQuerytrueSee relationship type key

Code Samples

curl
curl https://{subdomain}.zendesk.com/api/sunshine/relationships/records?type={relationship_type} \  -v -u {email_address}/token:{api_token}
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://support.zendesk.com/api/sunshine/relationships/records?order=desc&per_page=1&type=zen_users"	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/records")		.newBuilder()		.addQueryParameter("order", "desc")		.addQueryParameter("per_page", "1")		.addQueryParameter("type", "zen_users");
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/records',  headers: {	'Content-Type': 'application/json',  },  params: {    'order': 'desc',    'per_page': '1',    'type': 'zen_users',  },};
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/records?order=desc&per_page=1&type=zen_users"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/records")uri.query = URI.encode_www_form("order": "desc", "per_page": "1", "type": "zen_users")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": "2019-01-01T10:20:30Z",      "id": "6ea29370-a224-11e7-b1f0-191589292d4f",      "relationship_type": "zen_users",      "source": "e5f3f5b2-536a-4f1d-bca2-985c454362bb",      "target": "zen:user:10002"    },    {      "created_at": "2019-01-01T10:20:35Z",      "id": "890dfe2f-a223-11e7-b1f0-4316e017a51a",      "relationship_type": "zen_users",      "source": "e5f3f5b2-536a-4f1d-bca2-985c454362bb",      "target": "zen:user:10002"    }  ],  "links": {    "next": null,    "previous": null  }}

List Legacy Relationship Records by Legacy Object Record

  • GET /api/sunshine/objects/records/{object_record_id}/relationships/{relationship_type_key}

The record id must be the legacy relationship record's source record id, not its target record id.

For example, a car rental company could be creating relationship records based on a relationship type that specifies that each car can be rented by many Zendesk users. The company could use the API to list the relationship records of a specific car -- in other words, to list the users who rented the car.

Each legacy relationship record in the response has the following properties:

  • id - the id of the relationship record
  • target - the id of the target legacy object record, which may be a custom or Zendesk object record
  • ref - the API url of the legacy target object record for the Show Legacy Object Record endpoint

In the example, the targets are users who rented the car.

The response also includes a links object with previous and next url properties for pagination. See Pagination in the Zendesk v2 API documentation.

Allowed for

  • Everyone

Parameters

NameTypeInRequiredDescription
orderstringQueryfalseOrder of the items (by creation time). Default is ascending. Allowed values are "asc", or "desc".
per_pagestringQueryfalseNumber of items returned per page from 1 to 1000
object_record_idstringPathtrueThe ID of the legacy object record
relationship_type_keystringPathtrueThe key of the legacy relationship type

Code Samples

curl
curl https://{subdomain}.zendesk.com/api/sunshine/objects/records/{object_record_id}/relationships/{relationship_type_key} \  -v -u {email_address}/token:{api_token}
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://support.zendesk.com/api/sunshine/objects/records/14c6c4be-cb64-4678-ba73-296e3d2c32cf/relationships/suppliers?order=desc&per_page=1"	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/objects/records/14c6c4be-cb64-4678-ba73-296e3d2c32cf/relationships/suppliers")		.newBuilder()		.addQueryParameter("order", "desc")		.addQueryParameter("per_page", "1");
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/objects/records/14c6c4be-cb64-4678-ba73-296e3d2c32cf/relationships/suppliers',  headers: {	'Content-Type': 'application/json',  },  params: {    'order': 'desc',    'per_page': '1',  },};
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/objects/records/14c6c4be-cb64-4678-ba73-296e3d2c32cf/relationships/suppliers?order=desc&per_page=1"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/objects/records/14c6c4be-cb64-4678-ba73-296e3d2c32cf/relationships/suppliers")uri.query = URI.encode_www_form("order": "desc", "per_page": "1")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": [    {      "id": "eae75774-18a6-448f-bca7-dda5c11bb125",      "ref": "/api/sunshine/objects/records/f2771449-861e-43f0-8936-e16c3bd492d2",      "target": "f2771449-861e-43f0-8936-e16c3bd492d2"    },    {      "id": "517e916a-7099-11e7-8cf7-a6006ad3dba0",      "ref": "/api/v2/users/849294839",      "target": "849294839"    }  ],  "links": {    "next": null,    "previous": null  }}

Show Legacy Relationship Record

  • GET /api/sunshine/relationships/records/{relationship_record_id}

Returns a legacy relationship record specified by id.

Allowed for

  • Everyone

Parameters

NameTypeInRequiredDescription
relationship_record_idstringPathtrueThe ID of the legacy relationship record

Code Samples

curl
curl https://{subdomain}.zendesk.com/api/sunshine/relationships/records/{id} \  -v -u {email_address}/token:{api_token}
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://support.zendesk.com/api/sunshine/relationships/records/eae75774-18a6-448f-bca7-dda5c11bb125"	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/records/eae75774-18a6-448f-bca7-dda5c11bb125")		.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/records/eae75774-18a6-448f-bca7-dda5c11bb125',  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/records/eae75774-18a6-448f-bca7-dda5c11bb125"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/records/eae75774-18a6-448f-bca7-dda5c11bb125")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": "2019-03-12T17:15:41.807Z",    "id": "1a034055-6485-11ea-a338-a7395da450f1",    "relationship_type": "zen_users",    "source": "fa6dec91-6484-11ea-a338-6d0d189da5e0",    "target": "fc7925e3-6484-11ea-a338-19eb2b9d27d1"  }}

Create Legacy Relationship Record

  • POST /api/sunshine/relationships/records

Creates a legacy relationship record between two object records based on a relationship type. The legacy relationship type defines the object types of the two object records.

You can create relationship records between two legacy custom object records, a legacy custom object record and a standard Zendesk object record, or two standard Zendesk object records.

Allowed for

  • Everyone

Code Samples

curl
curl https://{subdomain}.zendesk.com/api/sunshine/relationships/records \  -d '{"data": {"relationship_type": "zen_users", "source": "e5f3f5b2-536a-4f1d-bca2-985c454362bb", "target": "zen:user:10002"}}' \  -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/records"	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/records")		.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/records',  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/records"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/records")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": "2019-01-01T10:20:30Z",    "id": "eae75774-18a6-448f-bca7-dda5c11bb125",    "relationship_type": "zen_users",    "source": "e5f3f5b2-536a-4f1d-bca2-985c454362bb",    "target": "zen:user:10002"  }}

Delete Legacy Relationship Record

  • DELETE /api/sunshine/relationships/records/{relationship_record_id}

Deletes the specified legacy relationship record.

Allowed for

  • Everyone

Parameters

NameTypeInRequiredDescription
relationship_record_idstringPathtrueThe ID of the legacy relationship record

Code Samples

curl
curl https://{subdomain}.zendesk.com/api/sunshine/relationships/records/{id} \  -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/records/eae75774-18a6-448f-bca7-dda5c11bb125"	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/records/eae75774-18a6-448f-bca7-dda5c11bb125")		.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/records/eae75774-18a6-448f-bca7-dda5c11bb125',  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/records/eae75774-18a6-448f-bca7-dda5c11bb125"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/records/eae75774-18a6-448f-bca7-dda5c11bb125")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