Skip to content

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

Endpoint

Method Path Purpose
POST /project Create the project.

Query Parameters

None.

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 native 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
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 native 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

Endpoint

Method Path Purpose
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 native 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 immuta@example.database.sample.net: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 immuta@example.database.sample.net: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

Endpoint

Method Path Purpose
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 native 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

Endpoint

Method Path Purpose
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 native 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 native 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 immuta@example.database.sample.net:1433/example.",
  "documentation": "This is an automatically generated project that collects data sources under the schema, medical_records, from immuta@example.database.sample.net: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

Endpoint

Method Path Purpose
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": "john.doe@immuta.com"
      },
      "targetUser": {
        "id": 2,
        "name": "John Doe",
        "email": "john.doe@immuta.com"
      }
    }
  ],
  "unread": 40,
  "next": "191_2021-07-29T20:56:11.856Z"
}

View the state of an equalized project

Endpoint

Method Path Purpose
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

Endpoint

Method Path Purpose
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": "john.doe@immuta.com",
      "email": "john.doe@immuta.com",
      "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

Endpoint

Method Path Purpose
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

Endpoint

Method Path Purpose
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

Response Parameters

None.

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

Endpoint

Method Path Purpose
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

Endpoint

Method Path Purpose
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": "immuta@example.database.sample.net: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": "immuta@example.database.sample.net: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": "immuta@example.database.sample.net:1433/example",
      "blobHandlerType": "Azure Synapse Analytics",
      "derivedInThisProject": false
    }
  ]
}

Remove data sources from a project

Endpoint

Method Path Purpose
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

Endpoint

Method Path Purpose
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

Endpoint

Method Path Purpose
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

Payload Parameters

None.

Response Parameters

None.

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/{projectId}/members/{subscriptionId}/acknowledge Acknowledge all the restrictions on this project.

Unsubscribe from a project

Endpoint

Method Path Purpose
DELETE /project/{projectId}/unsubscribe Unsubscribe from a project.

Query Parameters

Attribute Description Required
projectId string The project ID. Yes

Response Parameters

None.

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

Endpoint

Method Path Purpose
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

Response Parameters

None.

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

Acknowledge the project restrictions

Endpoint

Method Path Purpose
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 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

Endpoint

Method Path Purpose
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
}