Dynamic Content Items

Dynamic content is a combination of a default version of some text and variants of the text in other languages. The combined content is represented by a placeholder such as {{dc.my_placeholder}}. Dynamic content is available only on the Professional plan and above. Learn more in the Support Help Center.

This page contains the API reference for dynamic content items. See Dynamic Content Item Variants for the reference for variants.

You can use dynamic content with the API to set some properties of ticket fields, ticket forms, user fields, and organization fields. For example, you can use dynamic content for the title of a ticket field. In that case, use the dynamic content placeholder for the value of the field's raw_title property and the the default version of the text as the value of the title property. Example:

"title": "Flight Number", "raw_title": "{{dc.my_field_title}}", ...

If dynamic content is not used for the property, the two values are identical:

"title": "Flight Number", "raw_title": "Flight Number", ...

Data hierarchy

The data structure for dynamic content is a parent-child hierarchy where variants belong to items.

  • Items

    These are the dynamic content placeholders defined by content creators. Each item defines a namespace for a specific piece of content, such as instructions on how to reset your password or upgrade your plan. An item's only content is the title of the item itself (defined by you) and a placeholder for that item (defined by Zendesk Support). The content itself is contained in the variants.

  • Variants

    These are pieces of locale-specific content, where the context is based on the item they belong to. You can only have one variant per locale, per item. For example, if an item has 3 variants, they must each have a unique locale such as English, Spanish and French. They can't be English, English, and Spanish (though it is possible to have English-US and English-UK).

This hierarchy is illustrated in the following example:

Each item has a unique ID and a unique dynamic content placeholder. Below each item are a number of variants, all with their unique ID and locale. Items can contain any number of variants.

Paginating and sorting

This API uses standard pagination and sorting parameters. See Pagination.

You can sort the results of any list endpoint (both asc and desc) by the following properties: locale, outdated, active, updated_at, and created_at. The default sorting is by id in descending order.

Specifying item variants

When creating or updating an item, specify the variants in the item's variants array. Each variant consists of a locale_id, default, and content property. See Dynamic Content Item Variants for the variants API reference.

Zendesk Support uses the default variant if it can't find a variant that matches the user's locale.

Example, formatted for clarity:

{
  "item": {
    "name": "Snowboard Problem",
    "default_locale_id": 1,
    "variants": [
      {"locale_id": 1, "default": true, "content": "C'est mon contenu dynamique en français"},
      {"locale_id": 2, "default": false, "content": "Este es mi contenido dinámico en español"}
    ]
  }
}

If you have only one variant, you can use the content property instead of the variants property:

{
  "item": {
    "name": "Snowboard Problem",
    "default_locale_id": 1,
    "content": "C'est mon contenu dynamique en français"
  }
}

However, we recommend passing an array of variants even if you only have one variant.

JSON Format

Dynamic Content Items are represented as JSON objects with the following properties:

Name Type Read-only Mandatory Description
created_at string true false When this record was created
default_locale_id integer false true The default locale for the item. Must be one of the locales the account has active.
id integer true false Automatically assigned when creating items
name string false true The unique name of the item
outdated boolean true false Indicates the item has outdated variants within it
placeholder string true false Automatically generated placeholder for the item, derived from name
updated_at string true false When this record was last updated
url string true false The API url of this item
variants array false true All variants within this item. See Dynamic Content Item Variants

List Items

  • GET /api/v2/dynamic_content/items

Returns a list of all dynamic content items for your account if accessed as an admin or agents who have permission to manage dynamic content.

Allowed For
  • Admins, Agents
Using curl
curl https://{subdomain}.zendesk.com/api/v2/dynamic_content/items.json \
  -v -u {email_address}:{password}
Example Response
Status 200 OK

{
  "items": [
    {
      "created_at": "2015-05-13T22:33:12Z",
      "default_locale_id": 1,
      "id": 47,
      "name": "Snowboard Problem",
      "outdated": true,
      "placeholder": "{{dc.snowboard_problem}}",
      "updated_at": "2015-05-13T22:33:12Z",
      "url": "https://company.zendesk.com/api/v2/dynamic_content/items/47.json",
      "variants": [
        {
          "active": true,
          "content": "C'est mon contenu dynamique en français",
          "created_at": "2015-05-13T22:33:12Z",
          "default": true,
          "id": 47,
          "locale_id": 1,
          "outdated": false,
          "updated_at": "2015-05-13T22:33:12Z",
          "url": "https://company.zendesk.com/api/v2/dynamic_content/items/47/variants/47.json"
        }
      ]
    }
  ]
}

Create Item

  • POST /api/v2/dynamic_content/items

Create a new content item, with one or more variants in the item's variants array. See Specifying item variants.

The default_locale_id and variant locale_id values must be one of the locales the account has active. You can get the list with the List Locales endpoint.

Allowed For
  • Admins, Agents
Using curl
curl https://{subdomain}.zendesk.com/api/v2/dynamic_content/items.json \
  -d '{"item": {"name": "Snowboard Problem", "default_locale_id": 16, "variants": [{"locale_id": 16, "default": true, "content": "Voici mon contenu dynamique en français"}, {"locale_id": 2, "default": false, "content": "Este es mi contenido dinámico en español"}]}}' \
  -v -u {email_address}:{password}
Example Response
Status 201 Created

{
  "item": {
    "created_at": "2015-05-13T22:33:12Z",
    "default_locale_id": 1,
    "id": 47,
    "name": "Snowboard Problem",
    "outdated": false,
    "placeholder": "{{dc.snowboard_problem}}",
    "updated_at": "2015-05-13T22:33:12Z",
    "url": "https://company.zendesk.com/api/v2/dynamic_content/items/47.json",
    "variants": [
      {
        "active": true,
        "content": "Voici mon contenu dynamique en français",
        "created_at": "2015-05-13T22:33:12Z",
        "default": true,
        "id": 47,
        "locale_id": 16,
        "outdated": false,
        "updated_at": "2015-05-13T22:33:12Z",
        "url": "https://company.zendesk.com/api/v2/dynamic_content/items/47/variants/47.json"
      },
      {
        "active": true,
        "content": "Este es mi contenido dinámico en español",
        "created_at": "2015-05-13T22:33:12Z",
        "default": false,
        "id": 48,
        "locale_id": 2,
        "outdated": false,
        "updated_at": "2015-05-13T22:33:12Z",
        "url": "https://company.zendesk.com/api/v2/dynamic_content/items/47/variants/48.json"
      }
    ]
  }
}

Show Many Items

  • GET /api/v2/dynamic_content/items/show_many
Stability
  • Development
Allowed For
  • Admins, Agents
Parameters
Name Type In Required Description
identifiers string Query false Identifiers for the dynamic contents
Using curl
curl https://{subdomain}.zendesk.com/api/v2/dynamic_content/items/show_many.json?identifiers=item_one,item_two
  -v -u {email_address}:{password}
Example Response
Status 200 OK

{
  "items": [
    {
      "created_at": "2015-05-13T22:33:12Z",
      "default_locale_id": 1,
      "id": 47,
      "name": "Snowboard Problem",
      "outdated": true,
      "placeholder": "{{dc.snowboard_problem}}",
      "updated_at": "2015-05-13T22:33:12Z",
      "url": "https://company.zendesk.com/api/v2/dynamic_content/items/47.json",
      "variants": [
        {
          "active": true,
          "content": "C'est mon contenu dynamique en français",
          "created_at": "2015-05-13T22:33:12Z",
          "default": true,
          "id": 47,
          "locale_id": 1,
          "outdated": false,
          "updated_at": "2015-05-13T22:33:12Z",
          "url": "https://company.zendesk.com/api/v2/dynamic_content/items/47/variants/47.json"
        }
      ]
    }
  ]
}

Show Item

  • GET /api/v2/dynamic_content/items/{dynamic_content_item_id}
Allowed For
  • Admins, Agents
Parameters
Name Type In Required Description
dynamic_content_item_id integer Path true The ID of the dynamic content item
Using curl
curl https://{subdomain}.zendesk.com/api/v2/dynamic_content/items/{dynamic_content_item_id}.json \
  -v -u {email_address}:{password}
Example Response
Status 200 OK

{
  "item": {
    "created_at": "2015-05-13T22:33:12Z",
    "default_locale_id": 1,
    "id": 47,
    "name": "Snowboard Problem",
    "outdated": false,
    "placeholder": "{{dc.snowboard_problem}}",
    "updated_at": "2015-05-13T22:33:12Z",
    "url": "https://company.zendesk.com/api/v2/dynamic_content/items/47.json",
    "variants": [
      {
        "active": true,
        "content": "Voici mon contenu dynamique en français",
        "created_at": "2015-05-13T22:33:12Z",
        "default": true,
        "id": 47,
        "locale_id": 16,
        "outdated": false,
        "updated_at": "2015-05-13T22:33:12Z",
        "url": "https://company.zendesk.com/api/v2/dynamic_content/items/47/variants/47.json"
      },
      {
        "active": true,
        "content": "Este es mi contenido dinámico en español",
        "created_at": "2015-05-13T22:33:12Z",
        "default": false,
        "id": 48,
        "locale_id": 2,
        "outdated": false,
        "updated_at": "2015-05-13T22:33:12Z",
        "url": "https://company.zendesk.com/api/v2/dynamic_content/items/47/variants/48.json"
      }
    ]
  }
}

Update Item

  • PUT /api/v2/dynamic_content/items/{dynamic_content_item_id}

The only attribute you can change is the name. You can specify multiple variants in the item's variants array. See Specifying item variants.

Allowed For
  • Admins, Agents
Parameters
Name Type In Required Description
dynamic_content_item_id integer Path true The ID of the dynamic content item
Using curl
curl https://{subdomain}.zendesk.com/api/v2/dynamic_content/items/{dynamic_content_item_id}.json \
  -H "Content-Type: application/json" -d '{"item": {"name": "New name"}}'\
  -v -u {email_address}:{password} -X PUT
Example Response
Status 200 OK

{
  "item": {
    "created_at": "2015-05-13T22:33:12Z",
    "default_locale_id": 1,
    "id": 47,
    "name": "New name",
    "outdated": false,
    "placeholder": "{{dc.snowboard_problem}}",
    "updated_at": "2015-05-13T22:33:12Z",
    "url": "https://company.zendesk.com/api/v2/dynamic_content/items/47.json",
    "variants": [
      {
        "active": true,
        "content": "Voici mon contenu dynamique en français",
        "created_at": "2015-05-13T22:33:12Z",
        "default": true,
        "id": 47,
        "locale_id": 16,
        "outdated": false,
        "updated_at": "2015-05-13T22:33:12Z",
        "url": "https://company.zendesk.com/api/v2/dynamic_content/items/47/variants/47.json"
      },
      {
        "active": true,
        "content": "Este es mi contenido dinámico en español",
        "created_at": "2015-05-13T22:33:12Z",
        "default": false,
        "id": 48,
        "locale_id": 2,
        "outdated": false,
        "updated_at": "2015-05-13T22:33:12Z",
        "url": "https://company.zendesk.com/api/v2/dynamic_content/items/47/variants/48.json"
      }
    ]
  }
}

Delete Item

  • DELETE /api/v2/dynamic_content/items/{dynamic_content_item_id}
Allowed For
  • Admins, Agents
Parameters
Name Type In Required Description
dynamic_content_item_id integer Path true The ID of the dynamic content item
Using curl
curl https://{subdomain}.zendesk.com/api/v2/dynamic_content/items/{dynamic_content_item_id}.json \
  -X DELETE -v -u {email_address}:{password}
Example Response
Status 204 No Content