> ## Documentation Index
> Fetch the complete documentation index at: https://docs.genesiscomputing.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Salesforce Connector Tools

> Read and update Salesforce CRM records, with irreversible Lead, Contact, and Account merges governed by Action Review.

## Overview

<Note>
  Before using this tool group, save a Salesforce connection in **Config -> Connections**. See [Salesforce](/docs/Setup/Salesforce) for OAuth, server-to-server, and merge opt-in settings.

  Merges are **permanent** — Salesforce repoints child records and deletes the losers. Agents can preview and submit a proposal to Action Review, but they cannot approve their own proposal. When `review_required` is `true`, a genuinely authenticated human must approve it through Action Review before execution.
  If Salesforce refuses the single merge request, the outcome is `not_applied`; an uncertain provider response is `reconciliation_required` and must not be retried. See the [CRM merge API outcome contract](/docs/Genesis-API/API-Reference#crm-merge-endpoints).
</Note>

### Tool Name

```json theme={null}
salesforce_connector_tools
```

### Purpose

The **salesforce\_connector\_tools** group integrates Genesis with Salesforce CRM. Query records with SOQL, inspect object metadata, create, update, upsert, and delete records, and run the Action Review-governed merge workflow for duplicate **Lead**, **Contact**, and **Account** records.

#### Functions Available

1. **`salesforce_connector`**: Bounded Salesforce reads, record mutations, and merge preview / request / execute actions.

## Input Parameters

### `salesforce_connector`

**Parameters**

| **Name** | **Definition** | **Format** | **Default** |
| - | - | :-: | :-: |
| **action** | Operation to perform. Supported: `soql_query`, `list_objects`, `describe_object`, `describe_fields`, `get_record`, `create_record`, `update_record`, `upsert_record`, `delete_record`, `preview_merge`, `request_merge_approval`, `execute_merge`. | String (required) | none |
| **connection** | Salesforce connection name such as `salesforce.production`. Merge actions require an explicit connection; read and record actions may use the effective default. | String | none |
| **soql** | SELECT-only SOQL statement for `soql_query`. | String | none |
| **max\_records** | Maximum records returned by `soql_query`. | Integer | `2000` |
| **custom\_only** | For `list_objects`, return only custom Salesforce objects. | Boolean | `false` |
| **object\_name** | Salesforce sObject API name, such as `Account` or `Custom_Object__c`. Merge actions support only `Lead`, `Contact`, and `Account`. | String | none |
| **record\_id** | 15- or 18-character Salesforce record ID. | String | none |
| **fields** | Optional Salesforce field API names to return from `get_record`. | Array of strings | none |
| **data** | Field/value object for `create_record`, `update_record`, or `upsert_record`. | Object | none |
| **external\_id\_field** | External-ID field API name for `upsert_record`. | String | none |
| **external\_id** | External-ID value for `upsert_record`. | String | none |
| **survivor\_id** | Salesforce ID of the record that survives a merge. | String | none |
| **loser\_ids** | One or two Salesforce record IDs to merge into the survivor. | Array of strings | none |
| **expected\_digest** | Optional preview digest that `request_merge_approval` must reproduce. | String | none |
| **ttl\_seconds** | Lifetime of a pending merge approval in seconds. | Integer | `3600` |
| **approval\_id** | Action Review proposal ID returned by `request_merge_approval`, required by `execute_merge`. | String | none |

<Note>
  **Read-only connections:** When the connection locator sets `read_only` to a truthy value, or `access_intent` to `read` or `read_only`, write and merge actions are refused.

  **Merge opt-in:** `preview_merge`, `request_merge_approval`, and `execute_merge` require `merge_enabled` on the connection locator and a valid `merge_survivorship_policy` JSON object. See [Salesforce](/docs/Setup/Salesforce#approval-gated-merge).

  **Deleting a Lead, Contact, or Account:** an agent's `delete_record` of one of these types goes to Action Review, because updating one record, moving its related records, and deleting the other has the same effect as a merge. Object names are matched case-insensitively. The agent's call deletes nothing and returns `pending_review: true`; a person must approve the request in Action Review, and Genesis then sends the one delete. Tell the user it is waiting for approval; do not retry the call or reach the same result another way. A person always decides these requests, whatever the Action Review policy says. Deletes of other object types, and every create, update, and upsert, run at once as before.
</Note>

<Warning>
  **Merge workflow:** Always follow `preview_merge` → `request_merge_approval` → Action Review → `execute_merge`. A proposal ID beginning with `ap_` identifies an Action Review proposal. If `review_required` is `true`, an authenticated human must approve it in Action Review; when it is `false`, proceed to execution. There is no unmerge. If execution times out or the transport fails, the merge may already have succeeded in Salesforce — reconcile state instead of retrying blindly.

  If the governed merge is refused before its first write, `execute_merge` returns the handler's refusal reason and optional detail; see the [Action Review response contract](/docs/Genesis-API/API-Reference#action-review-response-fields).
</Warning>

**Example — SOQL query**

```python theme={null}
salesforce_connector(
    action="soql_query",
    connection="salesforce.production",
    soql="SELECT Id, Name, Email FROM Contact WHERE Email != null LIMIT 50",
)
```

**Example — merge preview**

```python theme={null}
salesforce_connector(
    action="preview_merge",
    connection="salesforce.production",
    object_name="Account",
    survivor_id="001000000000001AAA",
    loser_ids=["001000000000002AAA"],
)
```

## Use Cases

1. **Inspect CRM data** — `soql_query`, `get_record`, or `describe_object` when a user asks about Salesforce accounts, leads, or contacts.
2. **Update a record** — `update_record` or `upsert_record` when a workflow should write back to Salesforce.
3. **Duplicate review** — `preview_merge` to show what an Account, Lead, or Contact merge would do before any write.
4. **Governed merge** — `request_merge_approval` after preview, then inspect the returned `review_required` value; if it is `true`, a human approves the Action Review proposal, then `execute_merge` with the returned `approval_id`.

## Related pages

* [Salesforce](/docs/Setup/Salesforce)
* [Connections](/docs/Setup/Connections)
* [ServiceNow Connector Tools](/docs/Genbot-Toolkit/ServiceNow-Connector-Tools)
* [Salesforce merge endpoints](/docs/Genesis-API/API-Reference#salesforce-merge-endpoints)
* [CRM merge endpoints](/docs/Genesis-API/API-Reference#crm-merge-endpoints)