Important: The Lookup Relationships API is in early access. This API is subject to change and should not be used in a production environment. Complete the Lookup Relationship Field EAP registration form to start using it.

A lookup relationship field is a custom field whose type is "lookup". This type of custom field provides 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.

With lookup relationship fields, you can create definitions that specify what type of objects will show up in the autocomplete endpoints when populating the field. Note that the filter is not used to validate the relationship, only as a convenience to filter down the types of 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

The following fields are for creating a lookup relationship field for either a ticket field or a user or organization field:

  • (required) type needs to be "lookup"
  • (required) relationship_target_type needs to be: "zen:user", "zen:ticket", or "zen:organization". Note that the value of this field cannot be changed after field creation.
  • (optional) relationship_filter. Refer to filter definitions for more information.

The relationship_target_type field specifies the object type that you can store. For example, if you specify "zen:user", this field references user objects.

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

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

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"      }    ]  }}