Manage Projects

Projects API reference guide

This page details how to use the projects API to query projects and the data sources associated with them in Immuta.

Projects workflow

1. Create a project.

2. Search for Immuta projects.

3. Manage your Immuta projects.

4. Manage project members.

5. Manage project data sources.

6. Use projects.

7. Delete projects.

Create a project

POST /project

Create the project.

Payload parameters

Attribute	Description	Required
id	integer Project ID.	Yes
projectKey	string Name of the project.	Yes
name	string Name of the project.	Yes
status	string (Accepted statuses are open or closed.)	Yes
description	string Project description.	No
documentation	string Project documentation.	No
tags	array Project tags.	No
purposes	array Project purposes.	No
stagedPurposes	array Project purposes staged for approval.	No
deleted	boolean If true, the project will be deleted.	No
snowflake	array This enables a Snowflake workspace for the project and details the schema, hostname, and warehouse.	No
allowMaskedJoins	boolean If true, masked joins will be allowed.	No
subscriptionPolicy	array[object] A policy object for the Subscription Policy on the project. Details include type, exceptions, conditions, allowDiscovery, and automaticSubscription. If this is not set, it will be the default manual.	No
subscriptionType	string The type of subscription policy on the project. The type can be automatic (which allows anyone to subscribe), approval (which requires the subscriber to be manually approved), policy (which only allows users with specific groups or attributes to subscribe), or manual (which requires users to be manually added).	No
equalization	array Details the policy conditions of the equalization, including the configured (or recommended) user groups and attributes.	No
workspace	array Information on workspaces in the project.	No
type	string The type of Immuta project, either user created project (user) or system generated project (schema).	No
createdAt	timestamp Date of the project creation.	No
updatedAt	timestamp Date of the most recent update.	No

Response parameters

Attribute	Description
id	integer Project ID.
projectKey	string Name of the project.
name	string Name of the project.
status	string (Statuses are open or closed.)
description	string Project description.
documentation	string Project documentation.
tags	array Project tags.
purposes	array Project purposes.
stagedPurposes	array Project purposes staged for approval.
deleted	boolean If true, the project has been deleted.
snowflake	array If a Snowflake workspace has been enabled for the project, this attribute will detail the schema, hostname, and warehouse.
allowMaskedJoins	boolean If true, masked joins are allowed.
subscriptionPolicy	array[object] A policy object for the Subscription Policy on the project. Details include type, exceptions, conditions, allowDiscovery, and automaticSubscription.
subscriptionType	string The type of subscription policy on the project. The type can be automatic (which allows anyone to subscribe), approval (which requires the subscriber to be manually approved), policy (which only allows users with specific groups or attributes to subscribe), or manual (which requires users to be manually added).
equalization	array Details the policy conditions of the equalization, including the configured (or recommended) user groups and attributes.
workspace	array Information on workspaces in the project.
type	string The type of Immuta project, either user created project (user) or system generated project (schema).
createdAt	timestamp Date of the project creation.
updatedAt	timestamp Date of the most recent update.
workspaceWarnings	string This message describes issues with the created workspace.

Example request

This example request with the payload below will create a new project.

curl \
  --request POST \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer dea464c07bd07300095caa8" \
  --data @example-payload.json \
  https://demo.immuta.com/project

Example request payload

This example payload will create a new project named API Project.

{
  "id": 4,
  "projectKey": "api project",
  "name": "API Project",
  "status": "open",
  "description": "project created with api",
  "deleted": false,
  "allowMaskedJoins": false,
  "createdAt": "2021-09-10",
  "updatedAt": "2021-09-10"
}

Example response

{
  "id": 4,
  "projectKey": "api project",
  "name": "API Project",
  "status": "open",
  "description": "project created with api",
  "documentation": "# API Project",
  "deleted": false,
  "allowMaskedJoins": false,
  "subscriptionType": "manual",
  "subscriptionPolicy": null,
  "equalization": null,
  "workspace": null,
  "snowflake": null,
  "type": null,
  "schema": null,
  "createdBy": 2,
  "updatedBy": 2,
  "createdAt": "2021-09-10T00:00:00.000Z",
  "updatedAt": "2021-09-10T00:00:00.000Z",
  "schemaEvolutionId": null,
  "purposes": [],
  "stagedPurposes": []
}

Search projects

Method	Path	Purpose
GET	/project	Search for projects.
GET	/project/{projectId}	Get the project with the given ID.

Search all projects

GET /project

Search for projects.

Query parameters

Attribute	Description	Required
offset	integer Used in combination with size to fetch pages. The default is 0.	No
size	integer The number of results to return per page.	No
sortField	string Used to sort results by field.	No
sortOrder	string Sorts results by order, which must be asc or desc. The default is asc.	No
subscription	array[string] Filters projects by subscription types, which must be automatic, approval, or policy.	No
status	array[string] Filters projects based on their status: open or closed.	No
searchText	string Searches text. By default this will filter projects by name, description, documentation, category, and organization.	No
tag	array[string] Filters projects by tags associated with the projects.	No
nameOnly	boolean If true, searchText will only filter by project name, allowing you to retrieve specific projects. The default is false.	No
isEqualized	boolean If true, only equalized projects will be included.	No
snowflake	boolean If true, only projects with a Snowflake workspace will be included.	No
dataSourceId	integer Filters projects by whether they have the data source associated with the data source ID.	No
mode	integer Specifies the query mode, which must be 0 (FULL), 1 (COUNT), 4 (TAG), 5 (MIN_MAX), or 6 (STATUS).	No

Response parameters

Attribute	Description
count	integer Number of projects found.
hits	array Details about each project listed.
id	integer The project ID.
projectKey	string Name of the project.
name	string Name of the project.
status	string Statuses are open or closed.
description	string Project description.
documentation	string Project documentation.
tags	array Project tags.
purposes	array Project purposes.
stagedPurposes	array Project purposes staged for approval.
deleted	boolean If true, the project has been deleted.
snowflake	array If a Snowflake workspace has been enabled for the project, this attribute will detail the schema, hostname, and warehouse.
allowMaskedJoins	boolean If true, masked joins are allowed.
subscriptionPolicy	array[object] A policy object for the Subscription Policy on the project. Details include type, exceptions, conditions, allowDiscovery, and automaticSubscription.
subscriptionType	string The type of subscription policy on the project. The type can be automatic (which allows anyone to subscribe), approval (which requires the subscriber to be manually approved), policy (which only allows users with specific groups or attributes to subscribe), or manual (which requires users to be manually added).
equalization	array Details the policy conditions of the equalization, including the configured (or recommended) user groups and attributes.
workspace	array Information on workspaces in the project.
type	string The type of Immuta project, either user created project (user) or system generated project (schema).
createdAt	timestamp Date of the project creation.
updatedAt	timestamp Date of the most recent update.
acknowledgeRequired	boolean When true, the requesting user has not yet agreed to the project acknowledgement.
subscriptionId	integer The project member's subscription ID.
subscribedAsUser	boolean If true, the user running the request is currently subscribed.
subscriptionStatus	string Subscription status of the user running the request.
filterId	integer Corresponds with the ID of the project.
facets	array Facets (categories) relevant to the search.

Request example

This example request gets a list of all of the projects.

curl \
  --request GET \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer dea464c07bd07300095caa8" \
  https://demo.immuta.com/project

Response example

{
  "hits": [
    {
      "id": 8,
      "name": "Improving Employee Onboarding and Retention",
      "status": "open",
      "description": null,
      "deleted": false,
      "updatedAt": "2021-07-14T23:14:46.210Z",
      "subscriptionPolicy": null,
      "createdAt": "2021-07-14T23:13:53.752Z",
      "filterId": 8,
      "subscriptionType": "manual",
      "isEqualized": false,
      "acknowledgeRequired": false,
      "subscriptionStatus": "not_subscribed",
      "purposeCount": 1,
      "hasDeletedPurposes": false,
      "workspace": null,
      "type": null,
      "allowMaskedJoins": false
    },
    {
      "id": 4,
      "name": "Medical Records",
      "status": "open",
      "description": "This project contains all data sources under the schema, medical_records, from [e-mail]:1433/example.",
      "deleted": false,
      "updatedAt": "2021-06-22T23:24:58.766Z",
      "subscriptionPolicy": null,
      "createdAt": "2021-06-22T23:24:58.766Z",
      "filterId": 4,
      "subscriptionType": "manual",
      "isEqualized": false,
      "acknowledgeRequired": false,
      "subscriptionStatus": "owner",
      "purposeCount": 0,
      "hasDeletedPurposes": false,
      "workspace": null,
      "type": "Schema",
      "allowMaskedJoins": false
    },
    {
      "id": 6,
      "name": "sample123",
      "status": "open",
      "description": null,
      "deleted": false,
      "updatedAt": "2021-07-12T21:32:37.020Z",
      "subscriptionPolicy": null,
      "createdAt": "2021-07-12T21:32:37.012Z",
      "filterId": 6,
      "subscriptionType": "manual",
      "isEqualized": false,
      "acknowledgeRequired": false,
      "subscriptionStatus": "not_subscribed",
      "purposeCount": 1,
      "hasDeletedPurposes": false,
      "workspace": null,
      "type": null,
      "allowMaskedJoins": false
    },
    {
      "id": 2,
      "name": "test",
      "status": "open",
      "description": null,
      "deleted": false,
      "updatedAt": "2021-07-19T20:48:00.758Z",
      "subscriptionPolicy": null,
      "createdAt": "2021-05-19T22:50:44.190Z",
      "filterId": 2,
      "subscriptionType": "manual",
      "isEqualized": false,
      "acknowledgeRequired": false,
      "subscriptionStatus": "owner",
      "purposeCount": 2,
      "hasDeletedPurposes": false,
      "workspace": null,
      "type": null,
      "allowMaskedJoins": false
    },
    {
      "id": 3,
      "name": "Tpc",
      "status": "open",
      "description": "This project contains all data sources under the schema, tpc, from [e-mail]:1433/example.",
      "deleted": false,
      "updatedAt": "2021-05-20T16:29:09.679Z",
      "subscriptionPolicy": null,
      "createdAt": "2021-05-20T16:29:09.679Z",
      "filterId": 3,
      "subscriptionType": "manual",
      "isEqualized": false,
      "acknowledgeRequired": false,
      "subscriptionStatus": "owner",
      "purposeCount": 0,
      "hasDeletedPurposes": false,
      "workspace": null,
      "type": "Schema",
      "allowMaskedJoins": false
    }
  ],
  "facets": {},
  "count": 5
}

Search for projects by ID

GET /project/{projectId}

Get the project with the given ID.

Query parameters

Attribute	Description	Required
projectId	integer The project ID.	Yes
checkForSqlAccount	boolean Default is true.	No

Response parameters

Attribute	Description
id	integer Project ID.
projectKey	string Name of the project.
name	string Name of the project.
status	string Statuses are open or closed.
description	string Project description.
documentation	string Project documentation.
tags	array Project tags.
purposes	array Project purposes.
stagedPurposes	array Project purposes staged for approval.
deleted	boolean If true, the project has been deleted.
snowflake	array If a Snowflake workspace has been enabled for the project, this attribute will detail the schema, hostname, and warehouse.
allowMaskedJoins	boolean If true, masked joins are allowed.
subscriptionPolicy	array[object] A policy object for the Subscription Policy on the project. Details include type, exceptions, conditions, allowDiscovery, and automaticSubscription.
subscriptionType	string The type of subscription policy on the project. The type can be automatic (which allows anyone to subscribe), approval (which requires the subscriber to be manually approved), policy (which only allows users with specific groups or attributes to subscribe), or manual (which requires users to be manually added).
equalization	array Details the policy conditions of the equalization, including the configured (or recommended) user groups and attributes.
workspace	array Information on workspaces in the project.
type	string The type of Immuta project, either user created project (user) or system generated project (schema).
createdAt	timestamp Date of the project creation.
updatedAt	timestamp Date of the most recent update.
acknowledgeRequired	boolean When true, the requesting user has not yet agreed to the project acknowledgement.
subscriptionId	integer The project member's subscription ID.
subscribedAsUser	boolean If true, the user running the request is currently subscribed.
subscriptionStatus	string Subscription status of the user running the request.

Example request

This example gets the project object for the project with the ID 2.

curl \
  --request GET \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer dea464c07bd07300095caa8" \
  https://demo.immuta.com/project/2

Example response

{
  "id": 2,
  "projectKey": "test",
  "name": "test",
  "status": "open",
  "description": null,
  "documentation": "# test\n\n12345",
  "deleted": true,
  "allowMaskedJoins": true,
  "subscriptionType": "manual",
  "subscriptionPolicy": null,
  "equalization": null,
  "workspace": null,
  "snowflake": null,
  "type": null,
  "schema": null,
  "createdBy": 2,
  "updatedBy": 2,
  "createdAt": "2021-05-19T22:50:44.190Z",
  "updatedAt": "2021-07-29T18:30:04.066Z",
  "schemaEvolutionId": null,
  "subscribedAsUser": true,
  "subscriptionId": 5,
  "acknowledgeRequired": false,
  "subscriptionStatus": "owner",
  "requestedState": "owner",
  "approved": true,
  "subscriptionExpiration": null,
  "filterId": 2,
  "purposeCount": null,
  "purposes": [
    {
      "id": 8,
      "name": "Analyzing Onboarding and Job Satisfaction",
      "acknowledgement": null,
      "description": "Data can only be accessed for analyzing the effectiveness of current onboarding practices and trends in employee job satisfaction  reasons for data access must be approved by a compliance committee.",
      "addedByProfile": 2,
      "displayAcknowledgement": true,
      "deleted": false,
      "systemGenerated": false,
      "policyMetadata": null,
      "createdAt": "2021-07-07T19:56:06.360Z",
      "updatedAt": "2021-07-07T19:56:06.360Z",
      "createdBy": 2
    },
    {
      "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 t  address and mitigate such risks.",
      "description": null,
      "addedByProfile": 1,
      "displayAcknowledgement": true,
      "deleted": false,
      "systemGenerated": true,
      "policyMetadata": null,
      "createdAt": "2021-05-19T20:32:03.437Z",
      "updatedAt": "2021-07-28T14:17:22.690Z",
      "createdBy": 2
    }
  ],
  "stagedPurposes": [],
  "tags": []
}

Manage projects

Method	Path	Purpose
PUT	/project/{projectId}	Update the project with the given ID.
GET	/project/{projectId}/activity	Get all of the recent activity for a given project.
GET	/project/{projectId}/checkEqualizationState	Get current state of an equalized project.

Update project by ID

PUT /project/{projectId}

Update the project with the given ID.

Query parameters

Attribute	Description	Required
projectId	integer The project ID.	Yes
deleteDataSources	boolean If true, the data sources in the project will be deleted.	No

Payload parameters

Attribute	Description	Required
type	string The type of Immuta project, either user created project (user) or system generated project (schema).	No
name	string The project's new name.	No
description	string The project's new description.	No
documentation	string The project's new documentation.	No
status	string Accepted statuses are open or closed.	No
subscriptionType	string The type of subscription policy on the project. The type can be automatic (which allows anyone to subscribe), approval (which requires the subscriber to be manually approved), policy (which only allows users with specific groups or attributes to subscribe), or manual (which requires users to be manually added).	No
tags	array The project's new tags.	No
purposes	array The project's new purposes.	No
stagedPurposes	array The project's new purposes staged for approval.	No
deleted	boolean If true, the project will be deleted.	No
snowflake	array This enables a Snowflake workspace for the project and details the schema, hostname, and warehouse.	No
allowMaskedJoins	boolean If true, masked joins will be allowed.	No
subscriptionPolicy	array[object] A policy object for the Subscription Policy on the project. Details include type, exceptions, conditions, allowDiscovery, and automaticSubscription. If this is not set, it will be the default manual.	No
equalization	array Details the policy conditions of the equalization, including the configured (or recommended) user groups and attributes.	No
workspace	array Information on workspaces in the project.	No

Response parameters

Attribute	Description
id	integer Project ID.
projectKey	string Name of the project.
name	string Name of the project.
status	string Statuses are open or closed.
description	string Project description.
documentation	string Project documentation.
tags	array Project tags.
purposes	array Project purposes.
stagedPurposes	array Project purposes staged for approval.
deleted	boolean If true, the project will be deleted.
snowflake	array If a Snowflake workspace has been enabled for the project, this attribute will detail the schema, hostname, and warehouse.
allowMaskedJoins	boolean If true, masked joins will be allowed.
subscriptionPolicy	array[object] A policy object for the Subscription Policy on the project. Details include type, exceptions, conditions, allowDiscovery, and automaticSubscription.
subscriptionType	string The type of subscription policy on the project. The type can be automatic (which allows anyone to subscribe), approval (which requires the subscriber to be manually approved), policy (which only allows users with specific groups or attributes to subscribe), or manual (which requires users to be manually added).
equalization	array Details the policy conditions of the equalization, including the configured (or recommended) user groups and attributes.
workspace	array Information on workspaces in the project.
type	string The type of Immuta project, either user created project (user) or system generated project (schema).
createdAt	timestamp Date of the project creation.
updatedAt	timestamp Date of the most recent update.
workspaceWarnings	string This message describes issues with the created workspace.

Example request

This example request with the payload below will update the project with the project ID 2.

curl \
    --request PUT \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    --data @example-payload.json \
    https://demo.immuta.com/project/2

Example request payload

This example payload will update the project to be named Documentation Project.

{
  "name": "Documentation Project",
  "deleted": false
}

Example response

{
  "workspace": null,
  "createdBy": 2,
  "updatedBy": 2,
  "schemaEvolutionId": 1,
  "projectKey": "Medical Records",
  "name": "Documentation Project",
  "status": "open",
  "description": "This project contains all data sources under the schema, medical_records, from [e-mail]:1433/example.",
  "documentation": "This is an automatically generated project that collects data sources under the schema, medical_records, from [e-mail]:1433/example. When data sources in this schema are added to the system, they will automatically be added to this project.",
  "deleted": false,
  "allowMaskedJoins": false,
  "subscriptionType": "manual",
  "subscriptionPolicy": null,
  "equalization": null,
  "snowflake": null,
  "type": "Schema",
  "schema": "medical_records",
  "id": 2,
  "createdAt": "2021-08-24T15:44:29.477Z",
  "updatedAt": "2021-09-10T21:49:00.678Z",
  "purposeCount": 0,
  "tags": [],
  "projectPurposes": [],
  "stagedPurposes": [],
  "purposes": [],
  "workspaceWarnings": []
}

View project activity by project ID

GET /project/{projectId}/activity

Get all of the recent activity for a given project.

Query parameters

Attribute	Description	Required
projectId	integer The project ID.	Yes
offset	integer Used in combination with size to fetch pages.	No
size	integer Used to select the number of activities.	No

Response parameters

Attribute	Description
count	integer The total number of actions.
activities	array The id, modelType, modelId, notificationType, actionsBy, targetUser, targetGroup, additionalText, array, createdAt, updatedAt, and read for each action listed.
id	integer The activity ID.
modelType	string The Immuta feature the activity is attached to.
modelId	string The ID of the Immuta feature the activity is attached to.
notificationType	string The type of activity or notification, such as modelCreated, modelUserAdded, or projectUpdated.
actionBy	array The user data for the user who took the action.
targetUser	array The user data for the user who the action was directed towards.
targetGroup	array The group data for the group who the action was directed towards.
metadata	array Details about the action. For example, if the notificationType was modelCreated, the metadata attribute would include the project name.
createdAt	timestamp Date the action was taken.
updatedAt	timestamp Date of the most recent activity on the action.
read	boolean If true, the activity has been viewed.
unread	integer The number of unviewed activities on that project.

Example request

This example gets one activity for the project with the project ID 2.

curl \
    --request GET \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://demo.immuta.com/project/2/activity?size=1

Example response

{
  "count": 40,
  "activities": [
    {
      "modelType": "project",
      "modelId": "2",
      "createdAt": "2021-07-29T20:56:11.856Z",
      "notificationType": "projectUpdated",
      "metadata": {
        "fields": [
          "deleted",
          "purposes"
        ],
        "projectName": "test",
        "approvedPurposeCount": 0,
        "deniedPurposesCount": 0,
        "requestedPurposeCount": 0,
        "newPurposesAddedCount": 2
      },
      "read": false,
      "id": 191,
      "updatedAt": "2021-07-29T20:56:11.856Z",
      "actionBy": {
        "id": 2,
        "name": "John Doe",
        "email": "[e-mail]"
      },
      "targetUser": {
        "id": 2,
        "name": "John Doe",
        "email": "[e-mail]"
      }
    }
  ],
  "unread": 40,
  "next": "191_2021-07-29T20:56:11.856Z"
}

View the state of an equalized project

GET /project/{projectId}/checkEqualizationState

Get current state of an equalized project.

Query parameters

Attribute	Description	Required
projectId	integer The project ID.	Yes

Response parameters

Attribute	Description
equalizationState	string The state of the project's equalization. Options include: off, recommended, active, upgrade, or nonCompliantMembers.

Example request

This example gets the state of project equalization of the project with the project ID 2.

curl \
    --request GET \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://demo.immuta.com/project/2/checkEqualizationState

Example response

{
  "equalizationState": "recommended"
}

Manage project members

Method	Path	Purpose
GET	/project/{projectId}/members	Get all of the members for a given project.
POST	/project/{projectId}/checkEqualizedAuths	Check that all members meet the provided equalized entitlements.
POST	/project/{projectId}/members	Add a member to the project.
PUT	/project/{projectId}/members/{subscriptionId}	Update a member of the project.

View project members

GET /project/{projectId}/members

Get all of the members for a given project.

Query parameters

Attribute	Description	Required
projectId	integer The project ID.	Yes
offset	integer Used in combination with size to fetch pages.	No
size	integer The number of results to return per page.	No
sortField	string Sorts results by field. The default is name.	No
sortOrder	string Sorts results by order, which must be asc or desc. The default is asc.	No
searchText	string Searches text of member names.	No
approved	boolean Filters results based on whether or not members' subscription status has been approved.	No
checkDataSources	boolean When true, will check if users' meet the compliance requirements set on data sources within the project.	No
expandGroups	boolean	No

Response parameters

Attribute	Description
count	integer The number of members in the project.
members	array The profile, name, iamId, userId, email, type, approved, state, systemGenerated, lastExternalRefresh, subscriptionId, createdAt, updatedAt, approvals, currentUserCanApprove, and compliance for each member result.
profile	integer The user's profile ID.
name	string The user's name.
iamId	string The ID of the IAM, which is configured on the App Settings page.
userId	string The user's Immuta username.
email	string The user's email.
type	string The type of Immuta project, either user created project (user) or system generated project (schema).
approved	boolean When true, the members' subscription status has been approved.
state	string The user's relationship to the project. Options include owner, not_subscribed, pending, subscribed, and expert.
systemGenerated	boolean When true, the user is a system generated account.
lastExternalRefresh	timestamp The date of the last time this user's information was updated from an external IAM.
subscriptionId	integer The project member's subscription ID.
createdAt	timestamp The date that this user was created in Immuta.
updatedAt	timestamp The date of the most recent update of the user.
approvals	array Details on how this new member will fit into the project's approval process.
compliance	array Details about the compliance requirements of the project, including missingDataSources and invalidSubscriptions.

Example request

This request gets all of the members of the project with the project ID 2.

curl \
    --request GET \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://demo.immuta.com/project/2/members

Example response

{
  "count": 1,
  "members": [
    {
      "profile": 2,
      "name": "John Doe",
      "iamid": "bim",
      "userid": "[e-mail]",
      "email": "[e-mail]",
      "type": "user",
      "approved": true,
      "state": "owner",
      "systemGenerated": false,
      "lastExternalRefresh": "2021-07-30T17:49:55.050Z",
      "subscriptionId": 5,
      "createdAt": "2021-05-19T22:50:44.206Z",
      "updatedAt": "2021-07-19T20:47:53.069Z",
      "approvals": [],
      "currentUserCanApprove": false
    }
  ]
}

Check the members' equalized entitlements

POST /project/{projectId}/checkEqualizedAuths

Check that all members meet the provided equalized entitlements.

Query parameters

Attribute	Description	Required
projectId	integer The project ID.	Yes

Payload parameters

Attribute	Description	Required
conditionsObj	array Details containing operator, conditions, type, group, and field values.	Yes
operator	string	Yes
conditions	array Details containing type, group, and field.	Yes
type	string The type of Immuta project, either user created project (user) or system generated project (schema).	No
group	array Includes the group id, name, and iam.	No

Response parameters

Attribute	Description
validSet	boolean When true, users meet the specified entitlements.
usersMissingAuths	array Metadata about the user (name and subscription id) and the name of the group they're missing.

Request example

This request with the payload below will check if the requesting user is in the "View Masked Values" group.

curl \
    --request POST \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    --data @example-payload.json \
    https://demo.immuta.com/project/1/checkEqualizedAuths

Payload example

{
  "conditionsObj": {
    "operator": "and",
    "conditions": [
      {
        "type": "groups",
        "group": {
          "id": 1,
          "name": "View Masked Values"
        }
      }
    ]
  }
}

Response example

{
  "validSet": true,
  "usersMissingAuths": {}
}

Add a member to a project

POST /project/{projectId}/members

Add a member to the project.

Query parameters

Attribute	Description	Required
projectId	integer The project ID.	Yes

Payload parameters

Attribute	Description	Required
profileId	integer The new user's ID.	Yes
groupId	integer The group ID that the new user is a part of. This will add a whole group.	No
state	string The new user's connection to the project. Options include owner, not_subscribed, pending, subscribed, and expert.	No
expiration	timestamp The date when the member should no longer have access to the project.	No
approvals	array Details on how this new member will fit into the project's approval process.	No

Example request

This example request with the payload below will add a new member to the project with the project ID 1.

curl \
    --request POST \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    --data @example-payload.json \
    https:demo.immuta.com/project/1/members

Example request payload

{
  "profileId": 3,
  "state": "subscribed",
}

Example response

{
  "subscriptionId": 18,
  "state": "subscribed",
  "approved": true
}

Update a project member

PUT /project/{projectId}/members/{subscriptionId}

Update a member of the project.

Query parameters

Attribute	Description	Required
projectId	integer The project ID.	Yes
subscriptionId	integer The project member's subscription ID.	Yes

Payload parameters

Attribute	Description	Required
state	array[string] The user's role in the project. Options include owner, not_subscribed, pending, subscribed, and expert.	Yes
expiration	timestamp The date when the member should no longer have access to the project.	No

Response parameters

Attribute	Description
state	array[string] The user's role in the project. Options include owner, not_subscribed, pending, subscribed, and expert.
expiration	timestamp The date when the member should no longer have access to the project.

Request example

This example request with the payload below will update the user with the subscription ID 2 to be a subscriber of the project with the project ID 3.

curl \
    --request PUT \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    --data @example-payload.json \
    https://demo.immuta.com/project/3/members/2

Payload example

{
  "state": "subscribed"
}

Response example

{
  "state": "subscribed",
  "expiration": null
}

Manage project data sources

Method	Path	Purpose
GET	/project/{projectId}/dataSources	Get all of the data sources for a given project.
DELETE	/project/{projectId}/dataSources	Remove supplied data sources from the project.
POST	/project/{projectId}/dataSources	Add data sources to a project.
PUT	/project/{projectId}/dataSources/{dataSourceId}	Update the reason for adding a data source to a project.

View project data sources by project ID

GET project/{projectId}/dataSources

Get all of the data sources for a given project.

Query parameters

Attribute	Description	Required
projectId	integer The project ID.	Yes
offset	integer Used in combination with size to fetch pages.	No
searchText	string Searches text of the data source names.	No
size	integer The number of results to return per page.	No
sortField	string Used to sort results by field. Options include addedBy, addedOn, and dataSourceName. The default is dataSourceName.	No
sortOrder	string Sorts results by order, which must be asc or desc. The default is asc.	No
unsubscribed	boolean If true, filters by unsubscribed status (includes data sources with a pending subscription). If false, filters by subscribed status.	No
subscription	string Searches based on the subscription status of the user. Options include not_subscribed, owner, pending, or subscribed.	No

Response parameters

Attribute	Description
count	integer The total number of data sources in the project.
dataSources	array[object] An array of data source objects that includes addedBy, dataSourceName, policyHandlerType, addedOn, dataSourceId, addedByProfile, deleted, subscriptionType, subscriptionStatus, subscriptionPolicy, connectionString, blobHandlerType, and derivedThisProject values for each data source.
addedBy	string The user who added the data source to the project.
dataSourceName	string The name of the data source.
policyHandlerType	string
addedOn	timestamp The date the data source was added to the project.
dataSourceId	integer The data source ID.
addedByProfile	integer The profile ID of the user who added the data source to the project.
deleted	boolean If true, the data source has been deleted.
subscriptionType	string The type of subscription policy on the project. The type can be automatic (which allows anyone to subscribe), approval (which requires the subscriber to be manually approved), policy (which only allows users with specific groups or attributes to subscribe), or manual (which requires users to be manually added).
subscriptionStatus	string
subscriptionPolicy	array[object] A policy object for the Subscription Policy on the data source. Details include type, exceptions, conditions, allowDiscovery, and automaticSubscription.
connectionString	string The data source connection string.
blobHandlerType	string The data platform.
derivedInThisProject	boolean If true, this data source was created as a derived data source in this project.

Example request

This example gets the data source details for all of the data sources of the project with the project ID 2.

curl \
    --request GET \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://demo.immuta.com/project/2/dataSources

Example response

{
  "count": 3,
  "dataSources": [
    {
      "addedBy": "John Doe",
      "dataSourceName": "Fake Medical Claims 2017",
      "policyHandlerType": "Builder",
      "addedOn": "2021-06-25T19:11:03.230Z",
      "dataSourceId": 8,
      "addedByProfile": 2,
      "deleted": false,
      "subscriptionType": "policy",
      "subscriptionStatus": "owner",
      "subscriptionPolicy": {
        "type": "subscription",
        "exceptions": {
          "operator": "or",
          "conditions": [
            {
              "type": "groups",
              "group": {
                "name": "HR Department"
              }
            },
            {
              "type": "authorizations",
              "authorization": {
                "auth": "Manager",
                "value": "Receiving Surveys"
              }
            }
          ]
        },
        "shareResponsibility": false,
        "automaticSubscription": true
      },
      "connectionString": "[e-mail]:1433/example",
      "blobHandlerType": "Snowflake",
      "derivedInThisProject": false
    },
    {
      "addedBy": "John Doe",
      "dataSourceName": "Tpc Randomized",
      "policyHandlerType": "Builder",
      "addedOn": "2021-06-25T22:26:38.170Z",
      "dataSourceId": 6,
      "addedByProfile": 2,
      "deleted": false,
      "subscriptionType": "policy",
      "subscriptionStatus": "owner",
      "subscriptionPolicy": {
        "type": "subscription",
        "exceptions": {
          "operator": "and",
          "conditions": [
            {
              "type": "groups",
              "group": {
                "name": "HR"
              }
            }
          ]
        },
        "shareResponsibility": false,
        "automaticSubscription": true
      },
      "connectionString": "[e-mail]:1433/example",
      "blobHandlerType": "Azure Synapse Analytics",
      "derivedInThisProject": false
    },
    {
      "addedBy": "John Doe",
      "dataSourceName": "Tpc Web Sales",
      "policyHandlerType": "None",
      "addedOn": "2021-06-25T19:11:03.226Z",
      "dataSourceId": 7,
      "addedByProfile": 2,
      "deleted": false,
      "subscriptionType": "manual",
      "subscriptionStatus": "owner",
      "subscriptionPolicy": null,
      "connectionString": "[e-mail]:1433/example",
      "blobHandlerType": "Azure Synapse Analytics",
      "derivedInThisProject": false
    }
  ]
}

Remove data sources from a project

DELETE /project/{projectId}/dataSources

Remove supplied data sources from the project.

Query parameters

Attribute	Description	Required
projectId	integer The project ID.	Yes
ids	integer The IDs of the data sources to remove from the project.	Yes

Response parameters

Attribute	Description
success	array The id, blobHandlerType, and name values of the data sources that have been successfully removed.
inError	array The id, blobHandlerType, and name values of the data sources that have not been successfully removed.
id	integer The data source ID.
blobHandlerType	string The type of blob handler of the data source.
name	string The data source name.

Example request

This example request deletes the data source with the ID 8 from the project with the project ID 2.

curl \
    --request DELETE \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://demo.immuta.com/project/2/dataSources?ids=8

Example response

{
  "success": [
    {
      "id": 8,
      "name": "Fake Medical Claims 2017",
      "blobHandlerType": "Snowflake"
    }
  ],
  "inError": []
}

Add data sources to a project

POST /project/{projectId}/dataSources

Adds data sources to a project.

Query parameters

Attribute	Description	Required
projectId	integer The project ID.	Yes

Payload parameters

Attribute	Description	Required
dataSourceIds	integer The data source IDs for the data sources to add to the project.	Yes

Response parameters

Attribute	Description
success	array The id, blobHandlerType, and name values of the data sources that have been successfully added.
inError	array The id, blobHandlerType, and name values of the data sources that have not been successfully added.
id	integer The data source ID.
blobHandlerType	string The type of blob handler of the data source.
name	string The data source name.

Example request

This example request with the payload below will add the data source with the data source ID 1 to the project with the project ID 1.

curl \
    --request POST \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    --data @example-payload.json \
    https://demo.immuta.com/project/1/dataSources

Example request payload

This example payload will add the data source with the data source ID 2 to the project.

{
  "dataSourceIds": [
    2
  ]
}

Example response

{
  "success": [
    {
      "id": 2,
      "name": "Credit Payments Bank Deposits",
      "blobHandlerType": "Snowflake"
    }
  ],
  "inError": []
}

Update the reason for adding a data source

PUT /project/{projectId}/dataSources/{dataSourceId}

Updates the reason for adding a data source to a project.

Query parameters

Attribute	Description	Required
projectId	integer The project ID.	Yes
dataSourceId	integer The data source ID.	Yes

Request example

This example request with the payload below will update the reason that the data source with the data source ID 1 was added to the project with the project ID 1.

curl \
    --request PUT \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    --data @example-payload.json \
    https://demo.immuta.com/project/1/dataSources/1

Response example

None.

Use projects

Method	Path	Purpose
DELETE	/project/{projectId}/unsubscribe	Unsubscribe from a project.
POST	/project/current/{projectId}	Set the current project ID the current user is acting under.
POST	/project/current/null	Set current project to None.
POST	/project/{projectId}/members/{subscriptionId}/acknowledge	Acknowledge all the restrictions on this project.

Unsubscribe from a project

DELETE /project/{projectId}/unsubscribe

Unsubscribe from a project.

Query parameters

Attribute	Description	Required
projectId	string The project ID.	Yes

Request example

This example request unsubscribes the user from the project with the project ID 5.

curl \
    --request DELETE \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://demo.immuta.com/project/5/unsubscribe

Select the current project to act under

POST /project/current/{projectId}

Set the current project ID the current user is acting under.

Query parameters

Attribute	Description	Required
projectId	integer The project ID.	Yes

Request example

This example request sets the current project to act under as the project with the project ID 1.

curl \
    --request POST \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://demo.immuta.com/project/current/1

Set current project to None

POST /project/current/null

Set the project context to None.

Request example

curl \
    --request POST \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://demo.immuta.com/project/current/null

Acknowledge the project restrictions

POST /project/{projectId}/members/{subscriptionId}/acknowledge

Acknowledge all the restrictions on this project.

Query parameters

Attribute	Description	Required
projectId	integer The project ID.	Yes
subscriptionId	integer The project member's subscription ID.	Yes

Payload parameters

Attribute	Description	Required
text	string	Yes

Response parameters

Attribute	Description
acknowledgeRequired	boolean When true, the requesting user has not yet agreed to the project acknowledgement.
purposes	array Details of the purpose that has been acknowledged.

Request example

This example request acknowledges all of the purposes in the project with the project ID 1.

curl \
    --request POST \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    --data @example-payload.json \
    https://demo.immuta.com/project/1/members/1/acknowledge

Payload example

{}

Response example

{
  "acknowledgeRequired": false,
  "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."
    }
  ]
}

Delete project by ID

DELETE /project/{projectId}

Delete the project with the given ID.

Query parameters

Attribute	Description	Required
projectId	integer The project ID.	Yes

Response parameters

Attribute	Description
hardDelete	boolean If true, the project was permanently deleted.

Example request

This example request will delete the project with the project ID 4.

curl \
    --request DELETE \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://demo.immuta.com/project/4

Example response

{
  "hardDelete": true
}