Manage Purposes
Governance API reference guide
This page describes the governance
endpoint of the Immuta API and its request and response parameters used to manage purposes.
Governance workflow
Create a purpose
POST
/governance/purpose
Create a purpose.
Payload parameters
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
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.
curl \
--request POST \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
--data @example-payload.json \
https://demo.immuta.com/governance/purpose
Payload example
{
"name": "Compliance Requirement #2"
}
Response example
{
"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
Search all purposes
GET
/governance/purpose
Search for purposes.
Query parameters
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
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.
curl \
--request GET \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://demo.immuta.com/governance/purpose
Response example
{
"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
purposeId
integer
The purpose ID.
Yes
includeSubpurposes
boolean
If true
, sub-purposes will be included in the results.
No
Response parameters
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.
curl \
--request GET \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://demo.immuta.com/governance/purpose/1?includeSubpurposes=true
Response example
{
"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.
Query parameters
purposeId
integer
The purpose ID.
Yes
Payload parameters
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
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
.
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
{
"description": "This requirement has been amended to include an updated model."
}
Response example
{
"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.
Query parameters
purposeId
integer
The purpose ID.
Yes
Response parameters
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
.
curl \
--request DELETE \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://demo.immuta.com/governance/purpose/8
Response example
[
{
"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"
}
]
Last updated
Was this helpful?