Skip to content

Salesforce

Operations

Lead → Contact Auto-Convert & Merge

Request

Converts Salesforce Leads to Contacts and Accounts with sophisticated matching and merging logic.

Overview

The Salesforce Conversion API provides automated Lead-to-Contact conversion with intelligent matching, duplicate prevention, and merge policies. It uses Salesforce Lead.Convert under the hood with batch API and includes duplicate protection via pre-check matching.

Request Body

  • lead_sf_id: Salesforce Lead ID to convert (required)
  • match_policy: Match policy configuration for contact and account matching
  • merge_policy: Merge policy configuration for handling matches
  • set_owner_round_robin_pool: Optional round-robin pool for owner assignment
  • logs: Logging configuration for conversion process

Match Policy

  • contact: Contact matching rules and creation policy
  • account: Account matching rules and creation policy
  • by: List of field rules for matching (e.g., ["email:eq", "name_company:fuzzy0.8"])
  • create_if_no_match: Whether to create new record if no match found

Merge Policy

  • on_contact_match: Action when contact match is found
    • merge_lead_into_contact: Moves notes/activities, preserves owner history
    • create_separate_contact: Creates separate contact record
  • on_account_match: Action when account match is found
    • attach_to_account: Attaches lead to existing account
    • create_separate_account: Creates separate account record

Response Fields

  • success: Boolean indicating request success
  • status: Conversion status (converted, failed, duplicate)
  • account_id: Created or matched Account ID
  • contact_id: Created or matched Contact ID
  • owner_id: Assigned Owner ID
  • actions: List of actions performed during conversion
  • credits_consumed: Number of credits used
  • processing_time_ms: Processing time in milliseconds
  • cached: Whether result was from cache

Features

  • Duplicate Protection: Pre-check via /v1/match to avoid duplicate contacts/accounts
  • Idempotent: Same Idempotency-Key repeats return prior result
  • Batch Processing: Uses Salesforce Lead.Convert with batch API
  • Round-Robin Assignment: Optional owner assignment from specified pools
  • Comprehensive Logging: Route logs and enrichment differences

Credit Usage

Salesforce conversion consumes credits based on complexity:

  • Basic Conversion: 3 credits per lead
  • With Matching: +2 credits for duplicate checking
  • With Round-Robin: +1 credit for owner assignment
Security
BearerAuth
Bodyapplication/jsonrequired
lead_sf_idstring(Lead Sf Id)required

Salesforce Lead ID to convert

match_policyobject(ConversionMatchPolicy)required

Match policy configuration

merge_policyobject(MergePolicy)required

Merge policy configuration

set_owner_round_robin_poolstring or null(Set Owner Round Robin Pool)
Any of:

Round-robin pool for owner assignment

string
logsobject(ConversionLogs)

Logging configuration

curl -i -X POST \
  https://api-gateway.agenthq.withlantern.com/v1/salesforce/convert \
  -H 'Authorization: Bearer <YOUR_ApiToken_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "lead_sf_id": "string",
    "match_policy": {
      "contact": {
        "by": [
          "string"
        ],
        "create_if_no_match": true
      },
      "account": {
        "by": [
          "string"
        ],
        "create_if_no_match": true
      }
    },
    "merge_policy": {
      "on_contact_match": "string",
      "on_account_match": "string"
    },
    "set_owner_round_robin_pool": "string",
    "logs": {
      "route_log": true,
      "enrichment_diff": true
    }
  }'

Responses

Success Response

Bodyapplication/json
successboolean(Success)required

Boolean indicating request success

statusstring(Status)required

Conversion status

Enum:"converted""failed""duplicate"
account_idstring or null(Account Id)
Any of:

Created or matched Account ID

string
contact_idstring or null(Contact Id)
Any of:

Created or matched Contact ID

string
owner_idstring or null(Owner Id)
Any of:

Assigned Owner ID

string
actionsArray of strings(Actions)required

List of actions performed during conversion

Response
{
  "success": true,
  "status": "converted",
  "account_id": "001xx0001ABCDEF",
  "contact_id": "003xx0002HIJKLM",
  "owner_id": "005xx0003NOPQRS",
  "actions": [
    "lead_merged",
    "contact_created",
    "assigned_round_robin"
  ],
  "credits_consumed": 6,
  "processing_time_ms": 2500,
  "cached": false
}