References

To identify specific objects in the environment, the API uses references to point to those objects.Internally, the API uses references by internal ID to point to other objects. When you're adding or modifying objects using the API, you can also reference the objects by their codenames or external IDs, if present.

Reference object

Reference to a specific object in the environment.

The API uses internal IDs for referencing objects. This means that the reference objects in the API responses will always use internal IDs.

id

string · uuid

The referenced object's internal ID.

codename

string · write-only

The referenced object's codename. The value of the codename property must meet the conditions defined in rules for codenames.

external_id

string · write-only

The referenced object’s external ID. The value of the external_id property must not contain the following characters: /, ., ;.

JSON

{
  "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53",
  "codename": "object_codename",
  "external_id": "your-own-custom-identifier"
}

How to specify an object reference

When specifying references to objects, the object can be identified by one of three properties:

Internal ID such as 18b43cc5-f4fd-0172-842b-3ae2c878cf6f
- Generated by the system automatically.
- Unique per object type, such as content item, content type, and more.
- Can be used to specify any object.
Codename such as object_codename
- Initially generated from the object's display name.
- Unique per object type, such as content item, content type, and more.
- Can be used to specify most objects.
External ID such as custom-object-identifier
- Specified manually when creating the object through the Management API. The external ID cannot be changed later.
- Unique per object type. For example, the uniqueness applies to content types and their elements within an environment, content items within an environment, and so on. This means you can have a content type and an element with the same external ID, but no two elements can use the same external ID within an environment.
- Can be used to specify custom identifiers for user-created objects such as assets, content items, content types, and more.

Rules for codenames

When editing codenames, the new codenames must meet the following conditions:

Only lowercase letters, numbers, and underscores are permitted.
Codenames must start with a letter or an underscore and have at least one character.
Codenames are usually limited to 60 characters, but longer codenames are allowed for multiple choice options and taxonomy terms.
Codenames of elements within a snippet must be prefixed with the snippet's codename.
Codenames must be unique per object type. This applies to, for example, every element within a content type, every content type within an environment, every content item within an environment, and so on.

This means the following applies when codenames are generated automatically:

All letters are made lowercase.
All forbidden characters are replaced by _.
For any names that start with a number, the codename will start with n.
Codenames that duplicate another codename will have a random string attached to the end.
Codenames of elements within a snippet will be prefixed with the snippet's codename.
Codenames will be cut off at the character limit.

External IDs for imported content

By using external IDs to reference other objects, you can import your content in the order you prefer. For example, when importing multiple articles that contain images, you can reference these images with external IDs, such as roaster or coffee-cup, before uploading them. The referenced images will be visible in the UI only after you add them as assets via the API. With this approach, you can choose whether you want to create content items first and then upload binary files for assets, or vice versa. This means you can use external IDs to reference objects that don't exist yet and add the objects via the API later. References to non-existent objects will be stored and retrieved via the API as internal IDs. To check for any references to not-yet-created objects, we recommend you validate your content.

Referencing objects that don't exist yetWith Management API, you can reference non-existent objects in the following elements:

Linked items element
Asset element
Taxonomy element
Rich text element (as assets, content items, and links)

See how to import linked content to learn more.

Missing objects in the UI

If you use external IDs to reference non-existent objects in your elements, the referenced objects won't be shown in the UI. This is because the system cannot find those objects. The referenced assets, content items, and taxonomy terms will be displayed after you create them with their specific external IDs via the Management API. To add the missing objects, see:

Upsert a content item to create content items specified by external IDs.
Upsert an asset to create assets specified by external IDs.
Add a taxonomy group to create taxonomy groups with external IDs.

Reference object

Reference to a specific object in the environment.

The API uses internal IDs for referencing objects. This means that the reference objects in the API responses will always use internal IDs.

id

string · uuid

The referenced object's internal ID.

codename

string · write-only

The referenced object's codename. The value of the codename property must meet the conditions defined in rules for codenames.

external_id

string · write-only

The referenced object’s external ID. The value of the external_id property must not contain the following characters: /, ., ;.

JSON

{
  "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53",
  "codename": "object_codename",
  "external_id": "your-own-custom-identifier"
}

How to specify an object reference

When specifying references to objects, the object can be identified by one of three properties:

Internal ID such as 18b43cc5-f4fd-0172-842b-3ae2c878cf6f

Generated by the system automatically.
Unique per object type, such as content item, content type, and more.
Can be used to specify any object.

Codename such as object_codename

Initially generated from the object's display name.
Unique per object type, such as content item, content type, and more.
Can be used to specify most objects.

External ID such as custom-object-identifier

Specified manually when creating the object through the Management API. The external ID cannot be changed later.
Unique per object type. For example, the uniqueness applies to content types and their elements within an environment, content items within an environment, and so on. This means you can have a content type and an element with the same external ID, but no two elements can use the same external ID within an environment.
Can be used to specify custom identifiers for user-created objects such as assets, content items, content types, and more.

Rules for codenames

When editing codenames, the new codenames must meet the following conditions:

Only lowercase letters, numbers, and underscores are permitted.
Codenames must start with a letter or an underscore and have at least one character.
Codenames are usually limited to 60 characters, but longer codenames are allowed for multiple choice options and taxonomy terms.
Codenames of elements within a snippet must be prefixed with the snippet's codename.
Codenames must be unique per object type. This applies to, for example, every element within a content type, every content type within an environment, every content item within an environment, and so on.

This means the following applies when codenames are generated automatically:

All letters are made lowercase.
All forbidden characters are replaced by _.
For any names that start with a number, the codename will start with n.
Codenames that duplicate another codename will have a random string attached to the end.
Codenames of elements within a snippet will be prefixed with the snippet's codename.
Codenames will be cut off at the character limit.

External IDs for imported content

By using external IDs to reference other objects, you can import your content in the order you prefer.

For example, when importing multiple articles that contain images, you can reference these images with external IDs, such as roaster or coffee-cup, before uploading them. The referenced images will be visible in the UI only after you add them as assets via the API. With this approach, you can choose whether you want to create content items first and then upload binary files for assets, or vice versa.

This means you can use external IDs to reference objects that don't exist yet and add the objects via the API later. References to non-existent objects will be stored and retrieved via the API as internal IDs.

To check for any references to not-yet-created objects, we recommend you validate your content.

Referencing objects that don't exist yetWith Management API, you can reference non-existent objects in the following elements:

Linked items element
Asset element
Taxonomy element
Rich text element (as assets, content items, and links)

See how to import linked content to learn more.

Missing objects in the UI

To add the missing objects, see:

Upsert a content item to create content items specified by external IDs.

Upsert an asset to create assets specified by external IDs.

Add a taxonomy group to create taxonomy groups with external IDs.