Skip to main content
Use the Admin API to manage your organization’s workspaces and their configuration from your own tooling: create a workspace for a new book of business, define its profile groups and monitoring cadences, and switch custom lists on, without anyone working through the Minerva dashboard. These endpoints need an admin application key. Workspace-scoped and tenant-scoped keys keep working for screening and profile management. These endpoints refuse them for reads as well as changes. To create and update profile groups with a workspace-scoped key, use the Profile Groups API. This guide covers the admin key, authentication, each endpoint family, how monitoring cadences resolve across workspaces and profile groups, the error codes, and a complete walkthrough.

The admin application key

An admin application key is a tenant-wide key that can create, update, archive, and delete workspaces, and edit every workspace’s configuration through the API. In the Minerva dashboard it appears as the Admin (tenant-wide) key type.
  • Only an Owner or Admin can create, edit, rotate, deactivate, or delete an admin key. Developers see the Admin (tenant-wide) option disabled, with a hint to ask an owner or admin.
  • The key acts only while the person who created it is still an owner or admin of the organization. If that person is demoted, disabled, or removed, every Workspace Management API request made with the key is refused with 403 from the next request onward. Create a replacement key from an account that still holds the role.
  • The admin role can be set only when the key is created. You cannot change an existing workspace-scoped or tenant-scoped key into an admin key: that request returns 400 with the message “Admin role can only be set when an application is created. Create a new admin application instead.”
  • The key belongs to one organization. It is never accepted for another organization’s orgId.
  • Changes made with an admin key are recorded in the audit trail under the application’s name, not under a person.
  • The Workspace Management API does not cover team management or SSO and SCIM settings. Those stay dashboard-only. Profiles and searches have their own APIs, which an admin key can also call for one workspace at a time. See One workspace per client.
An admin key can rewrite every workspace in your organization. For most use cases, we recommend workspace-scoped keys, which follow least-privilege access. Create an admin key only for the integration that provisions or configures workspaces, keep it in a secrets manager, and deactivate it when that integration is retired.

Create an admin key

  1. Sign in as an Owner or Admin and open Administration > Developers.
  2. On API keys, select Create application.
  3. Enter a name and an optional description, and choose Live mode. Admin keys can’t be created in Dev mode.
  4. Under Scope, choose Admin (tenant-wide). Minerva sets Mode to Live and shows “Admin keys are always Live.”
  5. Create the application and copy the key. Minerva shows the plaintext key only once.
See API Keys for the full key lifecycle, including deactivation and deletion.

Authentication and base URL

Send every request to https://api.gominerva.com. Workspace paths start with /workspaces/v2/organizations/{orgId}, and custom-list activation paths start with /custom-lists/v2/organizations/{orgId}:
admin-api.gominerva.com is deprecated for API clients. It keeps working for now, but new and updated integrations should call api.gominerva.com. The paths change as well as the host:
  • admin-api.gominerva.com/v2/organizations/{orgId}/custom-lists/… becomes api.gominerva.com/custom-lists/v2/organizations/{orgId}/…
  • admin-api.gominerva.com/v2/organizations/{orgId}/workspaces/… becomes api.gominerva.com/workspaces/v2/organizations/{orgId}/…
  • admin-api.gominerva.com/v2/webhooks/screening/… becomes api.gominerva.com/webhooks/v2/screening/…
Authenticate with the admin key in the Authorization header. The legacy x-api-key header is also accepted.
orgId is your organization ID, and it must be the organization the key was created in. Successful responses wrap the record in a data envelope that echoes the organization ID:

Endpoints

The Admin Actions - Endpoints reference in this tab, starting at List workspaces, lists every request and response field. The tables below summarize what each family does.

Workspaces

  • POST requires name and accepts the same configuration sections as PATCH, such as monitoringFeedFrequencies, monitoringRiskFrequencies, matchScoring, automaticDisposition, and riskInference. clientRiskRating is accepted on PATCH only.
  • PATCH is sparse at the top level. A section you omit keeps its stored value. A section you send replaces that section, so send the complete monitoringFeedFrequencies map you want to keep.
  • Unknown fields are rejected with 400.
  • Archive a workspace with PATCH and {"archived": true} before you delete it. The default workspace cannot be archived or deleted.

Profile groups

  • POST requires name (up to 160 characters) and priority. description (up to 4,000 characters) and monitoringFeedFrequencies are optional.
  • priority is an integer from 0 to 1000000. Higher values win when a profile belongs to several groups, and each priority can be used by only one active group in a workspace. Reusing one returns 409.
  • A group PATCH that carries monitoringFeedFrequencies replaces the group’s whole cadence map. Include every feed you want the group to keep.
  • DELETE archives the group rather than erasing it, so profiles that still reference it keep an auditable assignment.
For what profile groups are and how to assign profiles to them, see the Profile Groups API and the Profile Groups Guide.

Presets

  • configType is match_scoring or alert_suppression. A preset body carries configType, label, an optional description, and the config object.
  • A promotion body names configType, targetWorkspaceId, and an optional changeSummary. Promotion also accepts customer_risk_rating, in which case presetId is a CRR scorecard ID.
See the Workspaces Guide for how presets and promotion fit a Calibration-to-Live workflow.

Customer Risk Rating

Profile custom fields

Profile custom fields are defined once for the whole organization. Manage the definitions at https://api.gominerva.com/tenant-config/v1/profile-custom-fields, which accepts any application key for your organization, including an admin key. The organization comes from the key, so these paths carry no organization or workspace ID. An admin key must also send the x-workspace-id header with the ID of any workspace in your organization, or the request returns 400; the definitions stay organization-wide. These responses wrap the record in result, with a message, not in the data envelope above. The Profile Custom Fields API page describes the definition fields, the field types, and how values are written on profiles.

Custom-list activation and entitlements

An admin key can read your custom-list entitlements and switch lists on or off in a workspace. To create lists, sync records, publish versions, and track deployment, see the Custom Lists API. The activation body takes enabled (default true). When you switch a list on, feedCategory and versionId are required so the list is bound to the feed and published version you intend.

Monitoring cadences

Monitoring cadences decide how often each data feed rescreens a profile. You set them per feed (Sanctions, PEP, News, Legal, Criminal, Internal) in a monitoringFeedFrequencies map, on a workspace and on each profile group. In the dashboard, News appears as Adverse Media and Internal as Internal Risk. A workspace can also set cadences per risk tier in monitoringRiskFrequencies (low, medium, high), which apply to profiles with that customer risk rating.

How a profile’s cadence is resolved

Minerva resolves each feed on its own.
  1. Minerva orders the profile’s active groups by priority, highest first.
  2. It checks the groups in that order. The first group that sets a cadence for the feed, including never, decides the feed for the groups.
  3. A group set to unset passes the decision to the next group down.
  4. If every group is set to unset, the risk tier decides. If the risk tier sets no cadence for the feed, the feed is never. It does not fall back to the workspace cadence.
  5. If the highest-priority group leaves the feed empty, the profile uses its risk-tier cadence, or the workspace cadence when the risk tier sets none. Once a group has passed the decision down with unset, a lower group that leaves the feed empty is skipped too.
Risk tiers have fixed priorities: low 800, medium 900, and high 1000. When the profile’s risk tier sets a cadence for the feed, that cadence applies unless the group that decided the feed has a higher priority than the tier. A tie goes to the risk tier. To let a group override every risk tier, give it a priority above 1000. Two consequences follow:
  • never beats unset. A group set to never decides the feed, so a lower group cannot turn it back on. Only a risk tier that outranks the group can.
  • Empty and unset are different. Empty on the top group means “use the risk tier or workspace cadence”. unset means “let a lower group or the risk tier decide, and otherwise do not monitor”.
unset is valid only on profile groups. Sending it in a workspace’s monitoringFeedFrequencies or in monitoringRiskFrequencies returns 400. Use never there to stop monitoring a feed.

Example: combining two groups

Group A monitors Sanctions daily and leaves every other feed unset:
Group B monitors PEP monthly and leaves every other feed unset:
A profile in both groups, with no risk-tier cadence for these feeds, is monitored like this, whichever group has the higher priority: A profile only in group A, with no risk-tier cadence, is monitored for Sanctions daily and nothing else.

Errors

Most error responses carry the message as a plain string in the body. Custom-list activation can also return a JSON object with error and message fields, as the 409 and 422 rows below describe. When the response’s Content-Type is application/json, parse the body as JSON.

Walkthrough: set up a new workspace

This walkthrough creates a workspace, adds the two groups from the example above, adjusts their priorities, and assigns a profile to both. Set these variables first:

1. Create the workspace

The workspace monitors Sanctions and PEP weekly for profiles that are not in any group.
cURL
The response returns 201 with the new workspace in data.workspace. Keep data.workspace.id as WORKSPACE_ID.

2. Create two profile groups

cURL
cURL
Each response returns 201 with the group in data.profileGroup. Keep the two IDs as GROUP_A_ID and GROUP_B_ID.

3. Set priorities

Priority decides which group is checked first. Raise group B above group A with a PATCH that carries only priority, so the group’s cadences are left as they are:
cURL
In this example the order does not change the result, because each group is set to unset for the other group’s feed. Priority matters when two groups both set a cadence for the same feed. These priorities are below every risk-tier priority, so a risk-tier cadence for the profile’s rating would still win. Use a priority above 1000 if a group must override risk tiers.

4. Assign a profile to both groups

Profile assignment is part of profile management, on https://api.gominerva.com/clm/v1, not the Admin API. You can use the same admin key and name the workspace in the x-workspace-id header, or use a workspace-scoped key created for the new workspace:
cURL
If the profile’s risk tier sets no cadence for these feeds, it is now monitored for Sanctions daily and PEP monthly, and is not monitored on News, Legal, Criminal, or Internal.

One workspace per client: the full API chain

If you serve several clients of your own, you can give each one its own workspace and run their whole monitoring setup with a single admin key. The admin key is tenant-wide, so every call outside the Workspace Management API names the client’s workspace in the x-workspace-id header. The chain below creates the workspace, adds profile groups, creates and screens a monitored profile, reads its matches, assigns its groups, and reads its screening history. A workspace is usable as soon as the create call returns. There is no propagation delay. The examples send the key in the Authorization: Api-Key header. Every endpoint in the chain also accepts the x-api-key header used elsewhere in these docs.
To receive monitoring events for every client, register one tenant-scoped receiver before creating the workspaces. It also covers future workspaces.

1. Create the client’s workspace

cURL
Keep data.workspace.id from the 201 response as WORKSPACE_ID. A new workspace starts as a copy of your default workspace’s onboarding feeds, monitoring cadences, allowed feeds, match scoring, and custom lists. Anything you send in the create call replaces the copied value. Check the copied onboarding feeds before you onboard profiles: if they leave out a feed you need, such as Sanctions, set them as shown above or name the feeds on each onboarding call.

2. Create profile groups in it

cURL
Keep data.profileGroup.id as GROUP_ID. See Profile groups for the cadence fields a group can carry.

3. Create and screen a monitored profile

You can create and screen a profile in one call, or create it first and screen it later. Use one of the following alternatives for the same subject.

Create and screen in one call

POST /clm/v1/onboarding/profiles creates the profile and screens it in the same call:
cURL
The 201 response carries the profile in result.profile, including its screened status, and any review tasks in result.tasks. Keep result.profile.id as PROFILE_ID.

Create first, then screen the existing profile

First, create a monitored profile without screening it:
cURL
Keep result.profile.id from the 201 response as PROFILE_ID. The profile starts with status not_screened. To screen that existing profile, send the onboarding request shown above with the same externalId and the same x-workspace-id. Minerva returns the same profile ID, applies the screening result to the profile, and returns any review tasks. Without the same external reference in the same workspace, the request does not select that existing profile and can create a second one. The example explicitly disables identity verification so this is a screening-only request. If you do not screen it through onboarding, each feed’s first scheduled monitoring screening waits until its cadence interval has passed since the profile was created. For a monthly feed that is about a month later.
A direct Core search with profile_id associates the search and its stored matches with the profile for history retrieval. It does not update the profile’s screening status or last-screening fields, or trigger the profile screening workflow. Use the onboarding endpoint above to screen an existing profile and update that workflow.

4. Fetch the profile’s matches

cURL
The response lists the stored potential matches in matches[]. Each one carries the request_id of the screening that produced it.

5. Assign profile groups

cURL
profileGroupIds replaces the profile’s whole group list.
  • Minerva rejects an ID that does not match an active group in this workspace with 400. That covers unknown IDs and groups from another workspace.
  • An ID that is already on the profile can be sent again even if that group has since been archived, so you can resend the full list without removing it first.
You can also pass profileGroupIds in the step 3 create call.

6. Read the profile’s screening history

cURL
Each item in requests[] is one screening of the profile, including runs that found nothing. See Monitoring run history.

Workspace scoping rules

These rules apply to the profile, search, and match APIs above.
An admin key without x-workspace-id reads across every client’s workspace. Send the header on every profile, search, and match call so one client’s data never appears in another client’s results.