Potential Match export: ROCS utility access and exporting relevance score / match action

Question

The customer wants to export potential matches for a relevance-based match rule and asks whether the report can include:

• relevance score
• match action

Answer

ROCS Potential Match export does not include the relevance score, even when that score is visible in the Potential Match UI for relevance-based rules. I did not find any useful documentation on exporting the relevance score or match action in the ROCS report.

The best way to get potential match results along with relevance score and match action is through the API-based approach:  Reltio’s Potential Matches API for an existing entity is:

GET {TenantURL}/entities/{entity object URI}/_matches 

For relevance-based match groups, the response includes:

• relevance
• matchActionLabel

The documentation explicitly states that these fields appear for relevance-based match groups, and that matchActionLabel is derived from the rule’s actionThreshold configuration. If no label is configured, matchActionLabel does not appear.

Reltio also documents transitive matches:

GET {TenantURL}/entities/{entity object URI}/_transitiveMatches

This response includes a matchRuleSummaries section with per-rule relevance and actionLabel, along with the maximum relevance/action label summary for the pair.

For transient input that is not yet persisted as an entity, Reltio documents the Scored Matches API:

POST {TenantURL}/entities/_scoredmatches 

In addition, Reltio documents indexed potential-match search fields:

• relevanceScores.matchRule
• relevanceScores.relevance
• relevanceScores.actionLabel

Recommended resolution

Recommendation

Treat this as a custom extraction/reporting requirement, not as a ROCS report-format requirement.

Use documented APIs to:

1. enumerate potential match pairs
2. retrieve relevance score and match action
3. enrich the result with entity labels, crosswalks, and selected attributes as needed

This is the most supportable approach because the metadata the customer needs is already exposed by supported APIs.

Option A: Existing tenant entities

Use:

GET https://<env>.reltio.com/<tenant_id>/entities/<entity_uri>/_matches

This is appropriate when the left-side entity already exists in the tenant and the goal is to export its potential matches. For relevance-based rules, the response can include relevance and matchActionLabel.

Option B: Pair/path-oriented export

Use:

GET https://<env>.reltio.com/<tenant_id>/entities/<entity_uri>/_transitiveMatches

This is appropriate when you want pair-level context and rule summaries. The documented response includes matchRuleSummaries[].relevance and matchRuleSummaries[].actionLabel.

Option C: Transient or pre-persistence scoring

Use:

POST https://<env>.reltio.com/<tenant_id>/entities/_scoredmatches

This is appropriate when the input entity is provided as JSON and you want scored candidate matches without first persisting the entity.

Option D: Search/filter by relevance metadata

Use indexed search fields such as:

• relevanceScores.matchRule
• relevanceScores.relevance
• relevanceScores.actionLabel

This is useful when the customer wants to search or filter match populations by score thresholds, rule URI, or action label.

Possible script workflow to assist in the process.

Best practice

Use ROCS, if and when it is available, only as a pair enumerator. Use the supported APIs to fetch the richer metadata required for reporting. This separates “pair discovery” from “match metadata extraction” and avoids relying on undocumented extract columns. That recommendation is an inference from the official API capabilities and the current ROCS availability notice.

Suggested workflow

1. Obtain the list of candidate entity pairs.
2. For each pair, call _matches or _transitiveMatches to retrieve relevance/action metadata.
3. Call Entity GET to enrich the output with label, crosswalks, and attributes.
4. Normalize the pair key so A|B and B|A are handled consistently.
5. Generate the final CSV or downstream report.

Get an access token
 

#!/usr/bin/env bash

CLIENT_ID='<your_client_id>'
CLIENT_SECRET='<your_client_secret>'

BASIC_AUTH=$(printf '%s:%s' "$CLIENT_ID" "$CLIENT_SECRET" | base64)

ACCESS_TOKEN=$(curl -s --request POST 'https://auth.reltio.com/oauth/token' \
  --header "Authorization: Basic $BASIC_AUTH" \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'grant_type=client_credentials' | jq -r '.access_token')

echo "$ACCESS_TOKEN"

 
 
Call the supported potential matches API and isolate the pair
For your example pair:
 

• Left entity: entities/123
• Right entity: entities/456

You call _matches on the left entity.
 
 

TENANT_URL='https://<env>.reltio.com/<tenant_id>'
curl -s --request GET "$TENANT_URL/entities/123/_matches" \
  --header "Authorization: Bearer $ACCESS_TOKEN"

 
The response structure documented by Reltio for relevance-based matching is a map keyed by match group, where each entry contains objects with object.uri, relevance, and matchActionLabel.
 
Extract only the pair entities/123 | entities/456:
 
 

curl -s --request GET "$TENANT_URL/entities/123/_matches" \
  --header "Authorization: Bearer $ACCESS_TOKEN" |
jq -r '
  to_entries[]
  | .key as $matchGroup
  | .value[]
  | select(.object.uri == "entities/456")
  | {
      matchGroup: $matchGroup,
      leftEntityUri: "entities/123",
      rightEntityUri: .object.uri,
      relevanceScore: .relevance,
      matchAction: .matchActionLabel
    }
'

That extraction is supported by the documented response fields. If the response contains your stated values, the extracted result will be:
 
 

{
  "matchGroup": "configuration/entityTypes/.../matchGroups/...",
  "leftEntityUri": "entities/123",
  "rightEntityUri": "entities/456",
  "relevanceScore": 0.972,
  "matchAction": "Potential Match"
}

 
 
Enrich the two entities with supported entity fields
 
Reltio documents that GET {TenantURL}/{entity object URI} supports select=label, crosswalks, and attributes.
 
Left entity:
 

curl -s --request GET \
  "$TENANT_URL/entities/123?select=label,crosswalks,attributes" \
  --header "Authorization: Bearer $ACCESS_TOKEN"

 
Right entity:
 

curl -s --request GET \
  "$TENANT_URL/entities/456?select=label,crosswalks,attributes" \
  --header "Authorization: Bearer $ACCESS_TOKEN"

• Label is a standard selectable property.
• Crosswalks are a standard selectable property.
• Attributes are a standard selectable property.
• Each crosswalk may contain type, value, and sourceTable.

 
What you can extract 
You asked for:
 

• leftEntityUri → not a response field - derived from the request you made, not directly returned as a field named leftEntityUri.
• rightEntityUri → object.uri
• relevanceScore → relevance
• matchAction → matchActionLabel (only when configured/present)

These are directly obtainable.
 
Build the final row without inventing attribute names
This script:
 

• Gets the specific match pair
• Fetches both entities
• Extracts first crosswalk type|value
• Uses label for left/right names, because label is documented
• Leaves tenant-specific attributes as optional placeholders unless you replace them with your actual attribute URIs

TENANT_URL='https://<env>.reltio.com/<tenant_id>'
LEFT_URI='entities/123'
RIGHT_URI='entities/456'

MATCH_JSON=$(curl -s --request GET "$TENANT_URL/$LEFT_URI/_matches" \
  --header "Authorization: Bearer $ACCESS_TOKEN")

PAIR_JSON=$(echo "$MATCH_JSON" | jq '
  to_entries[]
  | .key as $matchGroup
  | .value[]
  | select(.object.uri == "'"$RIGHT_URI"'")
  | {
      matchGroup: $matchGroup,
      leftEntityUri: "'"$LEFT_URI"'",
      rightEntityUri: .object.uri,
      relevanceScore: .relevance,
      matchAction: .matchActionLabel
    }
')

LEFT_ENTITY=$(curl -s --request GET \
  "$TENANT_URL/$LEFT_URI?select=label,crosswalks,attributes" \
  --header "Authorization: Bearer $ACCESS_TOKEN")

RIGHT_ENTITY=$(curl -s --request GET \
  "$TENANT_URL/$RIGHT_URI?select=label,crosswalks,attributes" \
  --header "Authorization: Bearer $ACCESS_TOKEN")

jq -n \
  --argjson pair "$PAIR_JSON" \
  --argjson left "$LEFT_ENTITY" \
  --argjson right "$RIGHT_ENTITY" \
  '{
    matchGroup: $pair.matchGroup,
    leftEntityUri: $pair.leftEntityUri,
    rightEntityUri: $pair.rightEntityUri,
    relevanceScore: $pair.relevanceScore,
    matchAction: $pair.matchAction
  }'

That output is fully aligned with documented fields.  That can produce a row like:
 
 

"PotentialMatchByEmail","entities/123","entities/456","0.972","Potential Match","left label","right label","left source id","right source id"

Authentication

For machine-to-machine extraction, the recommended default is client_credentials.

Reltio documents token retrieval as:

POST https://auth.reltio.com/oauth/token

• Authorization: Basic <Base64(client_id:client_secret)>
• Content-Type: application/x-www-form-urlencoded
• body: grant_type=client_credentials

Supported enrichment fields

For entity enrichment, Reltio documents that GET {TenantURL}/{entity object URI} supports the select parameter, including:

• label
• crosswalks
• attributes

So the supported enrichment pattern is:

GET https://<env>.reltio.com/<tenant_id>/entities/<entity_uri>?select=label,crosswalks,attributes 

Example customer-facing resolution text

Final resolution

The current ROCS documentation indicates that ROCS utilities are temporarily unavailable while Reltio moves them to a governed distribution model, so the prior Bitbucket path should not be treated as the current supported access mechanism.

For the reporting requirement, the supported approach is to use Reltio APIs rather than depend on the ROCS extract format. The Potential Matches API for existing entities returns relevance-based metadata including relevance and, when configured, matchActionLabel. The Transitive Matches API also returns pair-level summaries in matchRuleSummaries, including relevance and actionLabel. For transient input, the Scored Matches API can be used.

Accordingly, the recommended design is to build a custom export/reporting flow that:

• enumerates the potential match pairs
• retrieves relevance score and match action using supported APIs
• enriches output with entity labels, crosswalks, and attributes as needed

Important supportability note

A custom report/export implementation is outside standard break-fix support scope. Customer Engineering can provide suggestions on the supported APIs and design direction, but the build-out of a custom extraction pipeline is typically a Professional Services or customer implementation activity. This boundary is not explicitly documented in the sources above, so this part should be presented as an internal delivery expectation rather than a product fact.