PingIDM

Reconciliation operations

You can interact with the reconciliation engine over REST, as shown in the following table:

URI HTTP Method Description

/openidm/recon

GET

Lists all reconciliation runs, including those in progress. Inspect the state property to see the reconciliation status.

/openidm/recon/id

GET

Returns the JSON representation of a specific reconciliation run.

/openidm/recon?_action=recon

POST

Launches a reconciliation run with the specified mapping.

A JSON body can be included in the POST request to override specific mapping configuration parameters for this run only. For example, sourceQuery, targetQuery, or runTargetPhase can be adjusted dynamically.

Parameters

&mapping=mapping-name (Required)

Specifies the mapping to use.

&waitForCompletion=true

If set, the REST call blocks until the reconciliation completes.

This parameter isn’t supported for clustered reconciliation environments and will result in an error if used.
&persistAssociations=true

Stores detailed association results for this run, queryable with recon/assoc endpoints. Learn more in Reconciliation association details. Performance impact should be considered for large reconciliations.

&analyze=true

Performs an analysis run, determining actions without executing them. Requires persistAssociations=true to store and query the analysis results effectively. Learn more in Reconciliation association details.

/openidm/recon?_action=reconById

POST

Restricts the reconciliation run to the specified source object ID (id).

Parameters

&mapping=mapping-name (Required)

Specifies the mapping to use.

&id=source-id (Required)

The _id of the source object to reconcile.

You can include a JSON body in the POST request to override specific mapping configuration properties for this run only.

Optional request body properties

sourceQuery

Overrides the source query.

targetQuery

Overrides the target query.

allowEmptySourceSet

Overrides whether reconciliation proceeds when the source object set is empty. Learn more in Prevent the accidental deletion of a target system.

runTargetPhase

Set to false to skip the target phase for this run.

sourceQueryFullEntry

Overrides whether the source query returns full object data (true) or IDs only (false).

targetQueryFullEntry

Overrides whether the target query returns full object data (true) or IDs only (false).

Learn more in Override mapping configuration for reconById.

/openidm/recon/id?_action=cancel

POST

Cancels the specified reconciliation run.

/openidm/recon/assoc

GET

Lists stored reconciliation association summaries. Requires runs performed with persistAssociations=true. Supports standard query parameters like _queryFilter.

/openidm/recon/assoc/id

GET

Returns the association summary for a specific reconciliation run.

/openidm/recon/assoc/id/entry

GET

Returns detailed entry-level association information for a specific reconciliation run. Results can be large. Supports standard query parameters like _queryFilter.

/openidm/recon/id

DELETE

Purges the statistics and stored association data for a specific reconciliation run. Learn about configuring this to run automatically in Purge reconciliation statistics.

The following example runs a reconciliation for the mapping systemHrdb_managedUser:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request POST \
"http://localhost:8080/openidm/recon?_action=recon&mapping=systemHrdb_managedUser"