Skip to main content
Help us improve Python packaging – donate today!

Simple Salesforce is a basic REST API client. The goal is to provide a very low-level interface to the API, returning a dictionary of the API JSON response.

Project Description

Simple Salesforce is a basic REST API client. The goal is to provide a very low-level interface to the API, returning a dictionary of the API JSON response.

You can find out more regarding the format of the results in the Official REST API Documentation


There are two ways to gain access to Salesforce

The first is to simply pass the domain of your Salesforce instance and an access token straight to Salesforce()

For example:

from simple_salesforce import Salesforce
sf = Salesforce(instance='', session_id='')

If you have the full URL of your instance (perhaps including the schema, as is included in the OAuth2 request process), you can pass that in instead using instance_url:

from simple_salesforce import Salesforce
sf = Salesforce(instance_url='', session_id='')

There are also two means of autentication, one that uses username, password and security token and the other that uses IP filtering, username, password and organizationId

To login using the security token method, simply include the Salesforce method and pass in your Salesforce username, password and token (this is usually provided when you change your password):

from simple_salesforce import Salesforce
sf = Salesforce(username='', password='password', security_token='token')

To login using IP-whitelist Organization ID method, simply use your Salesforce username, password and organizationId:

from simple_salesforce import Salesforce
sf = Salesforce(password='password', username='', organizationId='OrgId')

If you’d like to enter a sandbox, simply add sandbox=True to your Salesforce() call.

For example:

from simple_salesforce import Salesforce
sf = Salesforce(username='', password='password', security_token='token', sandbox=True)

Note that specifying if you want to use a sandbox is only necessary if you are using the built-in username/password/security token authentication and is used exclusively during the authentication step.

Record Management

To create a new ‘Contact’ in Salesforce:


This will return a dictionary such as {u'errors': [], u'id': u'003e0000003GuNXAA0', u'success': True}

To get a dictionary with all the information regarding that record, use:

contact = sf.Contact.get('003e0000003GuNXAA0')

To change that contact’s last name from ‘Smith’ to ‘Jones’ and add a first name of ‘John’ use:

sf.Contact.update('003e0000003GuNXAA0',{'LastName': 'Jones', 'FirstName': 'John'})

To delete the contact:


To retrieve a list of deleted contacts between 2013-10-20 to 2013-10-29:

import urllib
sf.Contact.deleted(urllib.quote('2013-10-20T00:00:00+00:00'), urllib.quote('2013-10-29T00:00:00+00:00'))

Note that Update, Delete and Upsert actions return the associated Salesforce HTTP Status Code


It’s also possible to write select queries in Salesforce Object Query Language (SOQL) and search queries in Salesforce Object Search Language (SOSL).

SOQL queries are done via

sf.query("SELECT Id, Email FROM Contact WHERE LastName = 'Jones'")

If, due to an especially large result, Salesforce adds a nextRecordsUrl to your query result, such as "nextRecordsUrl" : "/services/data/v26.0/query/01gD0000002HU6KIAW-2000", you can pull the additional results with either the ID or the full URL (if using the full URL, you must pass ‘True’ as your second argument)

sf.query_more("/services/data/v26.0/query/01gD0000002HU6KIAW-2000", True)

As a convenience, to retrieve all of the results in a single local method call use

sf.query_all("SELECT Id, Email FROM Contact WHERE LastName = 'Jones'")

SOSL queries are done via:"FIND {Jones}")

There is also ‘Quick Search’, which inserts your query inside the {} in the SOSL syntax. Be careful, there is no escaping!


Search and Quick Search return None if there are no records, otherwise they return a dictionary of search results.

More details about syntax is available on the Salesforce Query Language Documentation Developer Website

Other Options

To insert or update (upsert) a record using an external ID, use:

sf.Contact.upsert('customExtIdField__c/11999',{'LastName': 'Smith','Email': ''})

To retrieve basic metadata use:


To retrieve a description of the object, use:


Additional Features

There are a few helper classes that are used internally and available to you.

Included in them are SalesforceLogin, which takes in a username, password, security token, optional boolean sandbox indicator and optional version and returns a touple of (session_id, sf_instance) where session_id is the session ID to use for authentication to Salesforce and sf_instance is the domain of the instance of Salesforce to use for the session.

For example, to use SalesforceLogin for a sandbox account you’d use:

from simple_salesforce import SalesforceLogin
session_id, instance = SalesforceLogin('', 'password', 'token', True)

Simply leave off the final True if you do not wish to use a sandbox.

Also exposed is the SFType class, which is used internally by the __getattr__() method in the Salesforce() class and represents a specific SObject type. SFType requires object_name (i.e. Contact), session_id (an authentication ID), sf_instance (hostname of your Salesforce instance), and an optional sf_version

To add a Contact using the default version of the API you’d use:

from simple_salesforce import SFType
contact = SFType('Contact','sesssionid','')

Authors & License

This plugin was originally built in-house by the team at New Organizing Institute led by Nick Catalano and is released under an open source Apache 2.0 license. Contributions are welcome and can be submitted via a pull request on the official GitHub Repo.

Authentication mechanisms were adapted from Dave Wingate’s RestForce and licensed under a MIT license

Release history Release notifications

History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


This version
History Node


History Node


History Node


History Node


History Node


History Node


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
simple-salesforce-0.6.tar.gz (12.1 kB) Copy SHA256 hash SHA256 Source None Nov 11, 2013

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging CloudAMQP CloudAMQP RabbitMQ AWS AWS Cloud computing Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page