Relationship Records

Relationship records create associations between object records based on a pre-defined relationship type. For more information, see Relationship Records in the Custom objects handbook.

For example, a car rental company could create the following relationship records after creating object records for its locations and cars:

  • Associate the Minnesota Motors location to a specific Duesenberg car based on the pre-defined relationship type that specifies a rental location can have many cars

  • Associate the Duesenberg to a Zendesk user based on the pre-defined relationship type that specifies a car can be rented to many Zendesk users

Once created, a relationship record can't be modified because the relationship_type property of a relationship record has fundamental implications on how associations between two object records are stored.

JSON Format

A relationship record consists of an object named data with the following properties.

Name Type Writable Required Comment
id string no no Automatically assigned when the relationship record is created
relationship_type string yes yes The key of the relationship type that defines the relationship record
source string yes yes The id of the object record that's the source of the relationship
target string or array yes yes The id of the object record that's the target of the relationship
ref string no no API url of the target object record
created_at date no no The time the relationship record was created

The relationship_type property defines the valid object types of the target and source object records.

Example
{
  "data": {
    "relationship_type": "users",
    "source": "1c771ee0-2c3f-11e7-bf60-e5c3f630b5aa",
    "target": "zen:user:35437746"
  }
}

List Relationship Records by Object Record

GET /api/sunshine/objects/records/{id}/relationships/{relationship_type}

Returns the relationship records of a specified relationship type for a specified object record. For the type, specify a relationship type key. For the object record id, specify a custom object record id or a Zendesk object record id. Use the following format for a Zendesk object record id: zen:{object}:{id}. Example:

GET /api/sunshine/objects/records/zen:ticket:234567/relationships/suppliers

The record id must be the relationship record's source record id, not its target record id.

For example, a car rental company could be creating relationship records based on a relationship type that specifies that each car can be rented by many Zendesk users. The company could use the API to list the relationship records of a specific car -- in other words, to list the users who rented the car.

Each relationship record in the response has the following properties:

  • id - the id of the relationship record
  • target - the id of the target object record, which may be a custom or Zendesk object record
  • ref - the API url of the target object record for the Show Object Record endpoint

In the example, the targets are users who rented the car.

The response also includes a links object with previous and next url properties for pagination. See Pagination in the Zendesk v2 API documentation.

Allowed For
  • Everyone
Parameters

You can use the following optional query string parameters:

Name Type Comment
per_page string Number of relationship records per page from 1 to 1000
order string Order of relationship records (by creation time). Default is ascending. Allowed value: "desc"
Using cURL
curl https://{subdomain}.zendesk.com/api/sunshine/objects/records/{id}/relationships/{relationship_type} \
  -v -u {email_address}:{password}
Example Response
Status: 200 OK

{
  "data": [
    {
      "id": "eae75774-18a6-448f-bca7-dda5c11bb125",
      "target": "f2771449-861e-43f0-8936-e16c3bd492d2",
      "ref": "/api/sunshine/objects/records/f2771449-861e-43f0-8936-e16c3bd492d2"
    },
    {
      "id": "517e916a-7099-11e7-8cf7-a6006ad3dba0",
      "target": "849294839",
      "ref": "/api/v2/users/849294839"
    }
  ],
  "links": {
    "previous": null,
    "next": null
  }
}

List Relationship Records by Type

GET /api/sunshine/relationships/records?type={relationship_type}

Returns all the relationship records of the specified relationship type. For the type, specify a relationship type key.

The response includes a links object with "previous" and "next" url properties for pagination. See Pagination in the Zendesk v2 API documentation.

Allowed For
  • Everyone
Parameters

You can use the following optional query string parameters:

Name Type Comment
per_page string Number of relationship records per page from 1 to 1000
order string Order of relationship records (by creation time). Default is ascending. Allowed value: "desc"
Using cURL
curl https://{subdomain}.zendesk.com/api/sunshine/relationships/records?type={relationship_type} \
  -v -u {email_address}:{password}
Example Response
Status: 200 OK

{
  "data": [
    {
      "id": "6ea29370-a224-11e7-b1f0-191589292d4f",
      "relationship_type": "zen_users",
      "source": "e5f3f5b2-536a-4f1d-bca2-985c454362bb",
      "target": "zen:user:10002",
      "created_at": "2019-01-01T10:20:30Z"
    },
    {
      "id": "890dfe2f-a223-11e7-b1f0-4316e017a51a",
      "relationship_type": "zen_users",
      "source": "e5f3f5b2-536a-4f1d-bca2-985c454362bb",
      "target": "zen:user:10002",
      "created_at": "2019-01-01T10:20:35Z"
    }
  ],
  "links": {
    "previous": null,
    "next": null
  }
}

Show Relationship Record by ID

GET /api/sunshine/relationships/records/{id}

Returns a relationship record specified by id.

Allowed For
  • Everyone
Using cURL
curl https://{subdomain}.zendesk.com/api/sunshine/relationships/records/{id} \
  -v -u {email_address}:{password}
Example Response
{
  "data": {
    "id": "1a034055-6485-11ea-a338-a7395da450f1",
    "relationship_type": "zen_users",
    "source": "fa6dec91-6484-11ea-a338-6d0d189da5e0",
    "target": "fc7925e3-6484-11ea-a338-19eb2b9d27d1",
    "created_at": "2019-03-12T17:15:41.807Z"
  }
}

Create Relationship Record

POST /api/sunshine/relationships/records

Creates a relationship record between two object records based on a relationship type. The relationship type defines the object types of the two object records.

You can create relationship records between two custom object records, a custom object record and a Zendesk object record, or two Zendesk object records.

Allowed For
  • Everyone
Using cURL
curl https://{subdomain}.zendesk.com/api/sunshine/relationships/records \
  -d '{"data": {"relationship_type": "zen_users", "source": "e5f3f5b2-536a-4f1d-bca2-985c454362bb", "target": "zen:user:10002"}}' \
  -H "Content-Type: application/json" -X POST \
  -v -u {email_address}:{password}
Example Response
Status: 201 Created

{
  "data": {
    "id": "eae75774-18a6-448f-bca7-dda5c11bb125",
    "relationship_type": "zen_users",
    "source": "e5f3f5b2-536a-4f1d-bca2-985c454362bb",
    "target": "zen:user:10002",
    "created_at": "2019-01-01T10:20:30Z"
  }
}

Delete Relationship Record

DELETE /api/sunshine/relationships/records/{id}

Deletes the specified relationship record.

Allowed For
  • Everyone
Using cURL
curl https://{subdomain}.zendesk.com/api/sunshine/relationships/records/{id} \
  -X DELETE \
  -v -u {email_address}:{password}
Example Response
Status: 204 No Content