Registry / crm-productivity / simple-salesforce

simple-salesforce

JSON →
library1.12.10pypypi✓ verified 24d ago

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.

pip install simple-salesforce
INSTALL
IMPORT
SIG · SIMPLE-SALESFORCE
S
simple-salesforce
crm-productivitypythonv1.12.10
Install
5.2s avg
Import
711ms
Disk
55MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.12.10 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.754s · 55.4MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 5.2s · import 0.668s · 56MB
55MB installed
● package 55MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

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.

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.")
Debug
Known issues
breakingBreaking 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.
affects: >=1.0.0
gotchaSecurity 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.
affects: All versions
gotchaBulk 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.
affects: All versions
gotchaConnecting 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')`).
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'simple_salesforce'
This error occurs when the 'simple-salesforce' library is not installed, or the import statement uses an incorrect module name (e.g., 'salesforce' instead of 'simple_salesforce').
fix
Ensure the library is installed using `pip install simple-salesforce` and imported as `from simple_salesforce import Salesforce`.
SalesforceAuthenticationFailed: invalid_grant: authentication failure
This error means the provided Salesforce username, password, or security token is incorrect, or IP restrictions are preventing access.
fix
Verify all credentials are correct, ensure the security token is appended directly to the password if required, and check for any IP restrictions or login hour policies on the Salesforce side.
SalesforceError: [StatusCode: 404] NOT_FOUND
This indicates that the Salesforce object, field, or record you are trying to access or manipulate does not exist, or your user profile lacks permissions to see it.
fix
Double-check the API name of the object/field/record ID for typos, and ensure the authenticated user has appropriate read/write permissions for that resource in Salesforce.
SalesforceError: [StatusCode: 500] INVALID_SESSION_ID: Session ID not found, please login again.
The current Salesforce session has expired due to inactivity or invalidation, requiring re-authentication to obtain a new valid session.
fix
Re-establish the Salesforce connection by re-instantiating the `Salesforce` object with your credentials to generate a fresh, valid session ID.
AttributeError: 'Salesforce' object has no attribute 'query_all'
This error typically means you've misspelled a method name or an object's API name, or are attempting to access a non-existent attribute of the `Salesforce` connection object.
fix
Correct the method or object name to match `simple-salesforce`'s conventions or Salesforce's API names (e.g., `sf.query_all()` for queries or `sf.Contact.get()` for object methods).
Upgrade
Version history
1.12.10latest on PyPI · released Jul 8, 2026
Audit
Dependencies
requestsrequiredUsed for all HTTP communication with the Salesforce API.
python-dotenvoptionalCommonly used in quickstart examples for managing credentials securely via environment variables.
Agent activity
44 hits · last 30 days
node
36
OpenAI (training)
1
Resources