Manage content type bindings using the REST API
A content type binding defines a set of property mappings from one content type to another. The from field specifies the source content type, and the to field specifies the target content type. After you define a content type binding, you can use it to data bind mapped properties from one content instance to another content instance.
For example, you can bind a StartPage content type to a StartPageTeaser content type so that properties like an image, alt text, and body are automatically mapped between them.
Content type bindings work together with content sources. While a content source defines an external source of content and maps its properties to CMS, a content type binding defines how properties from one content type map to another, enabling content integration across types.
The content type bindings API is available at https://api.cms.optimizely.com/v1/contenttypebindings. The endpoint requires a valid token, as described in Authentication and authorizationAuthentication and authorization.
Content type binding data model
The content type binding resource has the following fields:
- key – Unique identifier for the content type binding. Must start with a letter and contain only letters, digits, and underscores (A–Z, a–z, 0–9, _). Minimum two characters, maximum 255. If omitted on creation, a key is auto-generated.
- from – The key of the source content type to bind from. Required. Must start with a letter and contain only letters, digits, and underscores. Minimum two characters, maximum 255.
- to – The key of the target content type to bind to. Required. Must start with a letter and contain only letters, digits, and underscores. Minimum two characters, maximum 255.
- propertyMappings – An object map defining how properties in the target content type map to properties in the source content type. Each entry in the map uses the target property path as the key and contains:
- from – The property path in the source content type. Required. Use dot notation (such as Hero.Image) to reference nested properties.
- binding – An optional key referencing another content type binding. Use this to specify that component properties should be mapped using an existing binding.
- created – Read-only timestamp indicating when the content type binding was created.
- createdBy – Read-only field indicating who created the content type binding.
- lastModified – Read-only timestamp indicating when the content type binding was last modified.
- lastModifiedBy – Read-only field indicating who last modified the content type binding.
Create a content type binding
You can create a content type binding using the content type bindings API. You must provide the from and to content type keys. The key and propertyMappings fields are optional — if you omit key, it is auto-generated. See Create a content type bindingCreate a content type binding for the full API reference.
The request supports the following optional header:
- Prefer: return=representation – Return the created resource in the response body.
POST https://api.cms.optimizely.com/v1/contenttypebindings
Content-Type: application/json{
"key": "PageTeaserBinding",
"from": "StartPage",
"to": "StartPageTeaser",
"propertyMappings": {
"Image": {
"from": "Hero.Image"
},
"AltText": {
"from": "Hero.ImageDescription"
},
"Body": {
"from": "MainBody"
}
}
}Mapped properties must be compatible types. In general, a property type with fewer capabilities can map to a property type with broader capabilities. The following cross-type mappings are supported. For all other property types, the source and target must be the same type.
Text properties
Source type | Supported target types |
|---|---|
ShortString | LongString, XHTMLString, LinkItem, URL |
LongString | XHTMLString, LinkItem, URL |
Number properties
Source type | Supported target types |
|---|---|
Integer | Decimal, ShortString, LongString, XHTMLString |
Decimal | ShortString, LongString, XHTMLString |
Content reference properties
Source type | Supported target types |
|---|---|
ContentReference | LinkItem, URL |
ContentReference<T> | ContentReference, LinkItem, URL |
When mapping a ContentReference to a LinkItem property, the permanent URL of the referenced content is set on the link. When mapping a LinkItem to a ContentReference, the reference is set if the link's permanent URL points to a content item. This cross-type mapping only applies to untyped ContentReference properties.
All of the above mappings also apply to lists of the specified types.
Get a content type binding
You can retrieve a specific content type binding using its unique key. See Get a content type bindingGet a content type binding for the full API reference.
The request supports the following optional headers for conditional requests:
- If-None-Match – Return the resource only if the current ETag does not match.
- If-Modified-Since – Return the resource only if it was modified after the specified date.
GET https://api.cms.optimizely.com/v1/contenttypebindings/PageTeaserBinding{
"key": "PageTeaserBinding",
"from": "StartPage",
"to": "StartPageTeaser",
"created": "2025-01-15T10:30:00+00:00",
"createdBy": "[email protected]",
"lastModified": "2025-01-15T10:30:00+00:00",
"lastModifiedBy": "[email protected]",
"propertyMappings": {
"Image": {
"from": "Hero.Image"
},
"AltText": {
"from": "Hero.ImageDescription"
},
"Body": {
"from": "MainBody"
}
}
}List content type bindings
You can list content type bindings using the content type bindings API. See List content type bindingsList content type bindings for the full API reference.
The endpoint supports the following query parameters for pagination:
- pageIndex – The zero-based index of the page to retrieve.
- pageSize – The number of items per page.
GET https://api.cms.optimizely.com/v1/contenttypebindings{
"items": [
{
"key": "PageTeaserBinding",
"from": "StartPage",
"to": "StartPageTeaser",
"created": "2025-01-15T10:30:00+00:00",
"createdBy": "[email protected]",
"lastModified": "2025-01-15T10:30:00+00:00",
"lastModifiedBy": "[email protected]",
"propertyMappings": {
"Image": {
"from": "Hero.Image"
},
"AltText": {
"from": "Hero.ImageDescription"
},
"Body": {
"from": "MainBody"
}
}
}
],
"pageSize": 10,
"pageIndex": 0,
"totalCount": 1
}Update a content type binding
You can update individual fields on an existing content type binding using a merge patch request. See Update a content type bindingUpdate a content type binding for the full API reference.
The request supports the following optional headers:
- Prefer: return=representation – Return the updated resource in the response body.
- If-Match – Update only if the current ETag matches (optimistic concurrency).
- If-Unmodified-Since – Update only if the resource was not modified after the specified date.
PATCH https://api.cms.optimizely.com/v1/contenttypebindings/PageTeaserBinding
Content-Type: application/merge-patch+json{
"propertyMappings": {
"Additional": {
"from": "SourceProperty"
}
}
}Delete a content type binding
You can delete an existing content type binding using its unique key. See Delete a content type bindingDelete a content type binding for the full API reference.
The request supports the following optional headers:
- Prefer: return=representation – Return the deleted resource in the response body.
- If-Match – Delete only if the current ETag matches (optimistic concurrency).
- If-Unmodified-Since – Delete only if the resource was not modified after the specified date.
DELETE https://api.cms.optimizely.com/v1/contenttypebindings/PageTeaserBindingUse the binding property for nested mappings
When mapping component properties that have their own complex structure, you can reference another content type binding through the binding field instead of mapping individual properties. This lets you reuse existing binding definitions for nested content types.
POST https://api.cms.optimizely.com/v1/contenttypebindings
Content-Type: application/json{
"key": "PageTeaserWithHeroBinding",
"from": "StartPage",
"to": "StartPageTeaser",
"propertyMappings": {
"Hero": {
"from": "Hero",
"binding": "HeroComponentBinding"
},
"Body": {
"from": "MainBody"
}
}
}In this example, the Hero property mapping references the HeroComponentBinding binding, which defines how the individual properties within the hero component should be mapped.