# Manage Purposes
This page describes the `governance` endpoint of the Immuta API and its request and response parameters used to manage purposes.
{% hint style="info" %}
Additional fields may be included in some responses you receive; however, these attributes are for internal purposes and are therefore undocumented.
{% endhint %}
## Governance workflow
1. [Create a purpose](#create-a-purpose).
2. [Search for purposes](#search-purposes).
3. [Update purposes](#update-a-purpose).
4. [Delete purposes](#delete-a-purpose).
## Create a purpose
`POST` `/governance/purpose`
Create a purpose.
#### Payload parameters
| Attribute | Description | Required |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| name | `string` The purpose name. | **Yes** |
| id | `integer` The ID of the purpose. | No |
| acknowledgement | `string` The purpose acknowledgement. | No |
| description | `string` The purpose description. | No |
| displayAcknowledgement | `boolean` When `true`, the `acknowledgement` text will display for users when they are prompted to agree to use the data in the project only for that purpose. **Default is `true`**. | No |
| deleted | `boolean` If `true`, the purpose has been deleted. | No |
| subpurposes | `array` A list of the sub-purposes. | No |
| staged | `boolean` If `true`, the purpose is staged. | No |
#### Response parameters
| Attribute | Description |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id | `integer` The purpose ID. |
| name | `string` The purpose name. |
| acknowledgement | `string` The purpose acknowledgement. |
| description | `string` The purpose description. |
| addedByProfile | `integer` The profile ID of the user who created the purpose. |
| displayAcknowledgement | `boolean` When `true`, the `acknowledgement` text is displayed for users when they are prompted to agree to use the data in the project only for that purpose. |
| deleted | `boolean` If `true`, the purpose has been deleted. |
| subpurposes | `array` A list of the sub-purposes. |
| staged | `boolean` If `true`, the purpose is staged. |
| createdAt | `timestamp` The date the purpose was created. |
| updatedAt | `timestamp` The date the purpose was last updated. |
### Request example
This example request with the payload below creates a new purpose.
```bash
curl \
--request POST \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
--data @example-payload.json \
https://demo.immuta.com/governance/purpose
```
#### Payload example
```json
{
"name": "Compliance Requirement #2"
}
```
### Response example
```json
{
"id": 10,
"name": "Compliance Requirement #2",
"acknowledgement": null,
"description": null,
"addedByProfile": 2,
"displayAcknowledgement": true,
"deleted": false,
"systemGenerated": false,
"createdAt": "2021-10-04T15:52:38.060Z",
"updatedAt": "2021-10-04T15:52:38.060Z",
"subpurposes": []
}
```
## Search purposes
| Method | Path | Purpose |
| ------ | --------------------------------- | ---------------------------------------------- |
| GET | `/governance/purpose` | [Search for purposes](#search-all-purposes). |
| GET | `/governance/purpose/{purposeId}` | [Get a purpose by ID](#search-purposes-by-id). |
### Search all purposes
`GET` `/governance/purpose`
Search for purposes.
#### Query parameters
| Attribute | Description | Required |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| offset | `integer` Used in combination with `size` to fetch pages. | No |
| size | `integer` The number of results to return per page. | No |
| noLimit | `boolean` When `true`, the number of results to return per page will not be limited to the number defined by `size`. **Default is `false`**. | No |
| sortField | `string` Used to sort results by field. **Default is `name`.** | No |
| sortOrder | `string` Sorts results by order, which must be `asc` or `desc`. **Default is `asc`.** | No |
| searchText | `string` Search for purpose names by text. | No |
| root | `string` Restrict results to provided root or sub-purposes of root. | No |
| strictSearch | `boolean` When `true`, will search for a complete match of the whole string provided in `searchText`. | No |
| getAffectedCount | `boolean` If `true`, returns the count of projects with each purpose. | No |
| includeDeleted | `boolean` If `true`, includes deleted purposes in the results. | No |
#### Response parameters
| Attribute | Description |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| count | `integer` The number of results. |
| purposes | `array` Information on each purpose returned, including `id`, `name`, `acknowledgement`, `description`, `subpurposes`, the creation date, and the staged status. |
#### Request example
This example request returns a list of all of the purposes.
```bash
curl \
--request GET \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://demo.immuta.com/governance/purpose
```
#### Response example
```json
{
"purposes": [
{
"id": 1,
"name": "Re-identification Prohibited",
"acknowledgement": "I agree to use the data associated with this project for the stated purpose of the project, and for that purpose only, as listed in the project's homepage, and to refrain from sharing that data outside of the project or Immuta. I also agree not to re-identify or take any steps to re-identify the individuals whose personal information is contained in the data sources attached to the project. In the event that these individuals have been identified or that I discover risks that I believe could lead to their identification, I agree to immediately notify the project owner or governance team and take immediate action to address and mitigate such risks. I further agree to refrain from contacting any individuals who might be identified.",
"description": null,
"addedByProfile": 1,
"displayAcknowledgement": true,
"deleted": false,
"systemGenerated": true,
"createdAt": "2021-08-16T20:25:44.423Z",
"updatedAt": "2021-09-30T00:36:25.215Z"
},
{
"id": 3,
"name": "Re-identification Prohibited.CCPA",
"acknowledgement": "I agree to use the data associated with this project for the stated purpose of the project, and for that purpose only, as listed in the project's homepage, and to refrain from sharing that data outside of the project or Immuta. I also agree not to re-identify or take any steps to re-identify the individuals whose personal information is contained in the data sources attached to the project. In the event that these individuals have been identified or that I discover risks that I believe could lead to their identification, I agree to immediately notify the project owner or governance team and take immediate action to address and mitigate such risks. I further agree to refrain from contacting any individuals who might be identified.",
"description": null,
"addedByProfile": 1,
"displayAcknowledgement": true,
"deleted": false,
"systemGenerated": true,
"createdAt": "2021-08-16T20:25:44.443Z",
"updatedAt": "2021-09-30T00:36:25.250Z"
},
{
"id": 2,
"name": "Re-identification Prohibited.Safe Harbor Method",
"acknowledgement": "I agree to use the data associated with this project for the stated purpose of the project, and for that purpose only, as listed in the project's homepage, and to refrain from sharing that data outside of the project or Immuta. I also agree not to re-identify or take any steps to re-identify the individuals whose health information is contained in the data sources attached to the project. In the event that these individuals have been identified or that I discover risks that I believe could lead to their identification, I agree to immediately notify the project owner or governance team and take immediate action to address and mitigate such risks. I further agree to refrain from contacting any individuals who might be identified.",
"description": null,
"addedByProfile": 1,
"displayAcknowledgement": true,
"deleted": false,
"systemGenerated": true,
"createdAt": "2021-08-16T20:25:44.434Z",
"updatedAt": "2021-09-30T00:36:25.234Z"
},
{
"id": 4,
"name": "Use Case Outside De-identification",
"acknowledgement": "I agree to use the data associated with this project for the stated purpose of the project, and for that purpose only, as listed in the project's homepage, and to refrain from sharing that data outside of the project or Immuta. In the event that I discover risks that I believe could lead to unauthorized access, I agree to immediately notify the project owner or governance team and take immediate action to address and mitigate such risks.",
"description": null,
"addedByProfile": 1,
"displayAcknowledgement": true,
"deleted": false,
"systemGenerated": true,
"createdAt": "2021-08-16T20:25:44.452Z",
"updatedAt": "2021-09-30T00:36:25.270Z"
}
],
"count": 4
}
```
### Search purposes by ID
`GET` `/governance/purpose/{purposeId}`
Get a purpose by ID.
#### Query parameters
| Attribute | Description | Required |
| ------------------ | ------------------------------------------------------------------ | -------- |
| purposeId | `integer` The purpose ID. | **Yes** |
| includeSubpurposes | `boolean` If `true`, sub-purposes will be included in the results. | No |
#### Response parameters
| Attribute | Description |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id | `integer` The purpose ID. |
| name | `string` The purpose name. |
| acknowledgement | `string` The purpose acknowledgement. |
| description | `string` The purpose description. |
| addedByProfile | `integer` The profile ID of the user who created the purpose. |
| displayAcknowledgement | `boolean` When `true`, the `acknowledgement` text is displayed for users when they are prompted to agree to use the data in the project only for that purpose. |
| deleted | `boolean` If `true`, the purpose has been deleted. |
| subpurposes | `array` A list of the sub-purposes. |
| staged | `boolean` If `true`, the purpose is staged. |
| createdAt | `timestamp` The date the purpose was created. |
| updatedAt | `timestamp` The date the purpose was last updated. |
#### Request example
This example request returns information on the purpose with the ID `1`, including its sub-purposes.
```bash
curl \
--request GET \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://demo.immuta.com/governance/purpose/1?includeSubpurposes=true
```
#### Response example
```json
{
"name": "Re-identification Prohibited",
"acknowledgement": "I agree to use the data associated with this project for the stated purpose of the project, and for that purpose only, as listed in the project's homepage, and to refrain from sharing that data outside of the project or Immuta. I also agree not to re-identify or take any steps to re-identify the individuals whose personal information is contained in the data sources attached to the project. In the event that these individuals have been identified or that I discover risks that I believe could lead to their identification, I agree to immediately notify the project owner or governance team and take immediate action to address and mitigate such risks. I further agree to refrain from contacting any individuals who might be identified.",
"description": null,
"addedByProfile": 1,
"displayAcknowledgement": true,
"deleted": false,
"systemGenerated": true,
"id": 1,
"createdAt": "2021-08-16T20:25:44.423Z",
"updatedAt": "2021-09-30T00:36:25.215Z",
"addedBy": "Immuta System Account",
"projectCount": 1,
"projects": [
1
],
"subpurposes": [
{
"id": 3,
"name": "Re-identification Prohibited.CCPA",
"acknowledgement": "I agree to use the data associated with this project for the stated purpose of the project, and for that purpose only, as listed in the project's homepage, and to refrain from sharing that data outside of the project or Immuta. I also agree not to re-identify or take any steps to re-identify the individuals whose personal information is contained in the data sources attached to the project. In the event that these individuals have been identified or that I discover risks that I believe could lead to their identification, I agree to immediately notify the project owner or governance team and take immediate action to address and mitigate such risks. I further agree to refrain from contacting any individuals who might be identified.",
"description": null,
"addedByProfile": 1,
"displayAcknowledgement": true,
"deleted": false,
"systemGenerated": true,
"createdAt": "2021-08-16T20:25:44.443Z",
"updatedAt": "2021-09-30T00:36:25.250Z",
"projectCount": 0,
"projects": [],
"addedBy": "Immuta System Account"
},
{
"id": 2,
"name": "Re-identification Prohibited.Safe Harbor Method",
"acknowledgement": "I agree to use the data associated with this project for the stated purpose of the project, and for that purpose only, as listed in the project's homepage, and to refrain from sharing that data outside of the project or Immuta. I also agree not to re-identify or take any steps to re-identify the individuals whose health information is contained in the data sources attached to the project. In the event that these individuals have been identified or that I discover risks that I believe could lead to their identification, I agree to immediately notify the project owner or governance team and take immediate action to address and mitigate such risks. I further agree to refrain from contacting any individuals who might be identified.",
"description": null,
"addedByProfile": 1,
"displayAcknowledgement": true,
"deleted": false,
"systemGenerated": true,
"createdAt": "2021-08-16T20:25:44.434Z",
"updatedAt": "2021-09-30T00:36:25.234Z",
"addedBy": "Immuta System Account",
"projectCount": 0,
"projects": []
}
]
}
```
## Update a purpose
`PUT` `/governance/purpose/{purposeId}`
Update a purpose.
**Required Immuta permission**: `GOVERNANCE`
#### Query parameters
| Attribute | Description | Required |
| --------- | ------------------------- | -------- |
| purposeId | `integer` The purpose ID. | **Yes** |
#### Payload parameters
| Attribute | Description | Required |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| name | `string` The purpose name. | No |
| acknowledgement | `string` The purpose acknowledgement. | No |
| description | `string` The purpose description. | No |
| displayAcknowledgement | `boolean` When `true`, the `acknowledgement` text will display for users when they are prompted to agree to use the data in the project only for that purpose. **Default is `true`**. | No |
| reAcknowledge | `boolean` When `true`, users will have to re-acknowledge the purpose after it is updated. | No |
| applyToSubpurposes | `boolean` It `true`, the updates will be applied to the sub-purposes. | No |
#### Response parameters
| Attribute | Description |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id | `integer` The purpose ID. |
| name | `string` The purpose name. |
| acknowledgement | `string` The purpose acknowledgement. |
| description | `string` The purpose description. |
| addedByProfile | `integer` The profile ID of the user who created the purpose. |
| displayAcknowledgement | `boolean` When `true`, the `acknowledgement` text is displayed for users when they are prompted to agree to use the data in the project only for that purpose. |
| deleted | `boolean` If `true`, the purpose has been deleted. |
| subpurposes | `array` A list of the sub-purposes. |
| staged | `boolean` If `true`, the purpose is staged. |
| createdAt | `timestamp` The date the purpose was created. |
| updatedAt | `timestamp` The date the purpose was last updated. |
### Request example
This example request with the payload below will update the description of the purpose with the ID `8`.
```bash
curl \
--request PUT \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
--data @example-payload.json \
https://demo.immuta.com/governance/purpose/8
```
#### Payload example
```json
{
"description": "This requirement has been amended to include an updated model."
}
```
### Response example
```json
{
"id": 8,
"name": "Compliance Requirement #1",
"acknowledgement": null,
"description": "This requirement has been amended to include an updated model.",
"addedByProfile": 2,
"displayAcknowledgement": true,
"deleted": false,
"systemGenerated": false,
"createdAt": "2021-10-01T21:08:00.517Z",
"updatedAt": "2021-10-04T14:21:59.834Z"
}
```
## Delete a purpose
`DELETE` `/governance/purpose/{purposeId}`
Delete the purpose with the given ID and its associated sub-purposes.
**Required Immuta permission**: `GOVERNANCE`
#### Query parameters
| Attribute | Description | Required |
| --------- | ------------------------- | -------- |
| purposeId | `integer` The purpose ID. | **Yes** |
#### Response parameters
| Attribute | Description |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id | `integer` The purpose ID. |
| name | `string` The purpose name. |
| acknowledgement | `string` The purpose acknowledgement. |
| description | `string` The purpose description. |
| addedByProfile | `integer` The profile ID of the user who created the purpose. |
| displayAcknowledgement | `boolean` When `true`, the `acknowledgement` text is displayed for users when they are prompted to agree to use the data in the project only for that purpose. |
| deleted | `boolean` If `true`, the purpose has been deleted. |
| subpurposes | `array` A list of the sub-purposes. |
| staged | `boolean` If `true`, the purpose is staged. |
| createdAt | `timestamp` The date the purpose was created. |
| updatedAt | `timestamp` The date the purpose was last updated. |
### Request example
This example request deletes the purpose with the ID `8`.
```bash
curl \
--request DELETE \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://demo.immuta.com/governance/purpose/8
```
### Response example
```json
[
{
"id": 8,
"name": "Compliance Requirement #1",
"acknowledgement": null,
"description": "This requirement has been amended to include an updated model.",
"addedByProfile": 2,
"displayAcknowledgement": true,
"deleted": true,
"systemGenerated": false,
"createdAt": "2021-10-01T21:08:00.517Z",
"updatedAt": "2021-10-04T14:27:07.203Z"
}
]
```