# Create a Purpose

## <mark style="color:green;">POST</mark> `/api/v2/purpose`

**Required Immuta permission**: `GOVERNANCE`

{% tabs %}
{% tab title="Basic purpose" %}

```yaml
name: A basic purpose
```

{% endtab %}

{% tab title="Purpose with subpurposes" %}

```yaml
name: Purpose Hierarchy
acknowledgement: The root acknowledgement
subpurposes:
  - name: Purpose Hierarchy.Child 1
    acknowledgement: Override the root acknowledgement
    subpurposes:
      - name: Purpose Hierarchy.Child 1.Grandchild 1
      - name: Purpose Hierarchy.Child 1.Grandchild 2
  - name: Purpose Hierarchy.Child 2
    subpurposes:
      - name: Purpose Hierarchy.Child 2.Grandchild 1
      - name: Purpose Hierarchy.Child 2.Grandchild 2
```

{% endtab %}
{% endtabs %}

## Path parameters

| Parameter                           | Description                                                                                                                    | Default value |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ------------- |
| **dryRun** `boolean`                | If `true`, no updates will actually be made.                                                                                   | `false`       |
| **reAcknowledgeRequired** `boolean` | If `true`, will require all users of any projects using this purpose to re-acknowledge any updated acknowledgement statements. | `false`       |

## Body parameters

The body of the request contains the purpose details. The following attributes are available:

| Attribute                                     | Description                                                                                                                              | Required or optional |
| --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
| **name** `string`                             | The name of the purpose.                                                                                                                 | Required             |
| **description** `string`                      | A short description for the purpose.                                                                                                     | Optional             |
| **acknowledgement** `string`                  | The acknowledgement that users must agree to when joining a project with this purpose. If not provided, the system default will be used. | Optional             |
| [**subpurposes**](#subpurposes-array) `array` | The subpurposes of the purpose.                                                                                                          | Optional             |

### `subpurposes` array

The `subpurposes` array allows you to define a hierarchy of purposes, where each subpurpose can have its own acknowledgement and can be used to further categorize data usage. Each subpurpose can itself have a `subpurposes` array, allowing for nested hierarchies.

| Attribute                    | Description                                                                                                                                 | Required or optional |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
| **name** `string`            | The name of the subpurpose.                                                                                                                 | Required             |
| **acknowledgement** `string` | The acknowledgement that users must agree to when joining a project with this subpurpose. If not provided, the system default will be used. | Optional             |
| **subpurposes** `array`      | Nested subpurposes.                                                                                                                         | Optional             |