Create a hierarchy

Learn more about how to use the Create hierarchy API to create a hierarchy and, optionally, its first version and first connection.

Use the Create a Hierarchy to create a hierarchy definition. If versioning is enabled, you can also create the initial hierarchy version and 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/

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
`type`	—	String	Yes	The hierarchy type name as defined in the business configuration.
`name`	—	String	Yes	The name of the hierarchy.
`hasVersioning`	—	Boolean	No	Indicates whether the hierarchy is versioned.
`version`	—	Object	Yes, if `hasVersioning=true`	The object that describes the version to create.
	`name`	String	No	The name of the version.
	`effectiveStartDate`	String	No	Optional. The start effective date of the version in ISO 8601 date format.
	`effectiveEndDate`	String	No	Optional. The end effective date of the version in ISO 8601 date format.
	`description`	String	No	Optional. The description of the version.
	`context`	String	No	Optional. Additional context for the version.
	`firstConnection`	—	Object	No	The object that describes the first hierarchy connection to create.
`parentId`		String	Yes	The entity ID of the parent object. Either the parent or the child must be part of the hierarchy being modified.
`childId`		String	Yes	The entity ID of the child object. Either the parent or the child must be part of the hierarchy being modified.
`startDate`		String	No	Optional. The start effective date of the connection in ISO 8601 date format.
`endDate`		String	No	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 /
Authorization: Bearer <token>

{
  "type": "configuration/hierarchyTypes/TypeProduct",
  "name": "Product Hierarchy",
  "hasVersioning": true,
  "version": {
    "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
`type`	—	String	The hierarchy type name as defined in the business configuration.
`name`	—	String	The name of the hierarchy.
`hasVersioning`	—	Boolean	Indicates whether the hierarchy is versioned.
`hierarchyId`	—	String	The ID of the created hierarchy.
`instanceId`	—	String	The ID of the created hierarchy instance.
`version`	—	Object	Optional. The created hierarchy version.
	`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 hierarchy.
`createdTime`	—	String	The time when the hierarchy was created, in ISO 8601 date-time format.
`updatedBy`	—	String	The username of the user who last updated the hierarchy.
`updatedTime`	—	String	The time when the hierarchy was last updated, in ISO 8601 date-time format.

Example response

The following example shows the response body.

{
  "type": "configuration/hierarchyTypes/TypeProduct",
  "name": "Product Hierarchy",
  "hasVersioning": true,
  "hierarchyId": "0ABlc0A",
  "instanceId": "0ABlc0A.0ABlgGQ",
  "version": {
    "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-32"
  },
  "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