Create a hierarchy version

Learn more about how to use the Create hierarchy version to create a hierarchy version.

Use the Create hierarchy version to create a version for an existing hierarchy. You can also create the first hierarchy connection in the same request. This operation requires the MDM.Data.Hierarchy permission with the CREATE privilege.

HTTP method and endpoint

Use the following HTTP method and endpoint path to submit the request:

POST https://<environment>.reltio.com/reltio/api/{tenantId}/hierarchies/list/{hierarchyId}/versions

Request headers

The following request headers must be included.


Header	Value	Required
`Authorization`	`Bearer <token>`	Yes

Request body

The request body is a JSON array of connection definition objects.


Field		Type	Required	Description
`name`	—	String	Yes	The name of the version.
`status`	—	String	No	The status of the version.
`effectiveStartDate`	—	String	No	The start effective date of the version in ISO 8601 date format.
`effectiveEndDate`	—	String	No	The end effective date of the version in ISO 8601 date format.
`description`	—	String	No	The description of the version.
`context`	—	String	No	Additional context for the version.
`firstConnection`	—	Object	No	The object that describes the first hierarchy connection to create.
	`parentId`	String	See `firstConnection`	The entity ID of the parent object. Either the parent or the child must be part of the hierarchy being modified.
	`childId`	String	See `firstConnection`	The entity ID of the child object. Either the parent or the child must be part of the hierarchy being modified.
	`startDate`	String	See `firstConnection`	Optional. The start effective date of the connection in ISO 8601 date format.
	`endDate`	String	See `firstConnection`	Optional. The end effective date of the connection in ISO 8601 date format.

Example request

Use the following example to see how a complete request is structured with headers.

POST /list/prd/versions
Authorization: Bearer <token>

{
  "name": "Version 1",
  "status": "ACTIVE",
  "effectiveStartDate": "2024-01-01",
  "effectiveEndDate": "2026-12-31",
  "description": "longDescription",
  "context": "longContextDescription",
  "firstConnection": {
    "parentId": "prtId",
    "childId": "cldId",
    "startDate": "2024-01-01",
    "endDate": "2026-12-32"
  }
}

Response fields

The following table describes the fields returned in the response body, which is an array of hierarchy connection objects.


Field		Type	Description
`instanceId`	—	String	The ID of the created hierarchy instance.
`versionId`	—	String	The ID of the created version.
`name`	—	String	The name of the version.
`status`	—	String	Optional. The status of the version.
`effectiveStartDate`	—	String	Optional. The start effective date of the version in ISO 8601 date format.
`effectiveEndDate`	—	String	Optional. The end effective date of the version in ISO 8601 date format.
`description`	—	String	Optional. The description of the version.
`context`	—	String	Optional. Additional context for the version.
`firstConnection`	—	Object	Optional. The created first hierarchy connection.
	`connectionId`	String	The ID of the created connection.
	`parentId`	String	The entity ID of the parent object.
	`childId`	String	The entity ID of the child object.
	`startDate`	String	Optional. The start effective date of the connection in ISO 8601 date format.
	`endDate`	String	Optional. The end effective date of the connection in ISO 8601 date format.
`createdBy`	—	String	The username of the user who created the version.
`createdTime`	—	String	The time when the version was created, in ISO 8601 date-time format.
`updatedBy`	—	String	The username of the user who last updated the version.
`updatedTime`	—	String	The time when the version was last updated, in ISO 8601 date-time format.

Example response

The following example shows the response body.

{
  "instanceId": "0ABlc0A.0ABlgGQ",
  "versionId": "0ABlgGQ",
  "name": "Version 1",
  "status": "ACTIVE",
  "effectiveStartDate": "2024-01-01",
  "effectiveEndDate": "2026-12-31",
  "description": "longDescription",
  "context": "longContextDescription",
  "firstConnection": {
    "connectionId": "0ABmA6E",
    "parentId": "prtId",
    "childId": "cldId",
    "startDate": "2024-01-01",
    "endDate": "2026-12-31"
  },
  "createdBy": "email@reltio.com",
  "createdTime": "2025-04-01T13:30:00",
  "updatedBy": "email@reltio.com",
  "updatedTime": "2025-04-01T13:30:00"
}

Unify and manage your data