> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gominerva.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Profile Groups API

> Create and manage workspace-scoped profile groups for dynamic profile segmentation.

Use the Profile Groups API to create and maintain the workspace-scoped segment
labels that can be assigned to CLM profiles. Profile groups support dynamic
customer segmentation, such as risk populations, product lines, or onboarding
cohorts, without creating new workspaces.

For product concepts, UI workflows, and example segmentation models, see the
[Profile Groups Guide](/profile-groups-guide).

<Info>
  Profile Groups API calls use application API key authentication. The API key
  determines the tenant and workspace scope for every request; callers do not
  pass tenant or workspace IDs in the route.
</Info>

## Endpoints

```http theme={null}
GET    https://api.gominerva.com/tenant-config/v1/profile-groups
POST   https://api.gominerva.com/tenant-config/v1/profile-groups
GET    https://api.gominerva.com/tenant-config/v1/profile-groups/{profileGroupId}
PATCH  https://api.gominerva.com/tenant-config/v1/profile-groups/{profileGroupId}
DELETE https://api.gominerva.com/tenant-config/v1/profile-groups/{profileGroupId}
```

Authenticate with the same API key header used by the other Minerva API
endpoints:

```bash theme={null}
x-api-key: YOUR_API_KEY
```

Application API keys are managed from <strong>Administration</strong> >

<strong>Developers</strong> in the Minerva dashboard.

## Object Model

| Field                       | Description                                                                 |
| --------------------------- | --------------------------------------------------------------------------- |
| `id`                        | Minerva-generated profile group ID. Use this value in profile assignments.  |
| `key`                       | Read-only normalized key generated by Minerva from the initial group label. |
| `name`                      | Customer-facing group label shown in the dashboard.                         |
| `description`               | Optional description of the population represented by the group.            |
| `priority`                  | Non-negative priority. Higher values win when a profile has many groups.    |
| `archived`                  | Whether the group is archived. Archived groups are hidden by default.       |
| `monitoringFeedFrequencies` | Optional feed cadence overrides for profiles assigned to the group.         |

<Note>
  Do not supply <code>id</code> or <code>key</code> when creating a profile
  group. Minerva generates both values. Store and reuse the returned
  <code>id</code> when assigning profiles to groups.
</Note>

## Monitoring Frequencies

`monitoringFeedFrequencies` can include any of the feed keys below. Omitted
feeds inherit the workspace-level monitoring frequency.

| Feed        | Allowed values                                                                           |
| ----------- | ---------------------------------------------------------------------------------------- |
| `Sanctions` | `deltas`, `daily`, `weekly`, `monthly`, `quarterly`, `semiannually`, `annually`, `never` |
| `PEP`       | `daily`, `weekly`, `monthly`, `quarterly`, `semiannually`, `annually`, `never`           |
| `News`      | `daily`, `weekly`, `monthly`, `quarterly`, `semiannually`, `annually`, `never`           |

`deltas` is only supported for Sanctions monitoring.

## Create Risk Segments

This example creates high, medium, and low risk groups. Higher-risk groups use
more frequent monitoring, while lower-risk groups use less frequent monitoring.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.gominerva.com/tenant-config/v1/profile-groups" \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    --data '{
      "name": "High Risk",
      "description": "Enhanced diligence customers requiring the most frequent monitoring.",
      "priority": 100,
      "monitoringFeedFrequencies": {
        "Sanctions": "deltas",
        "PEP": "weekly",
        "News": "weekly"
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://api.gominerva.com/tenant-config/v1/profile-groups",
    {
      method: "POST",
      headers: {
        "x-api-key": process.env.MINERVA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: "High Risk",
        description:
          "Enhanced diligence customers requiring the most frequent monitoring.",
        priority: 100,
        monitoringFeedFrequencies: {
          Sanctions: "deltas",
          PEP: "weekly",
          News: "weekly",
        },
      }),
    },
  );

  if (!response.ok) {
    throw new Error(`Minerva API returned ${response.status}`);
  }

  const data = await response.json();
  const highRiskGroupId = data.result.profileGroup.id;
  ```

  ```python Python theme={null}
  import os
  import requests

  response = requests.post(
      "https://api.gominerva.com/tenant-config/v1/profile-groups",
      headers={
          "x-api-key": os.environ["MINERVA_API_KEY"],
          "Content-Type": "application/json",
      },
      json={
          "name": "High Risk",
          "description": "Enhanced diligence customers requiring the most frequent monitoring.",
          "priority": 100,
          "monitoringFeedFrequencies": {
              "Sanctions": "deltas",
              "PEP": "weekly",
              "News": "weekly",
          },
      },
      timeout=30,
  )
  response.raise_for_status()

  high_risk_group_id = response.json()["result"]["profileGroup"]["id"]
  ```
</CodeGroup>

Repeat the create call for medium and low risk populations:

```json theme={null}
[
  {
    "name": "Medium Risk",
    "description": "Standard monitored customers with periodic review.",
    "priority": 50,
    "monitoringFeedFrequencies": {
      "Sanctions": "daily",
      "PEP": "monthly",
      "News": "monthly"
    }
  },
  {
    "name": "Low Risk",
    "description": "Lower-risk customers monitored on a reduced cadence.",
    "priority": 10,
    "monitoringFeedFrequencies": {
      "Sanctions": "monthly",
      "PEP": "quarterly",
      "News": "quarterly"
    }
  }
]
```

## List Groups

```bash cURL theme={null}
curl -G "https://api.gominerva.com/tenant-config/v1/profile-groups" \
  -H "x-api-key: YOUR_API_KEY"
```

Archived groups are excluded by default. Include them when reconciling older
assignments:

```bash cURL theme={null}
curl -G "https://api.gominerva.com/tenant-config/v1/profile-groups" \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "includeArchived=true"
```

## Assign Profiles To Groups

Creating a profile group only creates the reusable segment. Assign profiles to
one or more groups by setting `profileGroupIds` on the profile create or update
request.

```bash cURL theme={null}
curl -X PATCH "https://api.gominerva.com/clm/v1/profiles/PROFILE_ID" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "profileGroupIds": [
      "665f0d4c2d2f7c2b2f2f2f31",
      "665f0d4c2d2f7c2b2f2f2f32"
    ]
  }'
```

Send an empty array to remove all group assignments from a profile:

```bash cURL theme={null}
curl -X PATCH "https://api.gominerva.com/clm/v1/profiles/PROFILE_ID" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"profileGroupIds": []}'
```

## Filter Profiles By Group

Use the profile list endpoint with `profile_group_ids` to retrieve profiles
assigned to any of the provided groups.

```bash cURL theme={null}
curl -G "https://api.gominerva.com/clm/v1/profiles" \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "profile_group_ids=665f0d4c2d2f7c2b2f2f2f31,665f0d4c2d2f7c2b2f2f2f32"
```

## Archive A Group

`DELETE` archives a profile group; it does not permanently delete it.

```bash cURL theme={null}
curl -X DELETE \
  "https://api.gominerva.com/tenant-config/v1/profile-groups/665f0d4c2d2f7c2b2f2f2f31" \
  -H "x-api-key: YOUR_API_KEY"
```

Archived groups are hidden from active group lists and dashboard selection, but
their IDs may still exist on older profile records for audit and reconciliation.