Lookup Relationships

A lookup relationship field is a custom field whose type is "lookup". This type of custom field gives you the ability to create a relationship from a source object to a target object. One example is a ticket lookup field called "Success Manager" that references a user. The source object is a ticket and the target object is a user. To learn more, see Using lookup relationship fields in Zendesk help.

You can create definitions that specify what type of objects will show up in the autocomplete endpoints when populating the field. The filter is not used to validate the relationship; it's used as a convenience to filter the target records that you want to see. For example, if your field was "Success Manager", you could define a filter that says "only show users who are agents".

Setting lookup field values

To set by id, provide the target record's id. Example: "my_lookup_field": "123".
To set by external id, provide an external id prefixed with the string external_id:. Example: "my_lookup_field": "external_id:ABCDE". Note: The external id is used to retrieve the target record and then the id is stored as the lookup field value.

Creating lookup relationship fields

Use the following endpoints to create lookup relationship fields for tickets, users, and organizations:

Set the following properties to create a lookup relationship field:

type (required) - Must be "lookup"
relationship_target_type (required) - The object type that you want to store. One of "zen:user", "zen:ticket", "zen:organization", or "zen:custom_object:CUSTOM_OBJECT_KEY". For example "zen:user" will list user records or "zen:custom_object:apartment" will list apartment records. You can't change the value of this property after creating the field
relationship_filter (optional) - A condition that defines a subset of records as the options in your lookup relationship field. See Filtering the field's options in Zendesk help and Conditions reference

Using cURL

The following example creates a lookup relationship ticket field that references users.

curl https://{subdomain}.zendesk.com/api/v2/ticket_fields.json \  --data-raw '{      "ticket_field": {          "type": "lookup",          "title": "Success Manager",          "relationship_target_type": "zen:user",          "relationship_filter": {              "all":[                  {"field":"role","operator":"is","value":"Agent"}              ]          }      }  }'  -H "Content-Type: application/json" -X POST \  -v -u {email_address}:{password}

Get sources by target

GET /api/v2/{target_type}/{target_id}/relationship_fields/{field_id}/{source_type}

Returns a list of source objects whose values are populated with the id of a related target object. For example, if you have a lookup field called "Success Manager" on a ticket, this endpoint can answer the question, "What tickets (sources) is this user (found by target_type and target_id) assigned as the 'Success Manager' (field referenced by field_id)?"

Allowed For

Agents

Pagination

Cursor pagination (recommended)
Offset pagination

See Pagination.

Parameters

Name	Type	In	Required	Description
field_id	integer	Path	true	The id of the lookup relationship field
source_type	string	Path	true	The type of object the relationship field belongs to (example. ticket field belongs to a ticket object). The options are "zen:user", "zen:ticket", "zen:organization", and "zen:custom_object:CUSTOM_OBJECT_KEY"
target_id	integer	Path	true	The id of the object the relationship field is targeting
target_type	string	Path	true	The type of object the relationship field is targeting. The options are "zen:user", "zen:ticket", "zen:organization", and "zen:custom_object:CUSTOM_OBJECT_KEY"

Code Samples

cURL

# Find users whose lookup relationship field of id `456` refer to ticket with id `1234`curl https://{subdomain}.zendesk.com/api/v2/zen:ticket/1234/relationship_fields/456/zen:user.json \  -u {email_address}:{password}

import (	"fmt"	"io"	"net/http")
func main() {	url := "https://example.zendesk.com/api/v2/zen:custom_object:apartment/1234/relationship_fields/1234/zen:custom_object:apartment"	method := "GET"	req, err := http.NewRequest(method, url, nil)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "username:password"
	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://example.zendesk.com/api/v2/zen:custom_object:apartment/1234/relationship_fields/1234/zen:custom_object:apartment")		.newBuilder();
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("GET", null)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))		.build();Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');
var config = {  method: 'GET',  url: 'https://example.zendesk.com/api/v2/zen:custom_object:apartment/1234/relationship_fields/1234/zen:custom_object:apartment',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});

Python

import requests
url = "https://example.zendesk.com/api/v2/zen:custom_object:apartment/1234/relationship_fields/1234/zen:custom_object:apartment"headers = {	"Content-Type": "application/json",}
response = requests.request(	"GET",	url,	auth=('<username>', '<password>'),	headers=headers)
print(response.text)

Ruby

require "net/http"uri = URI("https://example.zendesk.com/api/v2/zen:custom_object:apartment/1234/relationship_fields/1234/zen:custom_object:apartment")request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")request.basic_auth "username", "password"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
{  "users": [    {      "id": 223443,      "name": "Johnny Agent"    },    {      "id": 8678530,      "name": "James A. Rosen"    }  ]}

Filter Definitions

GET /api/v2/relationships/definitions/{target_type}

Returns filter definitions based on the given target type. Target types include users (zen:user), tickets (zen:ticket), organizations (zen:organization), or custom objects (zen:custom_object:CUSTOM_OBJECT_KEY). The returned filter definitions are the options that you can use to build a custom field or ticket field's relationship_filter.