# Lead → Contact Auto-Convert & Merge

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
- credits_remaining: Credits remaining in account
- 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

Endpoint: POST /v1/salesforce/convert
Version: 1.4.1
Security: BearerAuth

## Request fields (application/json):

  - `lead_sf_id` (string, required)
    Salesforce Lead ID to convert

  - `match_policy` (object, required)
    Match policy configuration

  - `match_policy.contact` (object, required)
    Contact matching policy

  - `match_policy.contact.by` (array, required)
    List of field rules for matching

  - `match_policy.contact.create_if_no_match` (boolean, required)
    Whether to create new record if no match found

  - `match_policy.account` (object, required)
    Account matching policy

  - `merge_policy` (object, required)
    Merge policy configuration

  - `merge_policy.on_contact_match` (string, required)
    Action when contact match is found

  - `merge_policy.on_account_match` (string, required)
    Action when account match is found

  - `set_owner_round_robin_pool` (any)
    Round-robin pool for owner assignment

  - `logs` (object)
    Logging configuration

  - `logs.route_log` (boolean)
    Whether to log routing information

  - `logs.enrichment_diff` (boolean)
    Whether to log enrichment differences

## Response 200 fields (application/json):

  - `success` (boolean, required)
    Boolean indicating request success

  - `status` (string, required)
    Conversion status
    Enum: "converted", "failed", "duplicate"

  - `account_id` (any)
    Created or matched Account ID

  - `contact_id` (any)
    Created or matched Contact ID

  - `owner_id` (any)
    Assigned Owner ID

  - `actions` (array, required)
    List of actions performed during conversion

## Response 400 fields (application/json):

  - `success` (boolean)
    Always false for error responses

  - `error` (string, required)
    Error message

  - `details` (any)
    Additional error details

  - `request_id` (any)
    Request ID for tracking

  - `retry_after` (any)
    Seconds to wait before retrying for rate limit errors

## Response 401 fields (application/json):

  - `success` (boolean)
    Always false for error responses

  - `error` (string, required)
    Error message

  - `details` (any)
    Additional error details

  - `request_id` (any)
    Request ID for tracking

  - `retry_after` (any)
    Seconds to wait before retrying for rate limit errors

## Response 402 fields (application/json):

  - `success` (boolean)
    Always false for error responses

  - `error` (string, required)
    Error message

  - `details` (any)
    Additional error details

  - `request_id` (any)
    Request ID for tracking

  - `retry_after` (any)
    Seconds to wait before retrying for rate limit errors

## Response 409 fields (application/json):

  - `success` (boolean)
    Always false for error responses

  - `error` (string, required)
    Error message

  - `details` (any)
    Additional error details

  - `request_id` (any)
    Request ID for tracking

  - `retry_after` (any)
    Seconds to wait before retrying for rate limit errors

## Response 422 fields (application/json):

  - `detail` (array)

  - `detail.loc` (array, required)

  - `detail.msg` (string, required)

  - `detail.type` (string, required)

## Response 429 fields (application/json):

  - `success` (boolean)
    Always false for error responses

  - `error` (string, required)
    Error message

  - `details` (any)
    Additional error details

  - `request_id` (any)
    Request ID for tracking

  - `retry_after` (any)
    Seconds to wait before retrying for rate limit errors

## Response 500 fields (application/json):

  - `success` (boolean)
    Always false for error responses

  - `error` (string, required)
    Error message

  - `details` (any)
    Additional error details

  - `request_id` (any)
    Request ID for tracking

  - `retry_after` (any)
    Seconds to wait before retrying for rate limit errors