# Manage Projects
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](#create-a-project).
2. [Search for Immuta projects](#search-projects).
3. [Manage your Immuta projects](#manage-projects).
4. [Manage project members](#manage-project-members).
5. [Manage project data sources](#manage-project-data-sources).
6. [Use projects](#use-projects).
7. [Delete projects](#delete-projects).
## Create a project
`POST` `/project`
Create the project.
**Required Immuta permission**: `CREATE_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`. *Support for Snowflake project workspaces has been deprecated.* | 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.
```bash
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**.
```json
{
"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
```json
{
"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](#search-all-projects). |
| GET | `/project/{projectId}` | [Get the project with the given ID](#search-for-projects-by-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.
```bash
curl \
--request GET \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://demo.immuta.com/project
```
#### Response example
```json
{
"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
`GET` `/project/{projectId}`
Get the project with the given ID.
**Requirement**: `PROJECT_MANAGEMENT` permission, `GOVERNANCE` permission, or you must be a member of the project
#### 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`.
```bash
curl \
--request GET \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://demo.immuta.com/project/2
```
#### Example response
```json
{
"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,
"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,
"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](#update-project-by-id). |
| GET | `/project/{projectId}/activity` | [Get all of the recent activity for a given project](#view-project-activity-by-project-id). |
| GET | `/project/{projectId}/checkEqualizationState` | [Get current state of an equalized project](#view-the-state-of-an-equalized-project). |
### Update project by ID
`PUT` `/project/{projectId}`
Update the project with the given ID.
**Requirement**: `PROJECT_MANAGEMENT` permission, `GOVERNANCE` permission, or you must be the owner of the project
#### 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`.
```bash
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**.
```json
{
"name": "Documentation Project",
"deleted": false
}
```
#### Example response
```json
{
"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
`GET` `/project/{projectId}/activity`
Get all of the recent activity for a given project.
**Requirement**: `PROJECT_MANAGEMENT` permission, `GOVERNANCE` permission, or you must be a member of the 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`.
```bash
curl \
--request GET \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://demo.immuta.com/project/2/activity?size=1
```
#### Example response
```json
{
"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
`GET` `/project/{projectId}/checkEqualizationState`
Get current state of an equalized project.
**Requirement**: `PROJECT_MANAGEMENT` permission, `GOVERNANCE` permission, or you must be a member of the 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`.
```bash
curl \
--request GET \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://demo.immuta.com/project/2/checkEqualizationState
```
#### Example response
```json
{
"equalizationState": "recommended"
}
```
## Manage project members
| Method | Path | Purpose |
| ------ | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| GET | `/project/{projectId}/members` | [Get all of the members for a given project](#view-project-members). |
| POST | `/project/{projectId}/checkEqualizedAuths` | [Check that all members meet the provided equalized entitlements](#check-the-members-equalized-entitlements). |
| POST | `/project/{projectId}/members` | [Add a member to the project](#add-a-member-to-a-project). |
| PUT | `/project/{projectId}/members/{subscriptionId}` | [Update a member of the project](#update-a-project-member). |
### View project members
`GET` `/project/{projectId}/members`
Get all of the members for a given project.
**Requirement**: `PROJECT_MANAGEMENT` permission, `GOVERNANCE` permission, or you must be a member of the 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`.
```bash
curl \
--request GET \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://demo.immuta.com/project/2/members
```
#### Example response
```json
{
"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
`POST` `/project/{projectId}/checkEqualizedAuths`
Check that all members meet the provided equalized entitlements.
**Requirement**: `PROJECT_MANAGEMENT` permission, `GOVERNANCE` permission, or you must be a member of the project
#### 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.
```bash
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**
```json
{
"conditionsObj": {
"operator": "and",
"conditions": [
{
"type": "groups",
"group": {
"id": 1,
"name": "View Masked Values"
}
}
]
}
}
```
#### Response example
```json
{
"validSet": true,
"usersMissingAuths": {}
}
```
### Add a member to a project
`POST` `/project/{projectId}/members`
Add a member to the project.
**Requirement**: `GOVERNANCE` permission or you must be the owner of 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`.
```bash
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**
```json
{
"profileId": 3,
"state": "subscribed",
}
```
#### Example response
```json
{
"subscriptionId": 18,
"state": "subscribed",
"approved": true
}
```
### Update a project member
`PUT` `/project/{projectId}/members/{subscriptionId}`
Update a member of the project.
**Requirement**: `GOVERNANCE` permission or you must be the owner 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`.
```bash
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**
```json
{
"state": "subscribed"
}
```
#### Response example
```json
{
"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](#view-project-data-sources-by-project-id). |
| DELETE | `/project/{projectId}/dataSources` | [Remove supplied data sources from the project](#remove-data-sources-from-a-project). |
| POST | `/project/{projectId}/dataSources` | [Add data sources to a project](#add-data-sources-to-a-project). |
| PUT | `/project/{projectId}/dataSources/{dataSourceId}` | [Update the reason for adding a data source to a project](#update-the-reason-for-adding-a-data-source). |
### View project data sources by project ID
`GET` `project/{projectId}/dataSources`
Get all of the data sources for a given project.
**Requirement**: `PROJECT_MANAGEMENT` permission, `GOVERNANCE` permission, or you must be a member of the 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`, and `blobHandlerType` 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. |
#### Example request
This example gets the data source details for all of the data sources of the project with the project ID `2`.
```bash
curl \
--request GET \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://demo.immuta.com/project/2/dataSources
```
#### Example response
```json
{
"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"
},
{
"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"
},
{
"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"
}
]
}
```
### Remove data sources from a project
`DELETE` `/project/{projectId}/dataSources`
Remove data sources from the project.
**Requirement**: `PROJECT_MANAGEMENT` permission, `GOVERNANCE` permission, or you must be the owner of 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`.
```bash
curl \
--request DELETE \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://demo.immuta.com/project/2/dataSources?ids=8
```
#### Example response
```json
{
"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.
**Requirement**: `PROJECT_MANAGEMENT` permission, `GOVERNANCE` permission, or you must be the owner of the 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`.
```bash
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.
```json
{
"dataSourceIds": [
2
]
}
```
#### Example response
```json
{
"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.
**Requirement**: `PROJECT_MANAGEMENT` permission, `GOVERNANCE` permission, or you must be the owner of the 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`.
```bash
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](#unsubscribe-from-a-project). |
| POST | `/project/current/{projectId}` | [Set the current project ID the current user is acting under](#select-the-current-project-to-act-under). |
| POST | `/project/{projectId}/members/{subscriptionId}/acknowledge` | [Acknowledge all the restrictions on this project](#acknowledge-the-project-restrictions). |
### Unsubscribe from a project
`DELETE` `/project/{projectId}/unsubscribe`
Unsubscribe from a project.
**Requirement**: You must be a member of the 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`.
```bash
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.
**Requirement**: You must be a member of the project
#### Query parameters
| Attribute | Description | Required |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| projectId | `integer` The project ID. To set the [project context](https://documentation.immuta.com/saas/govern/secure-your-data/projects-and-purpose-based-access-control/purpose-index/reference-guides/projects#project-contexts) to "None", use `null` | **Yes** |
#### Request example
This example request sets the current project to act under as the project with the project ID `1`.
```bash
curl \
--request POST \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://demo.immuta.com/project/current/1
```
### Acknowledge the project restrictions
`POST` `/project/{projectId}/members/{subscriptionId}/acknowledge`
Acknowledge all the restrictions on this project.
**Requirement**: You must be a member of the project to acknowledge for yourself or have the `GOVERNANCE` or `PROJECT_MANAGEMENT` permission to acknowledge on behalf of another user
#### 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`.
```bash
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**
```json
{}
```
#### Response example
```json
{
"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.
**Requirement**: You must be the owner of the project
#### 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`.
```bash
curl \
--request DELETE \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://demo.immuta.com/project/4
```
### Example response
```json
{
"hardDelete": true
}
```