Simple-Salesforce

1.12.9 · active · verified Sun Mar 29

Simple-Salesforce is a basic Salesforce.com REST API client built for Python 3.9 and newer versions. It provides a low-level interface to the Salesforce REST Resource and APEX API, returning JSON responses as Python dictionaries. The library facilitates common operations like authentication, CRUD operations on Salesforce objects, SOQL/SOSL queries, and interaction with Bulk and Metadata APIs. It's actively maintained with regular bug fixes and feature enhancements.

Warnings

breaking Breaking Change in v1.0.0: The default Salesforce API Version was increased to 42.0. This might affect queries or object interactions if your Salesforce instance expects an older API version. Additionally, support for Python 2.6, 2.7, 3.3, and 3.4 was removed.
Fix: Explicitly specify the desired API version in the `Salesforce` constructor using `sf_version='X.Y'` (e.g., `sf_version='41.0'`). Ensure your project runs on Python 3.9+ for compatibility.
gotcha Security Token Confusion: When authenticating with username and password, a 'security token' is often required, especially from untrusted IP ranges. This token is usually emailed to you after a password reset and must be appended to the password or passed as a separate `security_token` argument.
Fix: Obtain your Salesforce security token (often by resetting your password in Salesforce settings) and provide it either concatenated with your password or as the `security_token` parameter to the `Salesforce` constructor.
gotcha Bulk API 'InvalidBatch' Errors: When using the Bulk API (including Bulk 2.0), 'InvalidBatch' errors often indicate a schema mismatch, incorrect data types, or misrepresented fields in your payload. Error messages can be cryptic.
Fix: Carefully review your data payload against the Salesforce object's schema, ensuring all fields exist, have correct data types, and required fields are present. Validate external IDs for upsert operations.
gotcha Connecting to a Salesforce Sandbox: To connect to a sandbox instance, you must explicitly specify `domain='test'` in the `Salesforce` constructor, in addition to your credentials.
Fix: When initializing `Salesforce`, include `domain='test'` for sandbox environments (e.g., `sf = Salesforce(username=..., password=..., security_token=..., domain='test')`).

Install

pip install simple-salesforce Install stable version

Imports

Salesforce
```
from simple_salesforce import Salesforce
```
The primary class for interacting with the Salesforce API.
SalesforceLogin
```
from simple_salesforce.api import SalesforceLogin
```
A helper function for more granular control over the login process, though 'Salesforce' constructor handles most cases.

Quickstart

This quickstart demonstrates how to authenticate with Salesforce using username, password, and security token, then perform a simple SOQL query, create an account, and delete it. It emphasizes using environment variables for sensitive credentials.

import os
from simple_salesforce import Salesforce

# It's highly recommended to use environment variables for credentials
USERNAME = os.environ.get('SF_USERNAME', 'your_username@example.com')
PASSWORD = os.environ.get('SF_PASSWORD', 'your_password')
SECURITY_TOKEN = os.environ.get('SF_SECURITY_TOKEN', 'your_security_token')

# Optional: for sandbox use domain='test'
# For specific API versions, use sf_version='X.Y'

try:
    sf = Salesforce(
        username=USERNAME,
        password=PASSWORD,
        security_token=SECURITY_TOKEN,
        # domain='test' # Uncomment for sandbox
        # sf_version='59.0' # Uncomment for a specific API version
    )
    print(f"Successfully connected to Salesforce instance: {sf.instance_url}")

    # Example: Query Account records
    query_result = sf.query("SELECT Id, Name FROM Account LIMIT 5")
    print("\nFirst 5 Account Names:")
    for record in query_result['records']:
        print(f"  - {record['Name']} (Id: {record['Id']})")

    # Example: Create a new Account (replace with unique name for testing)
    new_account_name = "Test Account from simple-salesforce_" + str(os.urandom(4).hex())
    new_account = {'Name': new_account_name}
    create_result = sf.Account.create(new_account)
    print(f"\nCreated Account: {new_account_name} with Id: {create_result['id']}")

    # Example: Delete the created Account (cleanup)
    delete_result = sf.Account.delete(create_result['id'])
    print(f"Deleted Account with Id: {create_result['id']}")

except Exception as e:
    print(f"An error occurred: {e}")
    print("Please ensure your SF_USERNAME, SF_PASSWORD, and SF_SECURITY_TOKEN environment variables are set correctly.")

view raw JSON →