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
Relationships are represented as JSON objects with the following properties:
Name | Type | Read-only | Mandatory | Description |
---|---|---|---|---|
created_at | string | true | false | The time the relationship record was created |
id | string | true | false | Automatically assigned when the relationship record is created |
relationship_type | string | false | true | The key of the relationship type that defines the relationship record |
source | string | false | true | The id of the object record that's the source of the relationship |
target | string | false | true | The id of the object record that's the target of the relationship. |
Example
{
"created_at": "2019-01-01T10:20:30Z",
"id": "6ea29370-a224-11e7-b1f0-191589292d4f",
"relationship_type": "zen_users",
"source": "e5f3f5b2-536a-4f1d-bca2-985c454362bb",
"target": "zen:user:10002"
}
List Relationship Records by Type
GET /api/sunshine/relationships/records?type={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
Name | Type | In | Required | Description |
---|---|---|---|---|
order | string | Query | false | Order of the items (by creation time). Default is ascending. Allowed values are "asc", or "desc". |
per_page | string | Query | false | Number of items returned per page from 1 to 1000 |
type | string | Query | true | See relationship type key |
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": [
{
"created_at": "2019-01-01T10:20:30Z",
"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:35Z",
"id": "890dfe2f-a223-11e7-b1f0-4316e017a51a",
"relationship_type": "zen_users",
"source": "e5f3f5b2-536a-4f1d-bca2-985c454362bb",
"target": "zen:user:10002"
}
],
"links": {
"next": null,
"previous": null
}
}
List Relationship Records by Object Record
GET /api/sunshine/objects/records/{object_record_id}/relationships/{relationship_type_key}
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 recordtarget
- the id of the target object record, which may be a custom or Zendesk object recordref
- 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
Name | Type | In | Required | Description |
---|---|---|---|---|
order | string | Query | false | Order of the items (by creation time). Default is ascending. Allowed values are "asc", or "desc". |
per_page | string | Query | false | Number of items returned per page from 1 to 1000 |
object_record_id | string | Path | true | The ID of the object record |
relationship_type_key | string | Path | true | The key of the relationship type |
Using curl
curl https://{subdomain}.zendesk.com/api/sunshine/objects/records/{object_record_id}/relationships/{relationship_type_key} \
-v -u {email_address}:{password}
Example Response
Status 200 OK
{
"data": [
{
"id": "eae75774-18a6-448f-bca7-dda5c11bb125",
"ref": "/api/sunshine/objects/records/f2771449-861e-43f0-8936-e16c3bd492d2",
"target": "f2771449-861e-43f0-8936-e16c3bd492d2"
},
{
"id": "517e916a-7099-11e7-8cf7-a6006ad3dba0",
"ref": "/api/v2/users/849294839",
"target": "849294839"
}
],
"links": {
"next": null,
"previous": null
}
}
Show Relationship Record
GET /api/sunshine/relationships/records/{relationship_record_id}
Returns a relationship record specified by id.
Allowed For
- Everyone
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
relationship_record_id | string | Path | true | The ID of the relationship record |
Using curl
curl https://{subdomain}.zendesk.com/api/sunshine/relationships/records/{id} \
-v -u {email_address}:{password}
Example Response
Status 200 OK
{
"data": {
"created_at": "2019-03-12T17:15:41.807Z",
"id": "1a034055-6485-11ea-a338-a7395da450f1",
"relationship_type": "zen_users",
"source": "fa6dec91-6484-11ea-a338-6d0d189da5e0",
"target": "fc7925e3-6484-11ea-a338-19eb2b9d27d1"
}
}
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": {
"created_at": "2019-01-01T10:20:30Z",
"id": "eae75774-18a6-448f-bca7-dda5c11bb125",
"relationship_type": "zen_users",
"source": "e5f3f5b2-536a-4f1d-bca2-985c454362bb",
"target": "zen:user:10002"
}
}
Delete Relationship Record
DELETE /api/sunshine/relationships/records/{relationship_record_id}
Deletes the specified relationship record.
Allowed For
- Everyone
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
relationship_record_id | string | Path | true | The ID of the relationship record |
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