Dynamic content

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 in the Professional and Enterprise plans. Learn more.

Dynamic content can be used to set some properties of ticket fields, ticket forms, user fields, and organization fields. For example, dynamic content can be used for the title of a ticket field. If it's used, the value of the field's "raw_title" property is the dynamic content placeholder and the value of its "title" property is the default version of the text. 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 hierachy

It's important to understand how dynamic content's data is structured. It's a simple parent/child hierarchy, where variants belong to items.

  • Items

These are the dynamic content placeholders that are 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 you 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: English, Spanish and French for example. They can't be English, English and Spanish (though it is possible to have English-US and English-UK)

This hierarchy can be illustrated with this simple 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. It's perfectly OK for items to contain any number of variants; items can have as many or as little variants as you want.

Paginating and Sorting

We have a standard pattern for pagination and declaring sort order, which this API follows.

Sorting (both asc and desc) is supported for locale, outdated, active, updated_at and created_at which can be used on any GET endpoint where an index of data is being shown. Default sorting is by id, descending.

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. 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 always passing an array of variants, even if it's just one.

JSON Format for Items

Dynamic content items are represented as JSON objects which have the following keys:

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

List Items

GET /api/v2/dynamic_content/items.json

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

Show Item

GET /api/v2/dynamic_content/items/{id}.json

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

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

Create Item

POST /api/v2/dynamic_content/items.json

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

Note that 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 \
  -H "Content-Type: application/json" -X POST -d '{"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"]}}'\
  -v -u {email_address}:{password}
Example Response
Status: 200 OK
Location: https://{subdomain}.zendesk.com/api/v2/dynamic_content/items/{id}.json

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

Update Item

PUT /api/v2/dynamic_content/items/{id}.json

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
Using curl
curl https://{subdomain}.zendesk.com/api/v2/dynamic_content/items/{id}.json \
  -H "Content-Type: application/json" -d '{"item": {"name": "New name"}}'\
  -v -u {email_address}:{password} -X PUT
Example Response
Status: 200 OK
Location: https://{subdomain}.zendesk.com/api/v2/dynamic_content/items/{id}.json

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

Delete Item

DELETE /api/v2/dynamic_content/items/{id}.json

Allowed For
  • Admins, Agents
Using curl
curl https://{subdomain}.zendesk.com/api/v2/dynamic_content/items/{id}.json \
  -X DELETE -v -u {email_address}:{password}
Example Response
Status: 204 No Content

JSON Format for Variants

Variants are represented as JSON objects which have the following keys:

Name Type Read-only Mandatory Comment
id integer yes no Automatically assigned when creating variants
url string yes no The API url of this variant
name string no yes The unique name of the item
outdated boolean no no If the variant is outdated
active boolean no no If the variant is active and useable
default boolean yes no If the variant is the default for the item it belongs to
created_at date yes no When this record was created
updated_at date yes no When this record last got updated

List Variants

GET /api/v2/dynamic_content/items/3/variants.json

Returns a list of all the variants for a dynamic content item 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/{id}/variants.json \
  -v -u {email_address}:{password}
Example Response
Status: 200 OK

{
  "variants": [
    {
      "id": 23,
      "content": "This is my dynamic content in English",
      "locale_id": 125,
      "outdated": false,
      "active": true,
      "default": true,
      "created_at": "2014-04-09T19:53:23Z",
      "updated_at": "2014-04-09T19:53:23Z",
      "url": "https://subdomain.zendesk.com/api/v2/dynamic_content/items/3/variants/23.json"
    },
    {
      "id": 24,
      "content": "Este es mi contenido dinámico en español",
      "locale_id": 126,
      "outdated": true,
      "active": false,
      "default": false,
      "created_at": "2014-04-09T19:53:23Z",
      "updated_at": "2014-04-09T19:53:23Z",
      "url": "https://subdomain.zendesk.com/api/v2/dynamic_content/items/3/variants/24.json"
    },
    ...
  ]
}

There's a few items here worth a bit of attention:

  • locale_id

Must be one of the locales the account has active. You can get that list here: /api/v2/locales

  • default

Used as the fall back if Zendesk Support can't find an appropriate variant to match the locale of the user the content is being displayed for

  • outdated

This indicates that the default variant for this item has been updated, but the other variants were not changed. As a result, their content may be out of date

  • active

If this value is false, Zendesk Support will not use the variant even if the user's locale matches the variant

Almost all of these keys are writable.

Show Variant

GET /api/v2/dynamic_content/items/{id}/variants/{id}.json

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

{
  "variant": {
    "id": 23,
    "content": "This is my dynamic content in English",
    "locale_id": 125,
    "outdated": false,
    "active": true,
    "default": true,
    "created_at": "2014-04-09T19:53:23Z",
    "updated_at": "2014-04-09T19:53:23Z",
    "url": "https://subdomain.zendesk.com/api/v2/dynamic_content/items/3/variants/23.json"
  }
}

Create Variant

POST /api/v2/dynamic_content/items/{id}/variants.json

Allowed For
  • Admins, Agents
Using curl
curl https://{subdomain}.zendesk.com/api/v2/dynamic_content/items/{id}/variants.json \
  -H "Content-Type: application/json" -X POST -d '{"variant": {"locale_id": 127, "active": true, "default": false, "content": "C\u0027est mon contenu dynamique en français"}}'\
  -v -u {email_address}:{password}
Example Response
Status: 201 Created
Location: https://{subdomain}.zendesk.com/api/v2/dynamic_content/items/{id}/variants.json

{
  "variant": {
    "id": 23,
    "content": "C'est mon contenu dynamique en français",
    "locale_id": 127,
    "outdated": false,
    "active": true,
    "default": false,
    "created_at": "2014-04-09T19:53:23Z",
    "updated_at": "2014-04-09T19:53:23Z",
    "url": "https://subdomain.zendesk.com/api/v2/dynamic_content/items/3/variants/23.json"
  }
}

There is strictly only one variant for each locale. If a locale variant being posted already exists, the call will be rejected.

Create Many Variants

POST /api/v2/dynamic_content/items/{id}/variants/create_many.json

Allowed For
  • Admins, Agents
Using curl
curl https://{subdomain}.zendesk.com/api/v2/dynamic_content/items/{id}/variants/create_many.json \
  -H "Content-Type: application/json" -X POST -d '{"variants": [{"locale_id": 127, "active": true, "default": false, "content": "C\u0027est mon contenu dynamique en français"},{"locale_id": 126, "active": true, "default": false, "content": "Este es mi contenido dinámico en español"}]}'\
  -v -u {email_address}:{password}
Example Response
Status: 201 Created
Location: https://{subdomain}.zendesk.com/api/v2/dynamic_content/items/{id}/variants/create_many.json

{
  "variants": [
    {
      "id": 23,
      "content": "C'est mon contenu dynamique en français",
      "locale_id": 127,
      "outdated": false,
      "active": true,
      "default": false,
      "created_at": "2014-04-09T19:53:23Z",
      "updated_at": "2014-04-09T19:53:23Z",
      "url": "https://subdomain.zendesk.com/api/v2/dynamic_content/items/3/variants/23.json"
    },
    {
      "id": 24,
      "content": "Este es mi contenido dinámico en español",
      "locale_id": 126,
      "outdated": false,
      "active": true,
      "default": false,
      "created_at": "2014-04-09T19:53:23Z",
      "updated_at": "2014-04-09T19:53:23Z",
      "url": "https://subdomain.zendesk.com/api/v2/dynamic_content/items/3/variants/24.json"
    },
    ...
  ]
}

Update Variant

PUT /api/v2/dynamic_content/items/{id}/variants/{id}.json

Allowed For
  • Admins, Agents
Using curl
curl https://{subdomain}.zendesk.com/api/v2/dynamic_content/items/{id}/variants/{id}.json \
  -H "Content-Type: application/json" -d '{"variant": {"active": false, "default": false, "content": "C\u0027est mon contenu dynamique en français"}}'\
  -v -u {email_address}:{password} -X PUT
Example Response
Status: 200 OK
Location: https://{subdomain}.zendesk.com/api/v2/dynamic_content/items/{id}/variants/{id}.json

{
  "variant": {
    "id": 23,
    "content": "C'est mon contenu dynamique en français",
    "locale_id": 125,
    "outdated": false,
    "active": false,
    "default": false,
    "created_at": "2014-04-09T19:53:23Z",
    "updated_at": "2014-04-09T19:53:23Z",
    "url": "https://subdomain.zendesk.com/api/v2/dynamic_content/items/3/variants/23.json"
  }
}

Note that you don't need to include all the keys. If you just want to update content, for example, then include just that. You cannot switch the active state of the default variant within an item. Similarly, you can't switch the default to false if the variant is the default, you must make another variant default instead.

Update Many Variants

PUT /api/v2/dynamic_content/items/{id}/variants/update_many.json

Allowed For
  • Admins, Agents
Using curl
curl https://{subdomain}.zendesk.com/api/v2/dynamic_content/items/{id}/variants/update_many.json \
  -H "Content-Type: application/json" -d '{"variants": [{"id": 23, "active": false, "default": false, "content": "C\u0027est mon contenu dynamique en français"},{"id": 24, "active": false, "default": false, "content": "Este es mi contenido dinámico en español"}]}'\
  -v -u {email_address}:{password} -X PUT
Example Response
Status: 200 OK
Location: https://{subdomain}.zendesk.com/api/v2/dynamic_content/items/{id}/variants/{id}.json

{
  "variants": [
    {
      "id": 23,
      "content": "C'est mon contenu dynamique en français",
      "locale_id": 127,
      "outdated": false,
      "active": true,
      "default": false,
      "created_at": "2014-04-09T19:53:23Z",
      "updated_at": "2014-04-09T19:53:23Z",
      "url": "https://subdomain.zendesk.com/api/v2/dynamic_content/items/3/variants/23.json"
    },
    {
      "id": 24,
      "content": "Este es mi contenido dinámico en español",
      "locale_id": 126,
      "outdated": false,
      "active": true,
      "default": false,
      "created_at": "2014-04-09T19:53:23Z",
      "updated_at": "2014-04-09T19:53:23Z",
      "url": "https://subdomain.zendesk.com/api/v2/dynamic_content/items/3/variants/24.json"
    },
    ...
  ]
}

Delete Variant

DELETE /api/v2/dynamic_content/items/{id}/variants/{id}.json

Allowed For
  • Admins, Agents
Using curl
curl https://{subdomain}.zendesk.com/api/v2/dynamic_content/items/{id}/variants/{id}.json \
  -X DELETE -v -u {email_address}:{password}
Example Response
Status: 204 No Content