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".

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", or "zen:organization". For example, if you specify "zen:user", the field will list user records. You can't change the value of this property after creating the field
  • relationship_filter (optional) - A condition definition to filter the records that the field lists. 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

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", and "zen:organization"
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", and "zen:organization"

Using 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}

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), or organizations (zen:organization). The returned filter definitions are the options that you can use to build a custom field or ticket field's relationship_filter.

Parameters

Name Type In Required Description
target_type string Path true The target type for which you would like to see filter definitions. The options are "zen:user", "zen:ticket", and "zen:organization"

Using cURL

curl https://{subdomain}.zendesk.com/api/v2/relationships/definitions/zen:ticket.json \  -u {email_address}:{password}

Example Response(s)

200 OK
Status 200 OK
{  "definitions": {    "conditions_all": [      {        "group": "ticket",        "nullable": false,        "operators": [          {            "terminal": false,            "title": "Is",            "value": "is"          },          {            "terminal": false,            "title": "Is not",            "value": "is_not"          },          {            "terminal": false,            "title": "Less than",            "value": "less_than"          },          {            "terminal": false,            "title": "Greater than",            "value": "greater_than"          },          {            "terminal": true,            "title": "Changed",            "value": "changed"          },          {            "terminal": false,            "title": "Changed to",            "value": "value"          },          {            "terminal": false,            "title": "Changed from",            "value": "value_previous"          },          {            "terminal": true,            "title": "Not changed",            "value": "not_changed"          },          {            "terminal": false,            "title": "Not changed to",            "value": "not_value"          },          {            "terminal": false,            "title": "Not changed from",            "value": "not_value_previous"          }        ],        "repeatable": false,        "subject": "status",        "title": "Status",        "type": "list",        "values": [          {            "enabled": true,            "title": "New",            "value": "new"          },          {            "enabled": true,            "title": "Open",            "value": "open"          },          {            "enabled": true,            "title": "Pending",            "value": "pending"          },          {            "enabled": true,            "title": "Solved",            "value": "solved"          },          {            "enabled": true,            "title": "Closed",            "value": "closed"          }        ]      }    ],    "conditions_any": [      {        "group": "ticket",        "nullable": true,        "operators": [          {            "terminal": true,            "title": "Present",            "value": "present"          },          {            "terminal": true,            "title": "Not present",            "value": "not_present"          }        ],        "repeatable": false,        "subject": "custom_fields_20513432",        "title": "Happy Gilmore",        "type": "list"      },      {        "group": "ticket",        "nullable": true,        "operators": [          {            "terminal": true,            "title": "Present",            "value": "present"          },          {            "terminal": true,            "title": "Not present",            "value": "not_present"          }        ],        "repeatable": false,        "subject": "custom_fields_86492341",        "title": "total_time_field",        "type": "list"      }    ]  }}