> For the complete documentation index, see [llms.txt](https://documentation.immuta.com/latest/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.immuta.com/latest/developer-guides/api-intro/immuta-v1-api/manage-data-access/write-policies-api/payload-reference.md).

# Write Policies Payloads and Response Schema Reference Guide

## Manual write access grant payload

The parameters for manually granting write access to a data source without using a policy are outlined in the table below.

| Parameter                | Description                                                              | Required or optional | Default values | Accepted values                                                                                  |
| ------------------------ | ------------------------------------------------------------------------ | -------------------- | -------------- | ------------------------------------------------------------------------------------------------ |
| **profileId** `integer`  | The unique identifier of the user to whom you are granting write access. | Required             | -              | -                                                                                                |
| **state** `string`       | The user's role on the data source.                                      | Required             | -              | <ul><li><code>expert</code></li><li><code>owner</code></li><li><code>subscribed</code></li></ul> |
| **accessGrant** `string` | The type of access to grant the user.                                    | Required             | -              | <ul><li><code>READ</code></li><li><code>WRITE</code></li></ul>                                   |

## Global write policy payload

The parameters for creating a global write policy are outlined in the table below.

| Parameter                                           | Description                                                                                                                                                                                                                                                                                                                                                | Required or optional | Default values                                      | Accepted values                                                |
| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | --------------------------------------------------- | -------------------------------------------------------------- |
| **type** `string`                                   | The type of policy to create.                                                                                                                                                                                                                                                                                                                              | Required             | -                                                   | `subscription`                                                 |
| **name** `string`                                   | The name of the policy.                                                                                                                                                                                                                                                                                                                                    | Required             | -                                                   | -                                                              |
| **template** `boolean`                              | Specifies whether or not the policy should be available as a template.                                                                                                                                                                                                                                                                                     | Optional             | `false`                                             | <ul><li><code>true</code></li><li><code>false</code></li></ul> |
| [**actions** `array[]`](#actions-array)             | Specifies the policy access type and restriction level. See the [array description](#actions-array) for details.                                                                                                                                                                                                                                           | Required             | -                                                   | -                                                              |
| **staged** `boolean`                                | When `true`, the policy is not active or applied to any data sources.                                                                                                                                                                                                                                                                                      | Required             | -                                                   | <ul><li><code>true</code></li><li><code>false</code></li></ul> |
| [**circumstances** `object`](#circumstances-object) | This object specifies the conditions under which the policy applies to a data source. Set the value to `null` to enforce the policy only when it is applied by data owners. Do not include this object in your payload to apply the policy to all data sources. See the [object description](#circumstances-object) for additional parameters and details. | Optional             | By default, the policy applies to all data sources. | -                                                              |

### Actions array

The **actions** array specifies the policy access type and restriction level. Its child parameters are outlined in the table below.

<table><thead><tr><th>Parameter</th><th>Description</th><th>Required or optional</th><th width="149">Default values</th><th>Accepted values</th></tr></thead><tbody><tr><td><strong>type</strong> <code>string</code></td><td>The type of policy. For write access policies, the <strong>type</strong> is <code>subscription</code>.</td><td>Required</td><td>-</td><td><ul><li><code>data</code></li><li><code>subscription</code></li></ul></td></tr><tr><td><strong>accessGrant</strong> <code>string</code></td><td>The type of access the user is granted.</td><td>Required</td><td>-</td><td><code>WRITE</code></td></tr><tr><td><strong>description</strong> <code>string</code></td><td>The description of the policy.</td><td>Optional</td><td><code>null</code></td><td>-</td></tr><tr><td><strong>shareResponsibility</strong> <code>boolean</code></td><td>When <code>true</code>, users need to meet the conditions in this policy OR another share responsibility policy that applies to the data source. This parameter is not applicable to policies with <strong>actions.subscriptionType</strong> with a value of <code>manual</code>.</td><td>Optional</td><td><code>false</code></td><td><ul><li><code>true</code></li><li><code>false</code></li></ul></td></tr><tr><td><strong>subscriptionType</strong> <code>string</code></td><td>The restriction level of the subscription policy.</td><td>Required</td><td>-</td><td><ul><li><code>approval</code>: Users are granted access when approved by a specified user</li><li><code>automatic</code>: Anyone is granted access</li><li><code>manual</code>: Individually selected users are granted access</li><li><code>policy</code>: Users with specified entitlements are granted access</li></ul></td></tr></tbody></table>

### Circumstances object

The **circumstances** object specifies the conditions under which the policy applies to a data source. Its child parameters are outlined in the table below.

| Parameter                                 | Description                                                                                                                                                      | Required or optional                     | Default values | Accepted values                                                                                                                                                                         |
| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **operator** `string`                     | Specifies how to combine the conditions of the policy.                                                                                                           | Required                                 | -              | <ul><li><code>and</code></li><li><code>or</code></li></ul>                                                                                                                              |
| **type** `string`                         | The type of condition under which to apply the policy.                                                                                                           | Required                                 | -              | <ul><li><code>columnRegex</code></li><li><code>columnTags</code></li><li><code>domains</code></li><li><code>server</code></li><li><code>tags</code></li><li><code>time</code></li></ul> |
| **columnRegex** `object`                  | This object indicates that the policy should apply to data sources with column names that match the regular expression. Its child parameters are outlined below. | Required when **type** is `columnRegex`. | -              | -                                                                                                                                                                                       |
| columnRegex.**regex** `string`            | A regular expression that matches names of columns.                                                                                                              | Required when **type** is `columnRegex`. | -              | -                                                                                                                                                                                       |
| columnRegex.**caseInsensitive** `boolean` | When `true`, the regular expression is case insensitive.                                                                                                         | Optional                                 | `false`        | <ul><li><code>true</code></li><li><code>false</code></li></ul>                                                                                                                          |
| **columnTag** `object`                    | This object specifies the column tags required for the policy to apply to the data source. Child parameters are outlined below.                                  | Required if **type** is `columnTags`.    | -              | -                                                                                                                                                                                       |
| columnTag.**name** `string`               | The name of the tag.                                                                                                                                             | Required if **type** is `columnTags`     | -              | -                                                                                                                                                                                       |
| columnTag.**displayName** `string`        | The display name of the tag.                                                                                                                                     | Optional                                 | -              | -                                                                                                                                                                                       |
| columnTag.**hasLeafNodes** `boolean`      | When `true`, the tag applied has child tags.                                                                                                                     | Optional                                 | -              | -                                                                                                                                                                                       |
| **server** `string`                       | The server that contains the data sources the policy should be applied to.                                                                                       | Required when **type** is `server`.      | -              | -                                                                                                                                                                                       |
| **startDate** `string`                    | Applies the policy to data sources created on or after this **startDate** and before the **endDate** (if the **endDate** is specified).                          | Required when **type** is `time`.        | -              | -                                                                                                                                                                                       |
| **endDate** `string`                      | Applies the policy to data sources created on or before this **endDate** and after the **startDate**.                                                            | Optional                                 | `null`         | -                                                                                                                                                                                       |

## Global write policy response schema

| Parameter                                   | Description                                                                                                                                                                                                                                  |
| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **policyKey** `string`                      | The unique name of the policy.                                                                                                                                                                                                               |
| **createdBy** `integer`                     | The unique identifier of the user who created the policy.                                                                                                                                                                                    |
| **createdByName** `string`                  | The username of the user who created the policy.                                                                                                                                                                                             |
| **createdAt** `string`                      | The date the policy was created.                                                                                                                                                                                                             |
| **clonedFrom** `integer`                    | The unique identifier of the policy that the new policy was cloned from.                                                                                                                                                                     |
| **systemGenerated** `boolean`               | Indicates whether or not the policy is system-generated.                                                                                                                                                                                     |
| **deleted** `boolean`                       | When `true`, the policy has been deleted.                                                                                                                                                                                                    |
| **id** `integer`                            | The unique identifier of the policy.                                                                                                                                                                                                         |
| **type** `string`                           | The type of policy. For write access policies, the **type** is `subscription`.                                                                                                                                                               |
| **name** `string`                           | The name of the policy.                                                                                                                                                                                                                      |
| **template** `boolean`                      | Specifies whether or not the policy is available as a template.                                                                                                                                                                              |
| **certification** `object`                  | The certification object only applies to data policies, not write access policies.                                                                                                                                                           |
| **actions** `array[]`                       | Specifies the policy access type and restriction level.                                                                                                                                                                                      |
| actions.**type** `string`                   | The type of policy. For write access policies, the **type** is `subscription`.                                                                                                                                                               |
| actions.**accessGrant** `string`            | The type of access the user is granted. For write access policies, **actions.accessGrant** is `WRITE`.                                                                                                                                       |
| actions.**description** `string`            | The description of the policy.                                                                                                                                                                                                               |
| actions.**allowDiscovery** `boolean`        | When `true`, users can still see that the data source exists in Immuta, even if they do not have the attributes and groups specified by the policy.                                                                                          |
| actions.**subscriptionType** `string`       | The restriction level of the subscription policy.                                                                                                                                                                                            |
| actions.**shareResponsibility** `boolean`   | When `true`, users need to meet the conditions in this policy OR another share responsibility policy that applies to the data source. This parameter is not applicable to policies with `actions.subscriptionType` with a value of `manual`. |
| actions.**automaticSubscription** `boolean` | When `true`, users will automatically be subscribed to the data source when they meet the conditions specified in the policy. This parameter is not applicable to policies with **actions.subscriptionType** with a value of `manual`.       |
| **staged** `boolean`                        | When `true`, the policy is staged and not active on any data sources.                                                                                                                                                                        |
| **circumstances** `array[]`                 | Specifies the conditions under which the policy applies to a data source. See the [object description](#circumstances-object) for child parameters.                                                                                          |

## Manual write access grant response schema

| Parameter                            | Description                                                                                                                             |
| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| **isSubscriptionOverride** `boolean` | When `true`, the user was manually granted write access by a data owner instead of being granted access by a policy on the data source. |
| **id** `integer`                     | The unique identifier of the user's subscription to the data source.                                                                    |
| **modelId** `integer`                | The unique identifier of the data source.                                                                                               |
| **modelType** `string`               | The type of model the subscription policy applies to. For write policies, **modelType** is `dataSource`.                                |
| **state** `string`                   | The type of role the user has, such as `expert`, `owner`, or `subscribed`.                                                              |
| **admin** `integer`                  | The unique identifier of the user who granted write access to the data source subscriber.                                               |
| **denialReasoning** `string`         | If the user was denied access to the data source, this field contains the reason entered by the owner who denied access.                |
| **profile** `integer`                | The unique identifier of the user who has been granted write access.                                                                    |
| **group** `string`                   | The name of the group that has been granted write access, when applicable.                                                              |
| **policy** `boolean`                 | When `true`, the access has been granted by a policy on the data source.                                                                |
| **expiration** `string`              | The date the user's access expires.                                                                                                     |
| **acknowledgeRequired** `boolean`    | When `true`, the users must manually request access to the data source.                                                                 |
| **createdAt** `string`               | The date and time the user's access to the data source was granted.                                                                     |
| **updatedAt** `string`               | The date and time the user's access to the data source was updated.                                                                     |
| **accessGrant** `string`             | The type of access the user has to the data source: `READ` or `WRITE`.                                                                  |
| **approved** `boolean`               | When `true`, the user's access to the data source has been approved.                                                                    |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://documentation.immuta.com/latest/developer-guides/api-intro/immuta-v1-api/manage-data-access/write-policies-api/payload-reference.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.