DocumentationAPI Reference

Retrieving lookup relationship data with the API

A lookup relationship field is a type of custom field that Zendesk admins can add to users, organizations, tickets, or custom objects in Zendesk. After adding a lookup relationship field, team members can use it to establish relationships with other users, organizations, tickets, or custom objects. To learn more, see Using lookup relationship fields in Zendesk help and Lookup Relationships in the API reference documentation.

Understanding lookup relationships

A lookup relationship consists of a source record and a target record. The relationship can be expressed as follows:

source record -> target record

The source record can be a user, organization, ticket, or custom object. The target record can be a different user, organization, ticket, or custom object.

All relationships are one-way. For example, if you create a relationship between a source ticket and a related user, the ticket record will have a lookup relationship field identifying the user. However, the corresponding user record will not have a field identifying the ticket.

Listing source records associated with a target record

You can use the API to list the source records associated to a specific target record in a lookup relationship. For example, you can request a list of all tickets related to a specific user.

To list the source records associated to a specific target user, organization, ticket, or custom object record

  • Make a request to the Get Sources by Target endpoint:

    https:/{subdomain}.zendesk.com/api/v2/{target_type}/{target_id}/relationship_fields/{field_id}/{source_type}

    Specify the following query parameters in the request:

    • target_type - the type of the related object. Possible values are "zen:user", "zen:organization", "zen:ticket", and "zen:custom_object:CUSTOM_OBJECT_KEY".

    • target_id - the id of the specific related user, organization, or ticket. You can get the id from the API or from the URL of the object's page in the Zendesk interface.

    • field_id - the id of the lookup relationship field. You can get the id from the API or from the URL of the custom field's page in the Zendesk interface. In the following example, the field id is 6498722764059:

    • source_type - the type of the source object. Possible values are "zen:user", "zen:organization", "zen:ticket", and "zen:custom_object:CUSTOM_OBJECT_KEY".

Example

Suppose the Organizations page in Zendesk has a lookup relationship field that lists account managers. Team members use the field to associate an internal account manager to each organization.

The following API request in Postman lists all the organizations associated to a specific account manager. It returns a list of organizations (source_type of "zen:organization") with a lookup relationship field of account_managers (field_id of 6436064572443). The organizations in the response are all related to a specific account manager defined by a target_type of "zen:user" and a target_id of 1262482787270, which is a normal Zendesk user id.

For more information about using Postman, see Exploring Zendesk APIs with Postman.

The same request in curl looks as follows:

curl 'https://{subdomain}.zendesk.com/api/v2/zen:user/1262482787270/relationship_fields/6436064572443/zen:organization'  -v -u {email_address}/token:{api_token}