Profile Groups API

Profile groups are workspace-scoped segment labels that you assign to CLM profiles. Use the Profile Groups API to create and maintain them, so you can segment customers by risk population, product line, or onboarding cohort without creating a new workspace for each population. A group carries a customer-facing name, an optional description, a priority, and optional per-feed monitoring cadence overrides. Higher priority wins when a profile has many groups. For the concepts behind segmentation and the dashboard workflows, see the Profile Groups Guide and Profile Groups.

Access and scope

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.

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. See API Keys for how keys are created and scoped.

Create a profile group

Create a group with POST /profile-groups. The example below builds a high risk segment: Sanctions monitored on supported source deltas, PEP and News weekly. monitoringFeedFrequencies is optional: a feed you omit inherits the workspace-level cadence. See Monitoring frequencies for the feed keys and allowed values.

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, which use less frequent monitoring:

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

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": []}'

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"

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.

Profile group fields

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. For the dashboard equivalent of these cadences, see the Screening Frequencies Guide.

API Documentation

Screening - Endpoints

Admin Actions - Endpoints

Profiles - Endpoints

Agent Risk Assessments - Endpoints

Identity Verification - Endpoints

Access and scope

Create a profile group

Assign profiles to groups

List groups

Filter profiles by group

Archive a group

Profile group fields

Monitoring frequencies

​Access and scope

​Create a profile group

​Assign profiles to groups

​List groups

​Filter profiles by group

​Archive a group

​Profile group fields

​Monitoring frequencies

Access and scope

Create a profile group

Assign profiles to groups

List groups

Filter profiles by group

Archive a group

Profile group fields

Monitoring frequencies