# Manage Subscription Requests

This page describes the `subscription` endpoint, which allows you to view and manage subscription requests on data sources and projects.

{% hint style="info" %}
Additional fields may be included in some responses you receive; however, these attributes are for internal purposes and are therefore undocumented.
{% endhint %}

## Subscription workflow

1. [Get pending subscription requests](#get-pending-subscription-requests).
2. [Approve subscription requests](#approve-subscription-requests).
3. [Deny subscription requests](#deny-subscription-requests).

## Get pending subscription requests

<table><thead><tr><th>Method</th><th width="495">Path</th><th>Purpose</th></tr></thead><tbody><tr><td>GET</td><td><a href="#get-pending-subscription-requests-you-can-approve"><mark style="color:blue;"><code>/subscription/getPendingRequestsForUser</code></mark></a></td><td>Get pending subscription requests the calling user can approve.</td></tr><tr><td>GET</td><td><a href="#get-pending-subscription-requests-for-a-specified-model"><mark style="color:blue;"><code>/subscription/requestInfo/{modelType}/{modelId}</code></mark></a></td><td>Get pending request information for specified model and requesting user (or specified entity).</td></tr></tbody></table>

### Get pending subscription requests you can approve

<mark style="color:green;">`GET`</mark> `/subscription/getPendingRequestsForUser`

Get pending subscription requests the calling user can approve.

#### Query parameters

| Attribute     | Description                                                                      | Required |
| ------------- | -------------------------------------------------------------------------------- | -------- |
| groupByEntity | `boolean` If `true`, group request results by user/group.                        | No       |
| profileId     | `integer` Match against profile ID.                                              | No       |
| groupId       | `integer` Match against group ID.                                                | No       |
| name          | `string` A partial name to match against user or group names.                    | No       |
| email         | `string` A partial email address to match against user or group email addresses. | No       |
| modelName     | `string` A partial name to match against model names.                            | No       |
| modelTypes    | `array[string]` Model types to include.                                          | No       |
| size          | `integer` The max number of matches to return. **Default 15**.                   | No       |
| sortField     | `string` The field to sort results on. Defaults to name.                         | No       |
| sortOrder     | `string` The order that the results will be sorted in. **Default `asc`**.        | No       |
| offset        | `integer` Offset to start returning values.                                      | No       |

#### Response parameters

| Attribute | Description                                                   |
| --------- | ------------------------------------------------------------- |
| hits      | `array` Metadata details regarding the subscription requests. |
| count     | `integer` The number of subscription requests.                |

#### Request example

The following request gets pending subscription requests the calling user can approve.

```bash
curl \
    --request GET \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://your-immuta-url.com/subscription/getPendingRequestsForUser?size=15&sortOrder=asc
```

#### Response example

```json
{
  "hits": [
    {
      "id": 652,
      "createdAt": "2021-10-14T14:25:16.509Z",
      "metadata": {},
      "model": {
        "type": "datasource",
        "id": 544,
        "name": "Gp Toolkit  Gp Is Append Only"
      },
      "entity": {
        "type": "profile",
        "id": 2,
        "name": "First Last",
        "email": "first.last@immuta.com"
      },
      "approvals": [
        {
          "requiredPermission": "OWNER",
          "state": "pending",
          "approverId": null,
          "ownerModelId": null,
          "approver": null,
          "ownerModelName": null
        }
      ]
    }
  ],
  "count": 1
}
```

### Get pending subscription requests for a specified model

<mark style="color:green;">`GET`</mark> `/subscription/requestInfo/{modelType}/{modelId}`

Get pending request information for specified model and requesting user (or specified entity).

#### Query parameters

| Attribute | Description                                                                                  | Required |
| --------- | -------------------------------------------------------------------------------------------- | -------- |
| modelType | `string` The model that a pending request is out for. Options are `datasource` or `project`. | **Yes**  |
| modelId   | `integer` The data source or project ID.                                                     | **Yes**  |
| profileId | `integer` A user ID if you want to get pending requests for another user.                    | No       |
| groupId   | `integer` A group ID if you want to get pending requests for a whole group.                  | No       |

#### Response parameters

| Attribute | Description                                                                                                                                                                                 |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| records   | `array` Details about each of the pending subscription requests, including `subscriptionId`, `requiredPermission`, `state`, `approverId`, `ownerModelId`, `approver`, and `ownerModelName`. |

#### Request example

The following request gets pending subscription requests for the data source with the ID `6` for the current user.

```bash
curl -X 'GET' \
  'https://demo.immuta.com/subscription/requestInfo/datasource/6' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer 2533855fddf14b688df4483a30e7d57f'
```

#### Response example

```json
{
  "records": [
    {
      "subscriptionId": 36,
      "requiredPermission": "OWNER",
      "state": "pending",
      "approverId": null,
      "ownerModelId": null,
      "approver": null,
      "ownerModelName": null
    }
  ]
}
```

## Approve subscription requests

<table><thead><tr><th>Method</th><th width="337">Path</th><th>Purpose</th></tr></thead><tbody><tr><td>POST</td><td><a href="#approve-specified-subscription-requests"><mark style="color:blue;"><code>/subscription/approve</code></mark></a></td><td>Approve specified subscription requests.</td></tr><tr><td>POST</td><td><a href="#approve-bulk-subscription-requests"><mark style="color:blue;"><code>/subscription/approve/bulk</code></mark></a></td><td>Bulk approve subscription requests.</td></tr></tbody></table>

### Approve specified subscription requests

<mark style="color:green;">`POST`</mark> `/subscription/approve`

Approve specified subscription requests.

**Requirement**: `AUDIT` permission, `GOVERNANCE` permission, `USER_ADMIN` permission, or you must be the owner of the data source, depending on the subscription policy

#### Payload parameters

| Attribute  | Description                                              | Required |
| ---------- | -------------------------------------------------------- | -------- |
| id         | `integer` The subscription ID of the request to approve. | **Yes**  |
| expiration | `date` The date to expire this user's access.            | No       |

#### Response parameters

| Attribute | Description                                                                                                         |
| --------- | ------------------------------------------------------------------------------------------------------------------- |
| id        | `integer` If the request fails, the response includes the ID of the subscription request.                           |
| model     | `array[object]` If the request fails, the response includes details about the data source or project.               |
| entity    | `array[object]` If the request fails, the response includes details about the user making the subscription request. |

#### Request example

The following request approves the subscription request.

```bash
curl \
    --request POST \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    --data @example-payload.json \
    https://your-immuta-url.com/subscription/approve
```

#### Payload example

```json
{
  "requests": [
    {
      "id": 652,
      "expiration": "2021-10-14"
    }
  ]
}
```

#### Response example

```json
{
  "failures": []
}
```

### Approve bulk subscription requests

<mark style="color:green;">`POST`</mark> `/subscription/approve/bulk`

Bulk approve subscription requests.

**Requirement**: `AUDIT` permission, `GOVERNANCE` permission, `USER_ADMIN` permission, or you must be the owner of the data source, depending on the subscription policy

#### Payload parameters

| Attribute  | Description                                                                                                                                                                                                                                       | Required |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| requestIds | `integer` A list of the subscription request IDs to be approved. If `requestIds` is provided, jobs will only be created for the IDs listed. Otherwise, the `id` and `type` values will be used to find and create jobs for all approval requests. | **Yes**  |
| id         | `integer` The ID for the `type`. If `requestIds` is provided, jobs will only be created for the IDs listed. Otherwise, the `id` and `type` values will be used to find and create jobs for all approval requests.                                 | **Yes**  |
| type       | `string` The type of ID: `profile`. If `requestIds` is provided, jobs will only be created for the IDs listed. Otherwise, the `id` and `type` values will be used to find and create jobs for all approval requests.                              | **Yes**  |

#### Response parameters

| Attribute | Description                                                                            |
| --------- | -------------------------------------------------------------------------------------- |
| success   | `boolean` If `true`, all of the subscription requests have been successfully approved. |

#### Request example

The following request approves all of the subscription requests.

```bash
curl \
    --request POST \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    --data @example-payload.json \
    https://your-immuta-url.com/subscription/approve/bulk
```

#### Payload example

```json
{
  "id": 4,
  "type": "profile"
}
```

#### Response example

```json
{
  "success": true
}
```

## Deny subscription requests

<table><thead><tr><th>Method</th><th width="267">Path</th><th>Purpose</th></tr></thead><tbody><tr><td>POST</td><td><a href="#deny-specified-subscription-requests"><mark style="color:blue;"><code>/subscription/deny</code></mark></a></td><td>Deny specified subscription requests.</td></tr><tr><td>POST</td><td><a href="#deny-bulk-subscription-requests"><mark style="color:blue;"><code>/subscription/deny/bulk</code></mark></a></td><td>Bulk deny subscription requests.</td></tr></tbody></table>

### Deny specified subscription requests

<mark style="color:green;">`POST`</mark> `/subscription/deny`

Deny specified subscription requests.

**Requirement**: `AUDIT` permission, `GOVERNANCE` permission, `USER_ADMIN` permission, or you must be the owner of the data source, depending on the subscription policy

#### Payload parameters

| Attribute       | Description                                                                  | Required |
| --------------- | ---------------------------------------------------------------------------- | -------- |
| id              | `integer` The subscription ID of the request to deny.                        | **Yes**  |
| denialReasoning | `string` The reason the user is denied access to the data source or project. | **Yes**  |

#### Response parameters

| Attribute | Description                                                                                                         |
| --------- | ------------------------------------------------------------------------------------------------------------------- |
| id        | `integer` If the request fails, the response includes the ID of the subscription request.                           |
| model     | `array[object]` If the request fails, the response includes details about the data source or project.               |
| entity    | `array[object]` If the request fails, the response includes details about the user making the subscription request. |

#### Request example

The following request denies the subscription request.

```bash
curl \
    --request POST \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    --data @example-payload.json \
    https://your-immuta-url.com/subscription/deny
```

#### Payload example

```json
{
  "requests": [
    {
      "id": 652,
      "denialReasoning": "testdenial"
    }
  ]
}
```

#### Response example

```json
{
  "failures": []
}
```

### Deny bulk subscription requests

<mark style="color:green;">`POST`</mark> `/subscription/deny/bulk`

Bulk deny subscription requests.

**Requirement**: `AUDIT` permission, `GOVERNANCE` permission, `USER_ADMIN` permission, or you must be the owner of the data source, depending on the subscription policy

#### Payload parameters

| Attribute       | Description                                                                                                                                                                                                                                     | Required |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| requestIds      | `integer` A list of the subscription request IDs to be approved. If `requestIds` is provided, jobs will only be created for the IDs listed. Otherwise, the `id` and `type` values will be used to find and create jobs for all denial requests. | **Yes**  |
| id              | `integer` The ID for the `type` you select. If `requestIds` is provided, jobs will only be created for the IDs listed. Otherwise, the `id` and `type` values will be used to find and create jobs for all denial requests.                      | **Yes**  |
| type            | `string` The type of ID: `profile`. If `requestIds` is provided, jobs will only be created for the IDs listed. Otherwise, the `id` and `type` values will be used to find and create jobs for all denial requests.                              | **Yes**  |
| denialReasoning | `string` The reason that you are denying the subscription requests.                                                                                                                                                                             | **Yes**  |

#### Response parameters

| Attribute | Description                                                                          |
| --------- | ------------------------------------------------------------------------------------ |
| success   | `boolean` If `true`, all of the subscription requests have been successfully denied. |

#### Request example

The following request with the payload below denies the subscription requests with the IDs `40` and `41`.

```bash
curl \
    --request POST \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    --data @example-payload.json \
    https://your-immuta-url.com/subscription/deny/bulk
```

#### Payload example

```json
{
  "requestIds": [
    40,
    41
  ],
  "denialReasoning": "The users do not have the right attributes."
}
```

#### Response example

```json
{
  "success": true
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://documentation.immuta.com/saas/developer-guides/api-intro/immuta-v1-api/manage-data-access/subscription.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.