API Reference > Part II: Authenticate using JWT > Manage data collections > Create data collections

Create data collections

Use a REST API to create data collections in Data Marketplace.

Endpoint and method

The following table describes the connection properties for the API:

Property	Description
Endpoint	/api/v2/data-collections
Method	POST

For more information about how you can call an API, see Authenticate using JWT.

Request

The following table describes the parameters that you enter in the body of the API payload:

Parameter	Description	Additional Information
externalId	Optional. Enter a reference identifier for the data collection that you want to create.	If you don't specify a reference identifier, Data Marketplace automatically assigns a unique value to the item. The reference identifier that Data Marketplace automatically generates contains a prefix. The administrator can specify the prefix of the automatically generated reference identifier in Metadata Command Center. If you want to specify a reference identifier, ensure that you enter a unique value. Ensure that you don't use the prefix value that is configured in Metadata Command Center.
name	Required. Enter a name for the data collection.	Ensure that you enter a unique value. Data Marketplace doesn't consider the letter case when it verifies the uniqueness of the name parameter's value. For example, if you try to name a category as "Retail Department" while a category called "Retail department" already exists, the API call fails.
description	Required. Enter a description for the data collection.	-
categoryId	Required. The system-generated unique identifier of the category to which you want to add the data collection.	For more information about how you can use an API to get the system-generated unique identifier of a category, see Retrieve all categories. To get the system-generated unique identifier of a category from the Data Marketplace user interface, open the category. The category page's URL contains the system-generated unique identifier. For example, in the URL https://{{CDMP_URL}}/category/view?ac=67417f72-e5ab-44f0-add9-a1e412c1ce13&dtn=_AfterEBF%20may20, the system-generated unique identifier is 67417f72-e5ab-44f0-add9-a1e412c1ce13.
status	Required. Specify a status for the data collection. The status determines whether the data collection is discoverable to Data Users. Enter one of the following values: - To make the data collection discoverable to Data Users, enter PUBLISHED. - To make the data collection undiscoverable to Data Users, enter UNPUBLISHED.	-
usageContextId	Optional. Enter the system-generated unique identifier of the usage type that you want to use to specify the context in which you intend to use the data after you receive access to the collection.	For more information about how you can use an API to get the system-generated unique identifier of a usage type, see Retrieve usage type.
customAttributes	Specify the custom attribute values for the data collection.	Whether you must enter a value in a custom attribute or not is determined by how the custom attribute was defined by your administrator in Metadata Command Center. Custom attributes are additional properties for Data Marketplace items that are defined by your administrator in Metadata Command Center. For more information about custom attributes, see the Create custom attributes for items topic in the Set Up Data Marketplace help.
customAttributes > value	Enter a value in the custom attribute.	-
customAttributes > id	Enter the system-generated unique identifier of the custom attribute.	For more information about how you can retrieve the system-generated unique identifier of a custom attribute, see Retrieve custom attributes.
stakeholdership > stakeholderId	Optional. Enter the system-generated unique identifier of the user account or user group that you want to assign as a stakeholder for the data collection.	- To get the system-generated unique identifier of a user account, navigate to My Services > Administrator > Users. On the Users page, click a user account. The user account page's URL contains the unique identifier. For example, in the URL /cloudUI/products/administer/main/usersAsset/0LH3xBJC9A6haZ26htGZyT, the unique identifier is 0LH3xBJC9A6haZ26htGZyT. - To get the system-generated unique identifier of a user group, navigate to My Services > Administrator > User Groups. On the User Groups page, click a user group. The user group page's URL contains the unique identifier. For example, in the URL /cloudUI/products/administer/main/userGroupsAsset/90uizkSWg0ycuu7hSNXSW4, the unique identifier is 90uizkSWg0ycuu7hSNXSW4.
stakeholdership > roleId	Optional. Enter the system-generated unique identifier of the user role that is assigned to the stakeholder that you specified in the stakeholderId parameter.	If you specify a value for the stakeholderId parameter, ensure that you also specify a value for the roleId parameter. To get the system-generated unique identifier of a user role, navigate to My Services > Administrator > User Roles. On the User Roles page, click a user role. The user role page's URL contains the unique identifier. For example, in the URL /cloudUI/products/administer/main/userRolesAsset/90uizkSWg0ycuu7hSNXSW4, the unique identifier is 90uizkSWg0ycuu7hSNXSW4.
termsOfUse	Optional. Enter the system-generated unique identifier of the terms of use that you want to associate with the data collection.	For more information about how you can use an API to get the system-generated unique identifier of a terms of use, see Retrieve terms of use.

Example request

The following example shows how you can use an API to create a data collection:

{
"externalId": "DCL-1",
"name": "Aggregated Sales Data",
"description": "Sales data from all sources (physical online subscription) in one place for easy analysis.",
"categoryId": "2593524d-82f7-4dfd-bc6b-17088c046f9d",
"status": "PUBLISHED",
"usageContexts": [
"2593524d-82f7-4dfd-bc6b-17088c046f9d"
],
"customAttributes": [
{
"value": "PROJ-2024-CUSTOMER-INSIGHTS",
"id": "com.infa.odin.models.custom.ca_2491832487117218775"
}
],
"stakeholdership": [
{
"stakeholderId": "jqPFaKmJRGhdfJ35eWUzoW",
"roleId": "5Qvy6Uiiq9IjoocWeJhccW"
}
],
"termsOfUse": [
"2593524d-82f7-4dfd-bc6b-17088c046f9d"
]
}

Response

When you invoke the API using a REST client, the client displays a response for the parameter values that you have entered.

The following example shows the response of an API call to create a data collection:

{
"id": "2593524d-82f7-4dfd-bc6b-17088c046f9d",
"externalId": "DCL-1",
"name": "Aggregated Sales Data",
"description": "All sales data from around the world aggregated and standardized.",
"status": "UNPUBLISHED",
"assetGroups": [
{
"id": "b93c4539-a93e-440d-a4b4-95d69b8911e6",
"name": "ASIA",
"isInherited": true
}
]
}

The following table describes the parameters of each data collection that is created:

Parameter	Description
externalId	Reference identifier of the data collection.
name	Name of the data collection.
description	Description of the data collection.
status	Status of the data collection. The status indicates whether the data collection is discoverable by Data Users when they search for it. A data collection can have one of the following statuses: - PUBLISHED. The data collection is discoverable to Data Users. - UNPUBLISHED. The data collection isn't discoverable to Data Users.
assetGroups	Details of the asset group that is assigned to the category that contains the data collection.
assetGroups > id	System-generated identifier of the asset group.
assetGroups > name	Name of the asset group.
assetGroups > isInherited	Indicates whether the asset group is directly assigned to the category or if the asset group is inherited from the category hierarchy. This parameter can have one of the following values: - true. The asset group is inherited from the category hierarchy. - false. The asset group is directly assigned to the category.