1 of 1

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.

Additional fields may be included in some responses you receive; however, these attributes are for internal purposes and are therefore undocumented.

Create a purpose

POST /governance/purpose

Create a purpose.

Payload parameters

Attribute

Description

Required

Response parameters

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,
  "policyMetadata": null,
  "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

Response parameters

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,
      "policyMetadata": null,
      "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,
      "policyMetadata": null,
      "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,
      "policyMetadata": null,
      "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,
      "policyMetadata": null,
      "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

Response parameters

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,
  "policyMetadata": null,
  "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,
      "policyMetadata": null,
      "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,
      "policyMetadata": null,
      "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

Payload parameters

Response parameters

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,
  "policyMetadata": null,
  "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

Response parameters

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,
    "policyMetadata": null,
    "createdAt": "2021-10-01T21:08:00.517Z",
    "updatedAt": "2021-10-04T14:27:07.203Z"
  }
]

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.

Additional fields may be included in some responses you receive; however, these attributes are for internal purposes and are therefore undocumented.

Governance workflow

Create a purpose.
Search for purposes.
Update purposes.
Delete purposes.

Create a purpose

POST /governance/purpose

Create a purpose.

Payload parameters

Attribute

Description

Required

Response parameters

Attribute

Description

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,
  "policyMetadata": null,
  "createdAt": "2021-10-04T15:52:38.060Z",
  "updatedAt": "2021-10-04T15:52:38.060Z",
  "subpurposes": []
}

Search purposes

Method

Path

Purpose

Search all purposes

GET /governance/purpose

Search for purposes.

Query parameters

Attribute

Description

Required

Response parameters

Attribute

Description

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,
      "policyMetadata": null,
      "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,
      "policyMetadata": null,
      "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,
      "policyMetadata": null,
      "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,
      "policyMetadata": null,
      "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

Response parameters

Attribute

Description

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,
  "policyMetadata": null,
  "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,
      "policyMetadata": null,
      "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,
      "policyMetadata": null,
      "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

Attribute

Description

Required

Payload parameters

Attribute

Description

Required

Response parameters

Attribute

Description

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,
  "policyMetadata": null,
  "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

Attribute

Description

Required

Response parameters

Attribute

Description

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,
    "policyMetadata": null,
    "createdAt": "2021-10-01T21:08:00.517Z",
    "updatedAt": "2021-10-04T14:27:07.203Z"
  }
]