Object Records

Custom object records are created from an object type that you define. Your object records are stored in the Zendesk infrastructure. For more information, see Object Records in the Custom objects handbook.

Object records are validated against the object type schema.

You can define associations between different object records with relationship records.

JSON Format

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

Name Type Writable Required Comment
id string no no Automatically assigned when the object record is created
type string yes* yes The object type key. *Writable on create only
attributes object yes yes The data for the object record, up to a maximum of 32 KB. The object properties are defined in the schema of the type
external_id string yes* no A unique, case-insensitive identifier for the object record, usually from another system. *Writable on create only
created_at date no no The time the object record was created
updated_at date no no The time of the last update of the object record

The created_at and updated_at properties may not match exactly due to rounding of the updated_at timestamp.

Example
{
  "data": {
    "type": "product",
    "attributes": {
      "id": "3b0ff066-e8ec-11e6-bf01-fe55135034f3",
      "name": "Standing Desk"
    }
  }
}

List Object Records by Type

GET /api/sunshine/objects/records?type={object_type}

Returns object records by object type key.

Allowed For
  • Everyone
Parameters

If listing object records by object type key, you can use the following optional query string parameters:

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

{
  "data": [
    {
      "id": "14c6c4be-cb64-4678-ba73-296e3d2c32cf",
      "type": "product",
      "type_version": 1,
      "external_id": "3",
      "attributes": {
        "id": "3",
        "name": "Strawberry Chewing Gum"
      },
      "created_at": "2017-01-03T12:35:45Z",
      "updated_at": "2017-01-03T12:35:45Z"
    },
    {
      "id": "d07b6206-1ea1-43c4-ae68-ef743aa36169",
      "type": "product",
      "type_version": 1,
      "external_id": "4",
      "attributes": {
        "id": "4",
        "name": "Coffee Chewing Gum"
      },
      "created_at": "2017-01-03T12:35:45Z",
      "updated_at": "2017-01-03T12:35:45Z"
    }
  ],
  "links": {
    "previous": null,
    "next": null
  }
}

List Object Records by Id

GET /api/sunshine/objects/records?ids={id, id, ...}

Returns object records by object record ids.

Allowed For
  • Everyone
Using cURL
curl https://{subdomain}.zendesk.com/api/sunshine/objects/records?ids=14c6c4be-cb64-4678-ba73-296e3d2c32cf,4 \
  -v -u {email_address}:{password}
Example Response
Status: 200 OK

{
  "data": [
    {
      "id": "14c6c4be-cb64-4678-ba73-296e3d2c32cf",
      "type": "product",
      "type_version": 1,
      "external_id": "3",
      "attributes": {
        "id": "3",
        "name": "Strawberry Chewing Gum"
      },
      "created_at": "2017-01-03T12:35:45Z",
      "updated_at": "2017-01-03T12:35:45Z"
    }
  ],
  "errors": [
    {
      "code": "BadRequest",
      "status": "400",
      "title": "Bad Request",
      "detail": "id 4 is not a valid type 1 UUID"
    }
  ]
}

List Related Object Records

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

Returns all the object records that the specified object record has relationship records with for the specified relationship type. For the relationship type, specify a relationship type key. For the specified object record, specify a custom object record id or a Zendesk object record id.

For example, the following request returns all object records related to the object record with the id of 1edf74c1-8000-4d01-b75e-e14bf2c85442 in the relationship type with a key named "suppliers":

GET /api/sunshine/objects/records/1edf74c1-8000-4d01-b75e-e14bf2c85442/related/suppliers

See the Example Response section below. The custom object record with the id 1edf74c1-8000-4d01-b75e-e14bf2c85442 has relationship records to these object records, but they don't have a relationship record back to the original object record.

You can specify a Zendesk object record as follows:

GET /api/sunshine/objects/records/zen:user:123456/related/suppliers

Allowed For
  • Everyone
Parameters

You can use the following optional query string parameters:

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

{
  "data": [
    {
      "id": "14c6c4be-cb64-4678-ba73-296e3d2c32cf",
      "type": "product",
      "type_version": 1,
      "external_id": "3",
      "attributes": {
        "id": "3",
        "name": "Strawberry Chewing Gum"
      },
      "created_at": "2017-01-03T12:35:45Z",
      "updated_at": "2017-01-03T12:35:45Z"
    },
    {
      "id": "d07b6206-1ea1-43c4-ae68-ef743aa36169",
      "type": "product",
      "type_version": 1,
      "external_id": "4",
      "attributes": {
        "id": "4",
        "name": "Coffee Chewing Gum"
      },
      "created_at": "2017-01-03T12:35:45Z",
      "updated_at": "2017-01-03T12:35:45Z"
    }
  ],
  "links": {
    "previous": null,
    "next": null
  }
}

Show Object Record

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

Returns the specified object record.

Allowed For
  • Everyone
Using cURL
curl https://{subdomain}.zendesk.com/api/sunshine/objects/records/{id} \
  -v -u {email_address}:{password}
Example Response
Status: 200 OK

{
  "data": {
    "id": "14c6c4be-cb64-4678-ba73-296e3d2c32cf",
    "type": "product",
    "external_id": "3",
    "attributes": {
      "id": "3",
      "name": "Strawberry Chewing Gum"
    },
    "created_at": "2017-01-03T12:35:45Z",
    "updated_at": "2017-01-03T12:35:45Z"
  }
}

Show Object Record by External Id

  • GET /api/sunshine/objects/records?type={object_type}&external_id={id}
  • GET /api/sunshine/objects/records?type={object_type}&external_ids={id, id, ...}

Returns an array containing a single object record for a given object record external id and object type key.

Allowed For
  • Everyone
Using cURL
curl "https://{subdomain}.zendesk.com/api/sunshine/objects/records?type={object_type}&external_id={id}" \
  -v -u {email_address}:{password}
Example Response
Status: 200 OK

{
  "data": [
    {
      "id": "14c6c4be-cb64-4678-ba73-296e3d2c32cf",
      "type": "product",
      "external_id": "3",
      "attributes": {
        "id": "3",
        "name": "Strawberry Chewing Gum"
      },
      "created_at": "2017-01-03T12:35:45Z",
      "updated_at": "2017-01-03T12:35:45Z"
    }
  ]
}

Create Object Record

POST /api/sunshine/objects/records

Creates an object record.

Allowed For
  • Everyone
Using cURL
curl https://{subdomain}.zendesk.com/api/sunshine/objects/records \
  -d '{"data": {"type": "product", "external_id": "3", "attributes": {"id": "3", "name": "Strawberry Chewing Gum"}}}' \
  -H "Content-Type: application/json" -X POST \
  -v -u {email_address}:{password}
Example Response
Status: 201 Created

{
  "data": {
    "id": "14c6c4be-cb64-4678-ba73-296e3d2c32cf",
    "type": "product",
    "type_version": 1,
    "external_id": "3",
    "attributes": {
      "id": "3",
      "name": "Strawberry Chewing Gum"
    },
    "created_at": "2017-01-03T12:35:45Z",
    "updated_at": "2017-01-03T12:35:45Z"
  }
}

Note that unless your object type's schema includes "additionalProperties": false, you can add attributes with names not included in the schema. Avoid using an underscore (_) prefix for the names of any additional attribute. See schema property.

We will in the future be disallowing the creation of property names that commence with the "_" character, reserving such names for internal use. If you create an off-schema property with such a name before the restriction is enforced, you may not be able to search using that property. To avoid any possible future conflicts, please rename any such off-schema properties you may have created.

Update Object Record

PATCH /api/sunshine/objects/records/{id}

Updates the attributes object of the specified object record. It does not update any other record properties.

The attributes object patches the previously stored object. Therefore, the request should only contain the properties of the attributes object that need to be updated.

The request must include an "application/merge-patch+json" content-type header.

Allowed For
  • Everyone
Using cURL
curl https://{subdomain}.zendesk.com/api/sunshine/objects/records/{id} \
  -d '{"data": {"attributes": {"id": "4", "name": "Hotdog Chewing Gum"}}}' \
  -H "Content-Type: application/merge-patch+json" -X PATCH \
  -v -u {email_address}:{password}
Example Response
Status: 200 OK

{
  "data": {
    "id": "d07b6206-1ea1-43c4-ae68-ef743aa36169",
    "type": "product",
    "type_version": 1,
    "external_id": "4",
    "attributes": {
      "id": "4",
      "name": "Hotdog Chewing Gum"
    },
    "created_at": "2017-01-03T12:35:45Z",
    "updated_at": "2017-01-04T18:15:00Z"
  }
}

Set Object Record by External Id

PATCH /api/sunshine/objects/records

Creates a new object if an object with given external id does not exist and updates the attributes object of the specified object record if an object with the given external id does exist. This endpoint does not update any other record properties.

The request should contain:

  • Object type
  • External id
  • attributes of the object that needs to be updated

The request must include an "application/merge-patch+json" content-type header.

Allowed For
  • Everyone
Using cURL
curl https://{subdomain}.zendesk.com/api/sunshine/objects/records \
  -d '{"data": {"type": "product", "external_id": "4", "attributes": {"id": "4", "name": "Hotdog Chewing Gum"}}}' \
  -H "Content-Type: application/merge-patch+json" -X PATCH \
  -v -u {email_address}:{password}
Example Response
Status: 200 OK

{
  "data": {
    "id": "d07b6206-1ea1-43c4-ae68-ef743aa36169",
    "type": "product",
    "type_version": 1,
    "external_id": "4",
    "attributes": {
      "id": "4",
      "name": "Hotdog Chewing Gum"
    },
    "created_at": "2017-01-03T12:35:45Z",
    "updated_at": "2017-01-04T18:15:00Z"
  }
}

Delete Object Record

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

Deletes the specified object record.

Before deleting an object record, you must delete any relationship record that specifies the object record. See Relationship Records.

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

Delete Object Record by External Id

DELETE /api/sunshine/objects/records?external_id={external_id}&type={type}

Deletes the specified object record if it exists.

Before deleting an object record, you must delete any relationship record that specifies the object record. See Relationship Records.

Allowed For
  • Everyone
Using cURL
curl "https://{subdomain}.zendesk.com/api/sunshine/objects/records?type=product&external_id=1" \
  -X DELETE \
  -v -u {email_address}:{password}
Example Response
Status: 204 No Content