Handle duplicate record errors using auto-link in the Salesforce Connector
Learn how the Salesforce Connector automatically resolves duplicate record creation errors by linking matched Salesforce records to existing Reltio entities.
When the Salesforce Connector attempts to create a record in Salesforce and Salesforce detects a duplicate, the operation fails with a DUPLICATES_DETECTED error. This typically occurs when a matching Salesforce record already exists, but the Reltio entity does not yet have a Salesforce crosswalk.
The auto-link duplicates capability allows the connector to recover from this failure automatically. When enabled, the connector can identify the matching Salesforce record, link it to the Reltio entity, and retry the operation as an update. This eliminates the need for manual recovery and ensures reliable synchronization between Reltio and Salesforce.
How auto-linking works
When auto-linking is enabled and a create operation fails with DUPLICATES_DETECTED, the connector evaluates the duplicate response returned by Salesforce.
- The connector parses the duplicate payload and extracts matched Salesforce record IDs from
duplicateResult.matchResults.matchRecords.record.Id. - If exactly one Salesforce ID is found, the connector calls a Salesforce Apex REST endpoint to create a crosswalk between the Salesforce record and the Reltio entity.
- The connector sends a POST request to the following endpoint using the same Salesforce org authentication:
POST /services/apexrest/rel/auto-link Content-Type: application/json { "reltioEntityUri": "entities/<reltioId>", "sfId": "001…", "sourceTable": "Account | Contact | Lead", "sourceType": "configuration/sources/Salesforce" } - Based on the Apex response, the connector determines whether to retry the failed operation as an update or return the original error.
Auto-linking configuration parameters
Auto-link behavior is controlled through tenant profile configuration. By default, the feature is disabled, and the connector preserves the legacy behavior, returning the DUPLICATES_DETECTED error without attempting recovery.
| Parameter | Type | Default | Description |
|---|---|---|---|
salesforce.autoLinkForDuplicateRecord | Boolean | false | Enables automatic linking when a create operation fails with DUPLICATES_DETECTED and exactly one matching Salesforce record is found. |
How the connector handles duplicate record errors
The connector’s behavior depends on the number of matched Salesforce records and the response from the Apex auto-link endpoint.
- Exactly one matched Salesforce ID: The connector attempts auto-linking. If the endpoint returns
{ linked: true }with HTTP 200 or 201, it retries the operation as an update. - Auto-link returns HTTP 409: The connector treats this as “already linked”. The Salesforce ID is set on the operation, errors are cleared, and the create operation is not retried.
- No matches or multiple matches: Auto-linking is skipped. The connector logs a clear message and returns the original
DUPLICATES_DETECTEDerror.
If auto-linking fails due to an unexpected error, the connector surfaces the original Salesforce error and records diagnostic details in the logs to support troubleshooting.