Lookup Relationships

A lookup relationship field is a custom field whosetypeis "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, seeUsing lookup relationship fieldsin Zendesk help.

You can createdefinitionsthat 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".

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. SeeFiltering the field's optionsin Zendesk help andConditions reference

Using cURL

下面的示例创建一个查找停止外遇p ticket field that references users.

             
              旋度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 bytarget_typeandtarget_id) assigned as the 'Success Manager' (field referenced byfield_id)?"

Allowed For

Agents

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`旋度https://{subdomain}.zendesk.com/api/v2/zen:ticket/1234/relationship_fields/456/zen:user.json\-u{email_address}:{password}

              
               import("fmt""io""net/http")funcmain(){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)iferr!=nil{fmt.Println(err)return}req.Header.Add("Content-Type","application/json")req.Header.Add("Authorization","Basic ")// Base64 encoded "username:password"client:=&http.Client{}res,err:=client.Do(req)iferr!=nil{fmt.Println(err)return}deferres.Body.Close()body,err:=io.ReadAll(res.Body)iferr!=nil{fmt.Println(err)return}fmt.Println(string(body))}

Java

              
               importcom.squareup.okhttp.*;OkHttpClientclient=newOkHttpClient();HttpUrl.BuilderurlBuilder=HttpUrl.parse("https://example.zendesk.com/api/v2/zen:custom_object:apartment/1234/relationship_fields/1234/zen:custom_object:apartment").newBuilder();Requestrequest=newRequest.Builder().url(urlBuilder.build()).method("GET",null).addHeader("Content-Type","application/json").addHeader("Authorization",Credentials.basic("your-email","your-password")).build();Responseresponse=client.newCall(request).execute();

Nodejs

              
               varaxios=require('axios');varconfig={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 ',// Base64 encoded "username:password"},};axios(config).then(function(response){console.log(JSON.stringify(response.data));}).catch(function(error){console.log(error);});

Python

              
               importrequestsurl="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=('',''),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:truedo|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'srelationship_filter.