API Reference > Define settings for data collections > Terms of use

Terms of use

The terms of use provide usage requirements and guidelines that a Data User must accept to use the data.

Create terms of use

Use REST APIs to create terms of use in Data Marketplace.

Endpoint and method

The following table describes the connection properties for the API:

Property	Description
Endpoint	/api/v1/integration/termsOfUse
Method	POST

Request

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

Parameter	Description	Additional Information
refId	Optional. Enter a reference identifier for the terms of use.	If you don't specify a reference identifier, Data Marketplace automatically assigns a unique value to the object. 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 terms of use.	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 the terms of use as "Internal Use Only" while a terms of use called "Internal use only" already exists, the API call fails.
description	Required. Enter a description for the terms of use.	-
type	Required. Specify a type for the terms of use.	Enter one of the following values: - ACCESSIBLE - CONTROLLED - RESTRICTED
status	Required. Specify a status for the terms of use. The status determines whether the terms of use are available to be added to data collections.	Enter one of the following values: - To make the terms of use available, enter ENABLED . - To make the terms of use unavailable, enter DISABLED .
acknowledgement	Required. Configure whether you want the Data User to acknowledge the terms of use when they place an order.	Enter one of the following values: - If you want the Data User to acknowledge the terms of use when they place an order, enter true . - If you don't want the Data User to acknowledge the terms of use when they place an order, enter false .
referenceLink	Optional. Enter the uniform resource identifier of the resource or location where the data is stored or maintained.	-

Example request

The following example shows how you can use an API to create terms of use:

{
"items": [
{
"refId": "Term23",
"name": "Company use only",
"description": "This data should not be accessed by non-company personnel.",
"status": "ENABLED",
"type": "CONTROLLED",
"acknowledgement": true,
"referenceLink": "sample link"
},
{
"refId": "Term22",
"name": "Client confidential",
"description": "Use this for data to be shared with authorized third parties.",
"status": "DISABLED",
"type": "CONTROLLED",
"acknowledgement": false,
"referenceLink": "sample link"
}
]
}

Response

When you pass the API payload in the 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 terms of use:

{
"processingTime": 13051,
"objects": [
{
"index": 1,
"id": "5f674ca5-f2d1-4465-9576-dae6ff4cf7c0",
"refId": "Term23",
"name": "Company use only"
},
{
"index": 2,
"id": "3893741f-e9cf-4a7e-85de-0d200fe7ddf4",
"refId": "Term22",
"name": "Client confidential"
}
]
}

The following table describes the parameters of each terms of use that is created:

Parameter	Description
index	The position of the terms of use in the objects JSON array. This value does not impact how the terms of use is used by a Data Marketplace user.
id	System generated unique identifier of the terms of use.
refId	Reference identifier of the terms of use.
name	Name of the terms of use.

Retrieve terms of use

Use REST APIs to retrieve the details of terms of use in Data Marketplace.

Endpoint and method

The following table describes the connection properties for the API:

Property	Description
Endpoint	/api/v1/integration/termsOfUse
Method	GET

Note: Before you call this API, consider the following:

•If you use an Application Integration system service action to invoke this API, you can call a maximum of 100 APIs per minute.
•If you use JWT authentication to invoke this API, you can call a maximum of 120 APIs per minute and 10,000 APIs per day.

For more information, see How to call a Data Marketplace API.

Request

The following table describes the parameters that you enter in the request query:

Parameter	Description	Additional Information
ids	Optional. Enter the system generated unique identifier of a terms of use.	To enter more than one value, use the following format: ids=<value1>&ids=<value2>
search	Optional. Enter the search term that you want to use to find a terms of use.	Ensure that the search term that you enter don't contain an asterisk (*).
fields	Optional. Enter the fields on which the search term applies. The terms that you entered in the search field parameter are used to search the fields that you specify here.	Enter the following values: - NAME - DESCRIPTION
createdDateFrom	Optional. To find terms of use that were created between a date range, enter the initial date when the terms of use were created.	To specify a date, use the YYYY-MM-DD format. The value that you specify is automatically converted and stored in the Coordinated Universal Time (UTC) time standard. If you have specified a value for the createdDateFrom parameter, ensure that you also enter a value for the createdDateTo parameter.
createdDateTo	Optional. To find terms of use that were created between a date range, enter the latest date when the terms of use were created.	To specify a date, use the YYYY-MM-DD format. The value that you specify is automatically converted and stored in the Coordinated Universal Time (UTC) time standard. If you have specified a value for the createdDateTo parameter, ensure that you also enter a value for the createdDateFrom parameter.
modifiedDateFrom	Optional. To find terms of use that were modified between a date range, enter the initial date when the terms of use were modified.	To specify a date, use the YYYY-MM-DD format. The value that you specify is automatically converted and stored in the Coordinated Universal Time (UTC) time standard. If you have specified a value for the modifiedDateFrom parameter, ensure that you also enter a value for the modifiedDateTo parameter.
modifiedDateTo	Optional. To find terms of use that were modified between a date range, enter the latest date when the terms of use were modified.	To specify a date, use the YYYY-MM-DD format. The value that you specify is automatically converted and stored in the Coordinated Universal Time (UTC) time standard. If you have specified a value for the modifiedDateTo parameter, ensure that you also enter a value for the modifiedDateFrom parameter.
status	Optional. Specify the status of the terms of use. The status indicates whether the terms of use are available to be added to data collections.	Enter one of the following values: - To find the terms of use are available to be added to data collections, enter ENABLED. - To find the terms of use aren't available to be added to data collections, enter DISABLED.
type	Optional. Specify the type of the terms of use.	Enter one of the following types: - ACCESSIBLE - CONTROLLED - RESTRICTED
sortByField	Optional. Specify the parameters to sort the search results.	To sort the search results, enter one of the following values: - NAME - STATUS - TYPE - ID - CREATED_BY - CREATED_ON - MODIFIED_BY - MODIFIED_ON Default value is MODIFIED_ON.
sort	Optional. Set the sorting order of the search results.	You can sort the search results in the following order: - To sort the search results by ascending order, enter ASC. - To sort the search results by descending order, enter DESC. Default value is DESC.
offset	Optional. Enter the starting index for the paginated results.	Default value is 0.
limit	Optional. Enter the maximum number of results.	Default value is 50. Maximum value is 100.

Note: The API has no payload.

Example request

The following example shows how you can use an API to retrieve terms of use:

https://{{CDMP_URL}}/api/v1/integration/termsOfUse?search=SK&fields=NAME&fields=DESCRIPTION&ids=7bb0bcc1-23a9-4ffc-9f39-50c7b4df91b0&status=ENABLED&type=CONTROLLED&createdDateFrom=2022-01-01&createdDateTo=2022-12-01&modifiedDateFrom=2022-01-01&modifiedDateTo=2022-12-01&sortByField=MODIFIED_ON&sort=DESC&offset=0&limit=1

Response

When you pass the API query parameters in the 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 retrieve terms of use:

{
"processingTime": 4779,
"offset": 0,
"limit": 1,
"totalCount": 2,
"objects": [
{
"id": "5f674ca5-f2d1-4465-9576-dae6ff4cf7c0",
"refId": "Term23",
"name": "Company use only"
"description": "This data should not be accessed by non-company personnel.",
"type": "CONTROLLED",
"status": "ENABLED",
"acknowledgement": true,
"referenceLink": null,
"createdBy": "5tSQ0vG66z9jS0KBQkY84r",
"createdOn": "2022-05-17T10:05:21.453Z",
"modifiedBy": "5tSQ0vG66z9jS0KBQkY84r",
"modifiedOn": "2022-05-17T10:06:57.433Z"
}
]
}

The following table describes the parameters of each terms of use that is retrieved:

Parameter	Description
offset	Starting index for the paginated results.
limit	Maximum number of results.
totalCount	Number of terms of use retrieved.
id	System generated unique identifier of the terms of use.
refId	Reference identifier of the terms of use.
name	Name of the terms of use.
description	Description of the terms of use.
type	Type of the terms of use that apply to the ordered data collection. A terms of use can have one of the following types: - ACCESSIBLE - CONTROLLED - RESTRICTED
status	The status indicates whether the terms of use are available to be added to data collections. A terms of use can have one of the following statuses: - ENABLED. The terms of use are available to be added to data collections. - DISABLED. The terms of use isn't available to be added to data collections.
acknowledgement	This parameter indicates whether the Data User is required to acknowledge the terms of use when they place an order. The parameter can be one of the following values: - true. The Data User must acknowledge the terms of use when they place an order. - false. The Data User doesn't need to acknowledge the terms of use when they place an order.
referenceLink	Uniform resource identifier of the terms of use.

Modify terms of use

Use REST APIs to modify terms of use in Data Marketplace.

Endpoint and method

The following table describes the connection properties for the API:

Property	Description
Endpoint	/api/v1/integration/termsOfUse
Method	PUT

Request

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

Parameter	Description	Additional Information
id	Required. Enter the system generated unique identifier of the terms of use that you want to modify.	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.
refId	Optional. Enter a reference identifier for the terms of use.	If you don't specify a reference identifier, Data Marketplace automatically assigns a unique value to the object. 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 terms of use.	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 the terms of use as "Internal Use Only" while a terms of use called "Internal use only" already exists, the API call fails.
description	Required. Enter a description for the terms of use.	-
type	Required. Specify a type for the terms of use.	Enter one of the following values: - ACCESSIBLE - CONTROLLED - RESTRICTED
status	Required. Specify a status for the terms of use. The status determines whether the terms of use are available to be added to data collections.	Enter one of the following values: - To make the terms of use available, enter ENABLED . - To make the terms of use unavailable, enter DISABLED .
type	Required. Specify a type for the terms of use.	Enter one of the following values: - ACCESSIBLE - CONTROLLED - RESTRICTED
acknowledgement	Required. Configure whether you want the Data User to acknowledge the terms of use when they place an order.	Enter one of the following values: - If you want the Data User to acknowledge the terms of use when they place an order, enter true . - If you don't want the Data User to acknowledge the terms of use when they place an order, enter false .
referenceLink	Optional. Enter the uniform resource identifier of the resource or location where the data is stored or maintained.	-

Example request

The following example shows how you can use an API to modify a terms of use:

{
"items": [
{
"id": "5f674ca5-f2d1-4465-9576-dae6ff4cf7c0",
"refId": "Term23",
"name": "Company use only",
"description": "This data should not be accessed by non-company personnel.",
"status": "ENABLED",
"type": "CONTROLLED",
"acknowledgement": true,
"referenceLink": "sample link"
},
{
"id": "3893741f-e9cf-4a7e-85de-0d200fe7ddf4",
"refId": "Term22",
"name": "Client confidential",
"description": "Use this for data to be shared with authorized third parties.",
"status": "DISABLED",
"type": "CONTROLLED",
"acknowledgement": false,
"referenceLink": "sample link"
}
]
}

Response

When you pass the API payload in the 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 modify a terms of use:

{
"processingTime": 12351,
"objects": [
{
"index": 1,
"id": "5f674ca5-f2d1-4465-9576-dae6ff4cf7c0",
"refId": "Term23",
"name": "Company use only"
},
{
"index": 2,
"id": "3893741f-e9cf-4a7e-85de-0d200fe7ddf4",
"refId": "Term22",
"name": "Client confidential"
}
]
}

The following table describes the parameters of each terms of use that is modified:

Parameter	Description
index	The position of the terms of use in the objects JSON array. This value does not impact how the terms of use is used by a Data Marketplace user.
id	System generated unique identifier of the terms of use.
refId	Reference identifier of the terms of use.
name	Name of the terms of use.

Update the status of a terms of use

Use REST APIs to enable or disable terms of use in Data Marketplace.

Endpoint and method

The following table describes the connection properties for the API:

Property	Description
Endpoint	/api/v1/integration/termsOfUse/status
Method	PATCH

Request

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

Parameter	Description	Additional Information
id	Required. Enter the system generated unique identifier of the terms of use.	For more information about how you can use an API to get the unique identifier of a terms of use, see Retrieve terms of use.
status	Required. Specify a status for the terms of use. The status determines whether the terms of use are available to be added to data collections.	Enter one of the following values: - To make the terms of use available, enter ENABLED . - To make the terms of use unavailable, enter DISABLED .

Example request

The following example shows how you can use an API to update the status of a terms of use:

{
"items": [
{
"id": "7bb0bcc1-23a9-4ffc-9f39-50c7b4df91b0",
"status": "ENABLED"
},
{
"id": "f8504f82-3b26-41b8-ad1c-eea5d1a2a343",
"status": "ENABLED"
}
]
}

Response

When you pass the API payload in the REST client, the client displays a response for the parameter values that you have entered.

If you see the following response code, it means that the status of the terms of use is updated successfully:

204 OK