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 in the Support Help Center.

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 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 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 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

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. 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 you only have one variant.

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": 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 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": "Voici mon contenu dynamique en français",
        "locale_id": 16,
        "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

Show Many Items

GET /api/v2/dynamic_content/items/show_many.json?identifiers={identifiers}

Stability
  • Development
Allowed For
  • Admins, Agents
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": [
    {
      "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"
        },
      ...
      ]
    },
    {
      ...
    }
  ]
}

JSON Format for Variants

Variants are represented as JSON objects with the following properties:

Name Type Read-only Mandatory Comment
id integer yes no Automatically assigned when the variant is created
url string yes no The API url of the variant
content string no yes The content of the variant
locale_id integer no yes An active locale
outdated boolean yes no If the variant is outdated
active boolean no no If the variant is active and useable
default boolean no no If the variant is the default for the item it belongs to
created_at date yes no When the variant was created
updated_at date yes no When the variant was last updated

A few items are worth noting:

  • locale_id - Must be an active locale in the account. To get a list, see /api/v2/locales

  • default - Used as the fallback if Zendesk Support can't find an appropriate variant to match the locale of the user the content is being displayed for

  • outdated- Indicates the default variant for this item has been updated, but the other variants were not changed. The content may be out of date

  • active - If false, Zendesk Support will not use the variant even if the user's locale matches the variant

Almost all of the properties are writable.

List Variants

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

Returns all the variants of the specified dynamic content item.

Allowed For
  • Admins
  • Agents who have permission to manage dynamic content
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"
    },
    ...
  ]
}

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

You can only create one variant for each locale id. If a locale variant already exists, the request is rejected.

Allowed For
  • Admins, Agents
Using curl
curl https://{subdomain}.zendesk.com/api/v2/dynamic_content/items/{id}/variants.json \
  -d '{"variant": {"locale_id": 127, "active": true, "default": false, "content": "C\u0027est mon contenu dynamique en français"}}' \
  -H "Content-Type: application/json" -X POST \
  -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"
  }
}

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 \
  -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"}]}'\
  -H "Content-Type: application/json" -X POST \
  -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

Updates the specified variant. You don't need to include all the properties. If you just want to update content, for example, then include just that.

You can't switch the active state of the default variant of an item. Similarly, you can't switch the default to false if the variant is the default. You must make another variant default instead.

Allowed For
  • Admins, Agents
Using curl
curl https://{subdomain}.zendesk.com/api/v2/dynamic_content/items/{id}/variants/{id}.json \
  -d '{"variant": {"active": false, "default": false, "content": "C\u0027est mon contenu dynamique en français"}}'\
  -H "Content-Type: application/json" \
  -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"
  }
}

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 \
  -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"}]}'\
  -H "Content-Type: application/json" \
  -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