Fix grouping match issues for entities and associations
Learn how to use the fixGroupingMatchesState API to remove stored grouping match state for selected entities or associations and trigger asynchronous rematching.
Use the fixGroupingMatchesState API to remove stored grouping match data that can become inconsistent due to processing failures, programmatic errors, or unexpected shutdowns. The API deletes stored grouping matches and related association link data for the resolved member entities. It then publishes match update events, and rematching and regrouping run asynchronously to rebuild the correct state.
HTTP method and endpoint
POST {ApplicationURI}/reltio/tools/matching/fixGroupingMatchesState?tenantId={tenantId}Query parameters
The following table describes the query parameters and their values.
| Parameter | Type | Required | Description | Accepted values / Default |
|---|---|---|---|---|
| tenantId | String | Yes | The unique identifier of the tenant. | Example: ce5627DYnQ6abcD |
Request body
The following table describes the request body parameters, including accepted values and defaults.
| Parameter | Type | Required | Description | Accepted values / Default |
|---|---|---|---|---|
| entities | Array of Strings | Yes* | List of entity IDs for which grouping matches state should be fixed. | Example: ["entityId1","entityId2"]. |
| associations | Array of Strings | Yes* | List of association IDs for which grouping matches state should be fixed. | Example: ["associationId1","associationId2"]. |
| matchGroupUri | String | No | Optional Match Group URI to include for additional context during processing. | Example: matchGroups/12345. |
| trace | Boolean | No | Enables trace logging for debugging. | Default: false |
*Either entities or associations must be provided.
Example request
Use the following example to see how a complete request is structured with a JSON body.
POST {ApplicationURI}/reltio/tools/matching/fixGroupingMatchesState?tenantId={tenantId}
{
"entities" : [ "00005KL" ],
"matchGroupUri" : "configuration/entityTypes/HCP/matchGroups/AutomaticGrouping",
"trace" : true
}Response body
The following table describes the fields returned in the response body.
| Field | Type | Description |
|---|---|---|
| tenantId | String | Tenant identifier associated with the operation. |
| deletedMatches | Array of Objects | List of deleted grouping matches. Each item includes primaryId, secondaryId, and matchGroups. |
| deletedMatches.primaryId | String | Primary entity identifier for the deleted match pair. |
| deletedMatches.secondaryId | String | Secondary entity identifier for the deleted match pair. |
| deletedMatches.matchGroups | Array of Strings | Match group URIs associated with the deleted match pair. |
| entitiesProcessed | Number | Total number of entities processed. |
| deletedAssociations | Array of Strings | List of association IDs deleted or updated as part of the operation (as represented in the report). |
| associationsProcessed | Number | Total number of associations processed. |
| processedEvents | Object | Event processing report, including event IDs that were sent or failed. |
| processedEvents.sentEvents | Array of Strings | List of event IDs that were successfully sent. |
| processedEvents.failedEvents | Array of Strings | List of event IDs that failed to send. |
Example response
The following example shows a response with details about the actions performed in the scope of the call.
{
"tenantId": "tenant_abc123",
"deletedMatches": [
{
"primaryId": "entityId1",
"secondaryId": "entityId2",
"matchGroups": [
"matchGroups/12345",
"matchGroups/67890"
]
},
{
"primaryId": "entityId3",
"secondaryId": "entityId4",
"matchGroups": [
"matchGroups/54321"
]
}
],
"entitiesProcessed": 4,
"deletedAssociations": [
"associationId1",
"associationId2"
],
"associationsProcessed": 2,
"processedEvents": {
"sentEvents": [
"eventId1001",
"eventId1002"
],
"failedEvents": [
"eventId1003"
]
}
}