Profile Groups API - Minerva Docs

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 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.

Endpoints

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:

x-api-key: YOUR_API_KEY

Application API keys are managed from Administration > Developers 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.

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

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.

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"
    }
  }'

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;

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"]

Repeat the create call for medium and low risk populations:

[
  {
    "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

cURL

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:

cURL

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.

cURL

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:

cURL

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.

cURL

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.

cURL

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.

​Endpoints

​Object Model

​Monitoring Frequencies

​Create Risk Segments

​List Groups

​Assign Profiles To Groups

​Filter Profiles By Group

​Archive A Group

Endpoints

Object Model

Monitoring Frequencies

Create Risk Segments

List Groups

Assign Profiles To Groups

Filter Profiles By Group

Archive A Group