simple-salesforce Documentation

Release 0.72.1

Nick Catalano, community contributors

Feb 07, 2019

 Contents

1 Examples 3

2 Record Management 5

3 Queries 7

4 Other Options 9

5 Using Apex 11

6 Additional Features 13

7 API documentation 15
7.1 simple_salesforce package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

8 Release history 27
8.1 v0.72 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
8.2 v0.71 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
8.3 v0.70 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
8.4 v0.69 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
8.5 v0.68.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

9 Authors & License 29

10 Indices and tables 31

Python Module Index 33

i
ii
 simple-salesforce Documentation, Release 0.72.1

Simple Salesforce is a basic Salesforce.com REST API client built for Python 2.6, 2.7, 3.3, 3.4, 3.5 and 3.6. The goal
is to provide a very low-level interface to the REST Resource and APEX API, returning a dictionary of the API JSON
response.
You can find out more regarding the format of the results in the Official Salesforce.com REST API Documentation
Contents:

Contents 1
simple-salesforce Documentation, Release 0.72.1

2 Contents
 CHAPTER 1

Examples

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='na1.salesforce.com', 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='https://na1.salesforce.com', session_id='')

There are also two means of authentication, 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='[email protected]', password='password', security_token=
˓→'token')

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

from simple_salesforce import Salesforce

sf = Salesforce(password='password', username='[email protected]', organizationId=
˓→'OrgId')

If you’d like to enter a sandbox, simply add domain='test' to your Salesforce() call.
For example:

3
simple-salesforce Documentation, Release 0.72.1

from simple_salesforce import Salesforce

sf = Salesforce(username='[email protected]', password='password', security_
˓→token='token', domain='test')

Note that specifying if you want to use a domain is only necessary if you are using the built-in user-
name/password/security token authentication and is used exclusively during the authentication step.
If you’d like to keep track where your API calls are coming from, simply add client_id='My App' to your
Salesforce() call.

from simple_salesforce import Salesforce

sf = Salesforce(username='[email protected]', password='password', security_
˓→token='token', client_id='My App', domain='test')

If you view the API calls in your Salesforce instance by Client Id it will be prefixed with RestForce/, for example
RestForce/My App.
When instantiating a Salesforce object, it’s also possible to include an instance of requests.Session. This is to allow
for specialized session handling not otherwise exposed by simple_salesforce.
For example:

from simple_salesforce import Salesforce

import requests

session = requests.Session()
# manipulate the session instance (optional)
sf = Salesforce(
username='[email protected]', password='password', organizationId='OrgId',
session=session)

4 Chapter 1. Examples
 CHAPTER 2

Record Management

To create a new ‘Contact’ in Salesforce:

sf.Contact.create({'LastName':'Smith','Email':'[email protected]'})

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 get a dictionary with all the information regarding that record, using a custom field that was defined as External
ID:

contact = sf.Contact.get_by_custom_id('My_Custom_ID__c', '22')

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:

sf.Contact.delete('003e0000003GuNXAA0')

To retrieve a list of deleted records between 2013-10-20 to 2013-10-29 (datetimes are required to be in UTC):

import pytz
import datetime
end = datetime.datetime.now(pytz.UTC) # we need to use UTC as salesforce API
˓→requires this!

sf.Contact.deleted(end - datetime.timedelta(days=10), end)

To retrieve a list of updated records between 2014-03-20 to 2014-03-22 (datetimes are required to be in UTC):

5
simple-salesforce Documentation, Release 0.72.1

import pytz
import datetime
end = datetime.datetime.now(pytz.UTC) # we need to use UTC as salesforce API requires
˓→this

sf.Contact.updated(end - datetime.timedelta(days=10), end)

Note that Update, Delete and Upsert actions return the associated Salesforce HTTP Status Code
Use the same format to create any record, including ‘Account’, ‘Opportunity’, and ‘Lead’. Make sure to have all the
required fields for any entry. The Salesforce API has all objects found under ‘Reference -> Standard Objects’ and the
required fields can be found there.

6 Chapter 2. Record Management

 CHAPTER 3

Queries

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("01gD0000002HU6KIAW-2000")
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:

sf.search("FIND {Jones}")

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

sf.quick_search("Jones")

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

7
simple-salesforce Documentation, Release 0.72.1

8 Chapter 3. Queries
 CHAPTER 4

Other Options

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

sf.Contact.upsert('customExtIdField__c/11999',{'LastName': 'Smith','Email':
˓→'[email protected]'})

To retrieve basic metadata use:

sf.Contact.metadata()

To retrieve a description of the object, use:

sf.Contact.describe()

To retrieve a description of the record layout of an object by its record layout unique id, use:

sf.Contact.describe_layout('39wmxcw9r23r492')

To retrieve a list of top level description of instance metadata, user:

sf.describe()

for x in sf.describe()["sobjects"]:
print x["label"]

9
simple-salesforce Documentation, Release 0.72.1

10 Chapter 4. Other Options

 CHAPTER 5

Using Apex

You can also use this library to call custom Apex methods:

payload = {
"activity": [
{"user": "12345", "action": "update page", "time": "2014-04-21T13:00:15Z"}
]
}
result = sf.apexecute('User/Activity', method='POST', data=payload)

This would call the endpoint https://<instance>.salesforce.com/services/apexrest/User/

Activity with data= as the body content encoded with json.dumps
You can read more about Apex on the Force.com Apex Code Developer’s Guide

11
simple-salesforce Documentation, Release 0.72.1

12 Chapter 5. Using Apex

 CHAPTER 6

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 version
and optional domain and returns a tuple 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(
username='[email protected]',
password='password',
security_token='token',
domain='test')

Simply leave off the final domain 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','sessionid','na1.salesforce.com')
contact.create({'LastName':'Smith','Email':'[email protected]'})

To use a proxy server between your client and the SalesForce endpoint, use the proxies argument when creating
SalesForce object. The proxy argument is the same as what requests uses, a map of scheme to proxy URL:
proxies = {
"http": "http://10.10.1.10:3128",
"https": "http://10.10.1.10:1080",
}
SalesForce(instance='na1.salesforce.com', session_id='', proxies=proxies)

13
simple-salesforce Documentation, Release 0.72.1

All results are returned as JSON converted OrderedDict to preserve order of keys from REST responses.

14 Chapter 6. Additional Features

 CHAPTER 7

API documentation

7.1 simple_salesforce package

7.1.1 Subpackages

simple_salesforce.tests package

Submodules

simple_salesforce.tests.test_api module

simple_salesforce.tests.test_login module

simple_salesforce.tests.test_util module

Tests for simple-salesforce utility functions

class simple_salesforce.tests.test_util.TestExceptionHandler(methodName=’runTest’)
Bases: unittest.case.TestCase
Test the exception router
setUp()
Setup the exception router tests
test_expired_session()
Test an expired session (401 code)
test_generic_error_code()
Test an error code that is otherwise not caught
test_malformed_request()
Test a malformed request (400 code)

15
simple-salesforce Documentation, Release 0.72.1

test_multiple_records_returned()
Test multiple records returned (a 300 code)
test_request_refused()
Test a refused request (403 code)
test_resource_not_found()
Test resource not found (404 code)
class simple_salesforce.tests.test_util.TestXMLParser(methodName=’runTest’)
Bases: unittest.case.TestCase
Test the XML parser utility function
test_date_to_iso8601()
Test date conversion
test_returns_valid_value()
Test that when given the correct XML a valid response is returned

Module contents

Simple-Salesforce Tests

7.1.2 Submodules

simple_salesforce.api module

Core classes and exceptions for Simple-Salesforce

class simple_salesforce.api.PerAppUsage(used, total, name)
Bases: tuple
name
Alias for field number 2
total
Alias for field number 1
used
Alias for field number 0
class simple_salesforce.api.SFType(object_name, session_id, sf_instance, sf_version=’38.0’,
proxies=None, session=None)
Bases: object
An interface to a specific type of SObject
__init__(object_name, session_id, sf_instance, sf_version=’38.0’, proxies=None, session=None)
Initialize the instance with the given parameters.
Arguments:
• object_name – the name of the type of SObject this represents, e.g. Lead or Contact
• session_id – the session ID for authenticating to Salesforce
• sf_instance – the domain of the instance of Salesforce to use
• sf_version – the version of the Salesforce API to use
• proxies – the optional map of scheme to proxy server

16 Chapter 7. API documentation

 simple-salesforce Documentation, Release 0.72.1

• session – Custom requests session, created in calling code. This enables the use of requests Ses-
sion features not otherwise exposed by simple_salesforce.
create(data, headers=None)
Creates a new SObject using a POST to . . . /{object_name}/.
Returns a dict decoded from the JSON payload returned by Salesforce.
Arguments:
• data – a dict of the data to create the SObject from. It will be JSON-encoded before being trans-
mitted.
• headers – a dict with additional request headers.
delete(record_id, raw_response=False, headers=None)
Deletes an SObject using a DELETE to . . . /{object_name}/{record_id}.
If raw_response is false (the default), returns the status code returned by Salesforce. Otherwise, return the
requests.Response object.
Arguments:
• record_id – the Id of the SObject to delete
• raw_response – a boolean indicating whether to return the response directly, instead of the sta-
tus code.
• headers – a dict with additional request headers.
deleted(start, end, headers=None)
Gets a list of deleted records
Use the SObject Get Deleted resource to get a list of deleted records for the specified object.
. . . /deleted/?start=2013-05-05T00:00:00+00:00&end=2013-05-10T00:00:00+00:00
• start – start datetime object
• end – end datetime object
• headers – a dict with additional request headers.
describe(headers=None)
Returns the result of a GET to . . . /{object_name}/describe as a dict decoded from the JSON payload
returned by Salesforce.
Arguments:
• headers – a dict with additional request headers.
describe_layout(record_id, headers=None)
Returns the layout of the object
Returns the result of a GET to . . . /{object_name}/describe/layouts/<recordid> as a dict decoded from the
JSON payload returned by Salesforce.
Arguments:
• record_id – the Id of the SObject to get
• headers – a dict with additional request headers.
get(record_id, headers=None)
Returns the result of a GET to . . . /{object_name}/{record_id} as a dict decoded from the JSON payload
returned by Salesforce.
Arguments:

7.1. simple_salesforce package 17

simple-salesforce Documentation, Release 0.72.1

• record_id – the Id of the SObject to get

• headers – a dict with additional request headers.
get_by_custom_id(custom_id_field, custom_id, headers=None)
Return an SFType by custom ID
Returns the result of a GET to . . . /{object_name}/{custom_id_field}/{custom_id} as a dict decoded from
the JSON payload returned by Salesforce.
Arguments:
• custom_id_field – the API name of a custom field that was defined as an External ID
• custom_id - the External ID value of the SObject to get
• headers – a dict with additional request headers.
metadata(headers=None)
Returns the result of a GET to . . . /{object_name}/ as a dict decoded from the JSON payload returned by
Salesforce.
Arguments:
• headers – a dict with additional request headers.
request
Deprecated access to self.session for backwards compatibility
update(record_id, data, raw_response=False, headers=None)
Updates an SObject using a PATCH to . . . /{object_name}/{record_id}.
If raw_response is false (the default), returns the status code returned by Salesforce. Otherwise, return the
requests.Response object.
Arguments:
• record_id – the Id of the SObject to update
• data – a dict of the data to update the SObject from. It will be JSON-encoded before being
transmitted.
• raw_response – a boolean indicating whether to return the response directly, instead of the sta-
tus code.
• headers – a dict with additional request headers.
updated(start, end, headers=None)
Gets a list of updated records
Use the SObject Get Updated resource to get a list of updated (modified or added) records for the specified
object.
. . . /updated/?start=2014-03-20T00:00:00+00:00&end=2014-03-22T00:00:00+00:00

• start – start datetime object

• end – end datetime object
• headers – a dict with additional request headers.

upsert(record_id, data, raw_response=False, headers=None)

Creates or updates an SObject using a PATCH to . . . /{object_name}/{record_id}.
If raw_response is false (the default), returns the status code returned by Salesforce. Otherwise, return the
requests.Response object.

18 Chapter 7. API documentation

 simple-salesforce Documentation, Release 0.72.1

Arguments:
• record_id – an identifier for the SObject as described in the Salesforce documentation
• data – a dict of the data to create or update the SObject from. It will be JSON-encoded before
being transmitted.
• raw_response – a boolean indicating whether to return the response directly, instead of the sta-
tus code.
• headers – a dict with additional request headers.
class simple_salesforce.api.Salesforce(username=None, password=None, secu-
rity_token=None, session_id=None, instance=None,
instance_url=None, organizationId=None, sand-
box=None, version=’38.0’, proxies=None, ses-
sion=None, client_id=None, domain=None)
Bases: object
Salesforce Instance
An instance of Salesforce is a handy way to wrap a Salesforce session for easy use of the Salesforce REST API.

__init__(username=None, password=None, security_token=None, session_id=None, in-

stance=None, instance_url=None, organizationId=None, sandbox=None, version=’38.0’,
proxies=None, session=None, client_id=None, domain=None)
Initialize the instance with the given parameters.
Available kwargs
Password Authentication:
• username – the Salesforce username to use for authentication
• password – the password for the username
• security_token – the security token for the username
• sandbox – DEPRECATED: Use domain instead.
• domain – The domain to using for connecting to Salesforce. Use common domains, such as ‘lo-
gin’ or ‘test’, or Salesforce My domain. If not used, will default to ‘login’.
Direct Session and Instance Access:
• session_id – Access token for this session
Then either * instance – Domain of your Salesforce instance, i.e.
na1.salesforce.com
OR * instance_url – Full URL of your instance i.e.
‘https://na1.salesforce.com
Universal Kwargs: * version – the version of the Salesforce API to use, for example
29.0

• proxies – the optional map of scheme to proxy server

• session – Custom requests session, created in calling code. This enables the use of requests Ses-
sion features not otherwise exposed by simple_salesforce.

7.1. simple_salesforce package 19

simple-salesforce Documentation, Release 0.72.1

apexecute(action, method=’GET’, data=None, **kwargs)

Makes an HTTP request to an APEX REST endpoint
Arguments:
• action – The REST endpoint for the request.
• method – HTTP method for the request (default GET)
• data – A dict of parameters to send in a POST / PUT request
• kwargs – Additional kwargs to pass to requests.request
describe()
Describes all available objects
limits(**kwargs)
Return the result of a Salesforce request to list Organization limits.
static parse_api_usage(sforce_limit_info)
parse API usage and limits out of the Sforce-Limit-Info header
Arguments:
• sforce_limit_info: The value of response header ‘Sforce-Limit-Info’ Example 1: ‘api-
usage=18/5000’ Example 2: ‘api-usage=25/5000;
per-app-api-usage=17/250(appName=sample-connected-app)’
query(query, include_deleted=False, **kwargs)
Return the result of a Salesforce SOQL query as a dict decoded from the Salesforce response JSON pay-
load.
Arguments:
• query – the SOQL query to send to Salesforce, e.g. SELECT Id FROM Lead WHERE Email =
“[email protected]”
• include_deleted – True if deleted records should be included
query_all(query, include_deleted=False, **kwargs)
Returns the full set of results for the query. This is a convenience wrapper around query(. . . ) and
query_more(. . . ).
The returned dict is the decoded JSON payload from the final call to Salesforce, but with the totalSize field
representing the full number of results retrieved and the records list representing the full list of records
retrieved.
Arguments
• query – the SOQL query to send to Salesforce, e.g. SELECT Id FROM Lead WHERE Email =
“[email protected]”
• include_deleted – True if the query should include deleted records.
query_more(next_records_identifier, identifier_is_url=False, include_deleted=False, **kwargs)
Retrieves more results from a query that returned more results than the batch maximum. Returns a dict
decoded from the Salesforce response JSON payload.
Arguments:
• next_records_identifier – either the Id of the next Salesforce object in the result, or a URL to the
next record in the result.
• identifier_is_url – True if next_records_identifier should be treated as a URL, False if
next_records_identifier should be treated as an Id.

20 Chapter 7. API documentation

 simple-salesforce Documentation, Release 0.72.1

• include_deleted – True if the next_records_identifier refers to a query that includes deleted

records. Only used if identifier_is_url is False
quick_search(search)
Returns the result of a Salesforce search as a dict decoded from the Salesforce response JSON payload.
Arguments:
• search – the non-SOSL search string, e.g. Waldo. This search string will be wrapped to read
FIND {Waldo} before being sent to Salesforce
request
Deprecated access to self.session for backwards compatibility
restful(path, params=None, method=’GET’, **kwargs)
Allows you to make a direct REST call if you know the path
Arguments:
• path: The path of the request Example: sobjects/User/ABC123/password’
• params: dict of parameters to pass to the path
• method: HTTP request method, default GET
• other arguments supported by requests.request (e.g. json, timeout)
search(search)
Returns the result of a Salesforce search as a dict decoded from the Salesforce response JSON payload.
Arguments:
• search – the fully formatted SOSL search string, e.g. FIND {Waldo}
setPassword(user, password)
Sets the password of a user
salesforce dev documentation link: https://www.salesforce.com/us/developer/docs/api_rest/Content/
dome_sobject_user_password.htm
Arguments:
• user: the userID of the user to set
• password: the new password
set_password(user, password)
Sets the password of a user
salesforce dev documentation link: https://www.salesforce.com/us/developer/docs/api_rest/Content/
dome_sobject_user_password.htm
Arguments:
• user: the userID of the user to set
• password: the new password
class simple_salesforce.api.SalesforceAPI(username, password, security_token, sand-
box=False, sf_version=’27.0’)
Bases: simple_salesforce.api.Salesforce
Deprecated SalesforceAPI Instance
This class implements the Username/Password Authentication Mechanism using Arguments It has since been
surpassed by the ‘Salesforce’ class, which relies on kwargs

7.1. simple_salesforce package 21

simple-salesforce Documentation, Release 0.72.1

__init__(username, password, security_token, sandbox=False, sf_version=’27.0’)

Initialize the instance with the given parameters.
Arguments:
• username – the Salesforce username to use for authentication
• password – the password for the username
• security_token – the security token for the username
• sandbox – True if you want to login to test.salesforce.com, False if you want to login to lo-
gin.salesforce.com.
• sf_version – the version of the Salesforce API to use, for example “27.0”
class simple_salesforce.api.Usage(used, total)
Bases: tuple
total
Alias for field number 1
used
Alias for field number 0

simple_salesforce.bulk module

Classes for interacting with Salesforce Bulk API

class simple_salesforce.bulk.SFBulkHandler(session_id, bulk_url, proxies=None, ses-
sion=None)
Bases: object
Bulk API request handler Intermediate class which allows us to use commands,
such as ‘sf.bulk.Contacts.insert(. . . )’
This is really just a middle layer, whose sole purpose is to allow the above syntax
__init__(session_id, bulk_url, proxies=None, session=None)
Initialize the instance with the given parameters.
Arguments:
• session_id – the session ID for authenticating to Salesforce
• bulk_url – API endpoint set in Salesforce instance
• proxies – the optional map of scheme to proxy server
• session – Custom requests session, created in calling code. This enables the use of requests Ses-
sion features not otherwise exposed by simple_salesforce.
class simple_salesforce.bulk.SFBulkType(object_name, bulk_url, headers, session)
Bases: object
Interface to Bulk/Async API functions
__init__(object_name, bulk_url, headers, session)
Initialize the instance with the given parameters.
Arguments:
• object_name – the name of the type of SObject this represents, e.g. Lead or Contact
• bulk_url – API endpoint set in Salesforce instance

22 Chapter 7. API documentation

 simple-salesforce Documentation, Release 0.72.1

• headers – bulk API headers

• session – Custom requests session, created in calling code. This enables the use of requests Ses-
sion features not otherwise exposed by simple_salesforce.
delete(data)
soft delete records
hard_delete(data)
hard delete records
insert(data)
insert/create records
query(data)
bulk query
update(data)
update records
upsert(data, external_id_field)
upsert records based on a unique identifier

simple_salesforce.exceptions module

All exceptions for Simple Salesforce

exception simple_salesforce.exceptions.SalesforceAuthenticationFailed(code,
mes-
sage)
Bases: simple_salesforce.exceptions.SalesforceError
Thrown to indicate that authentication with Salesforce failed.
__init__(code, message)
Initialize the SalesforceError exception
SalesforceError is the base class of exceptions in simple-salesforce
Args: url: Salesforce URL that was called status: Status code of the error response resource_name: Name
of the Salesforce resource being queried content: content of the response
exception simple_salesforce.exceptions.SalesforceError(url, status, resource_name,
content)
Bases: exceptions.Exception
Base Salesforce API exception
__init__(url, status, resource_name, content)
Initialize the SalesforceError exception
SalesforceError is the base class of exceptions in simple-salesforce
Args: url: Salesforce URL that was called status: Status code of the error response resource_name: Name
of the Salesforce resource being queried content: content of the response
message = u'Unknown error occurred for {url}. Response content: {content}'
exception simple_salesforce.exceptions.SalesforceExpiredSession(url, status, re-
source_name,
content)
Bases: simple_salesforce.exceptions.SalesforceError

7.1. simple_salesforce package 23

simple-salesforce Documentation, Release 0.72.1

Error Code: 401 The session ID or OAuth token used has expired or is invalid. The response body contains the
message and errorCode.
message = u'Expired session for {url}. Response content: {content}'
exception simple_salesforce.exceptions.SalesforceGeneralError(url, status, re-
source_name,
content)
Bases: simple_salesforce.exceptions.SalesforceError
A non-specific Salesforce error.
message = u'Error Code {status}. Response content: {content}'
exception simple_salesforce.exceptions.SalesforceMalformedRequest(url, sta-
tus, re-
source_name,
content)
Bases: simple_salesforce.exceptions.SalesforceError
Error Code: 400 The request couldn’t be understood, usually because the JSON or XML body contains an error.

message = u'Malformed request {url}. Response content: {content}'

exception simple_salesforce.exceptions.SalesforceMoreThanOneRecord(url,
status, re-
source_name,
content)
Bases: simple_salesforce.exceptions.SalesforceError
Error Code: 300 The value returned when an external ID exists in more than one record. The response body
contains the list of matching records.
message = u'More than one record for {url}. Response content: {content}'
exception simple_salesforce.exceptions.SalesforceRefusedRequest(url, status, re-
source_name,
content)
Bases: simple_salesforce.exceptions.SalesforceError
Error Code: 403 The request has been refused. Verify that the logged-in user has appropriate permissions.
message = u'Request refused for {url}. Response content: {content}'
exception simple_salesforce.exceptions.SalesforceResourceNotFound(url, sta-
tus, re-
source_name,
content)
Bases: simple_salesforce.exceptions.SalesforceError
Error Code: 404 The requested resource couldn’t be found. Check the URI for errors, and verify that there are
no sharing issues.
message = u'Resource {name} Not Found. Response content: {content}'

simple_salesforce.login module

Login classes and functions for Simple-Salesforce

Heavily Modified from RestForce 1.0.0

24 Chapter 7. API documentation

 simple-salesforce Documentation, Release 0.72.1

simple_salesforce.login.SalesforceLogin(username=None, password=None, secu-

rity_token=None, organizationId=None, sand-
box=None, sf_version=’38.0’, proxies=None,
session=None, client_id=None, domain=None)
Return a tuple of (session_id, sf_instance) where session_id is the session ID to use for authentication to Sales-
force and sf_instance is the domain of the instance of Salesforce to use for the session.
Arguments:
• username – the Salesforce username to use for authentication
• password – the password for the username
• security_token – the security token for the username
• organizationId – the ID of your organization NOTE: security_token an organizationId are mutually ex-
clusive
• sandbox – DEPRECATED: Use domain instead.
• sf_version – the version of the Salesforce API to use, for example “27.0”
• proxies – the optional map of scheme to proxy server
• session – Custom requests session, created in calling code. This enables the use of requets Session fea-
tures not otherwise exposed by simple_salesforce.
• client_id – the ID of this client
• domain – The domain to using for connecting to Salesforce. Use common domains, such as ‘login’ or
‘test’, or Salesforce My domain. If not used, will default to ‘login’.

simple_salesforce.util module

Utility functions for simple-salesforce

simple_salesforce.util.call_salesforce(url, method, session, headers, **kwargs)
Utility method for performing HTTP call to Salesforce.
Returns a requests.result object.
simple_salesforce.util.date_to_iso8601(date)
Returns an ISO8601 string from a date
simple_salesforce.util.exception_handler(result, name=”)
Exception router. Determines which error to raise for bad results
simple_salesforce.util.getUniqueElementValueFromXmlString(xmlString, element-
Name)
Extracts an element value from an XML string.
For example, invoking getUniqueElementValueFromXmlString(
‘<?xml version=”1.0” encoding=”UTF-8”?><foo>bar</foo>’, ‘foo’)
should return the value ‘bar’.

7.1.3 Module contents

Simple-Salesforce Package

7.1. simple_salesforce package 25

simple-salesforce Documentation, Release 0.72.1

26 Chapter 7. API documentation

 CHAPTER 8

Release history

8.1 v0.72

8.1.1 Bugs

• [134] query_all changed to be non-recursive due to recursion limit being hit for large result sets.

8.2 v0.71

8.2.1 Features

• [131] Added the ability to pass custom headers through to requests

8.3 v0.70

8.3.1 Features

• [98] Requests session objects are now shared between SFType instances and the parent Salesforce object

8.4 v0.69

8.4.1 Features

• [103] Require requests[secure] to allow for system openssl, which will allow for TLSv1.2 in Python < 2.7.9
assuming system openssl is newer than Python’s.

27
simple-salesforce Documentation, Release 0.72.1

8.4.2 Other

• Replaced httpretty with responses for unit tests due to SSL-related errors in httpretty.

8.5 v0.68.2

8.5.1 Other

• [85] Added tox support, updated travis-ci config

• Added CHANGES file
• [97] _call_salesforce is now used consistently across API

28 Chapter 8. Release history

 CHAPTER 9

Authors & License

This package is released under an open source Apache 2.0 license. Simple-Salesforce was originally written by Nick
Catalano but most newer features and bugfixes come from community contributors. Pull requests submitted to the
GitHub Repo are highly encouraged!
Authentication mechanisms were adapted from Dave Wingate’s RestForce and licensed under a MIT license
The latest build status can be found at Travis CI

29
simple-salesforce Documentation, Release 0.72.1

30 Chapter 9. Authors & License

 CHAPTER 10

Indices and tables

• genindex
• modindex
• search

31
simple-salesforce Documentation, Release 0.72.1

32 Chapter 10. Indices and tables

 Python Module Index

s
simple_salesforce, 25
simple_salesforce.api, 16
simple_salesforce.bulk, 22
simple_salesforce.exceptions, 23
simple_salesforce.login, 24
simple_salesforce.tests, 16
simple_salesforce.tests.test_util, 15
simple_salesforce.util, 25

33
simple-salesforce Documentation, Release 0.72.1

34 Python Module Index

 Index

Symbols get_by_custom_id() (simple_salesforce.api.SFType

__init__() (simple_salesforce.api.SFType method), 16 method), 18
__init__() (simple_salesforce.api.Salesforce method), 19 getUniqueElementValueFromXmlString() (in module
__init__() (simple_salesforce.api.SalesforceAPI method), simple_salesforce.util), 25
21
__init__() (simple_salesforce.bulk.SFBulkHandler H
method), 22 hard_delete() (simple_salesforce.bulk.SFBulkType
__init__() (simple_salesforce.bulk.SFBulkType method), method), 23
22
I
__init__() (simple_salesforce.exceptions.SalesforceAuthenticationFailed
method), 23 insert() (simple_salesforce.bulk.SFBulkType method), 23
__init__() (simple_salesforce.exceptions.SalesforceError
method), 23 L
limits() (simple_salesforce.api.Salesforce method), 20
A
apexecute() (simple_salesforce.api.Salesforce method), M
19 message (simple_salesforce.exceptions.SalesforceError
attribute), 23
C message (simple_salesforce.exceptions.SalesforceExpiredSession
call_salesforce() (in module simple_salesforce.util), 25 attribute), 24
create() (simple_salesforce.api.SFType method), 17 message (simple_salesforce.exceptions.SalesforceGeneralError
attribute), 24
D message (simple_salesforce.exceptions.SalesforceMalformedRequest
date_to_iso8601() (in module simple_salesforce.util), 25 attribute), 24
delete() (simple_salesforce.api.SFType method), 17 message (simple_salesforce.exceptions.SalesforceMoreThanOneRecord
delete() (simple_salesforce.bulk.SFBulkType method), attribute), 24
23 message (simple_salesforce.exceptions.SalesforceRefusedRequest
deleted() (simple_salesforce.api.SFType method), 17 attribute), 24
describe() (simple_salesforce.api.Salesforce method), 20 message (simple_salesforce.exceptions.SalesforceResourceNotFound
describe() (simple_salesforce.api.SFType method), 17 attribute), 24
describe_layout() (simple_salesforce.api.SFType metadata() (simple_salesforce.api.SFType method), 18
method), 17
N
E name (simple_salesforce.api.PerAppUsage attribute), 16
exception_handler() (in module simple_salesforce.util),
25 P
parse_api_usage() (simple_salesforce.api.Salesforce
G static method), 20
get() (simple_salesforce.api.SFType method), 17 PerAppUsage (class in simple_salesforce.api), 16

35
simple-salesforce Documentation, Release 0.72.1

Q test_generic_error_code() (sim-
query() (simple_salesforce.api.Salesforce method), 20 ple_salesforce.tests.test_util.TestExceptionHandler
query() (simple_salesforce.bulk.SFBulkType method), 23 method), 15
query_all() (simple_salesforce.api.Salesforce method), test_malformed_request() (sim-
20 ple_salesforce.tests.test_util.TestExceptionHandler
query_more() (simple_salesforce.api.Salesforce method), method), 15
20 test_multiple_records_returned() (sim-
quick_search() (simple_salesforce.api.Salesforce ple_salesforce.tests.test_util.TestExceptionHandler
method), 21 method), 15
test_request_refused() (sim-
R ple_salesforce.tests.test_util.TestExceptionHandler
request (simple_salesforce.api.Salesforce attribute), 21 method), 16
request (simple_salesforce.api.SFType attribute), 18 test_resource_not_found() (sim-
restful() (simple_salesforce.api.Salesforce method), 21 ple_salesforce.tests.test_util.TestExceptionHandler
method), 16
S test_returns_valid_value() (sim-
Salesforce (class in simple_salesforce.api), 19 ple_salesforce.tests.test_util.TestXMLParser
SalesforceAPI (class in simple_salesforce.api), 21 method), 16
SalesforceAuthenticationFailed, 23 TestExceptionHandler (class in sim-
SalesforceError, 23 ple_salesforce.tests.test_util), 15
SalesforceExpiredSession, 23 TestXMLParser (class in sim-
SalesforceGeneralError, 24 ple_salesforce.tests.test_util), 16
SalesforceLogin() (in module simple_salesforce.login), total (simple_salesforce.api.PerAppUsage attribute), 16
24 total (simple_salesforce.api.Usage attribute), 22
SalesforceMalformedRequest, 24
SalesforceMoreThanOneRecord, 24 U
SalesforceRefusedRequest, 24 update() (simple_salesforce.api.SFType method), 18
SalesforceResourceNotFound, 24 update() (simple_salesforce.bulk.SFBulkType method),
search() (simple_salesforce.api.Salesforce method), 21 23
set_password() (simple_salesforce.api.Salesforce updated() (simple_salesforce.api.SFType method), 18
method), 21 upsert() (simple_salesforce.api.SFType method), 18
setPassword() (simple_salesforce.api.Salesforce method), upsert() (simple_salesforce.bulk.SFBulkType method),
21 23
Usage (class in simple_salesforce.api), 22
setUp() (simple_salesforce.tests.test_util.TestExceptionHandler
method), 15 used (simple_salesforce.api.PerAppUsage attribute), 16
SFBulkHandler (class in simple_salesforce.bulk), 22 used (simple_salesforce.api.Usage attribute), 22
SFBulkType (class in simple_salesforce.bulk), 22
SFType (class in simple_salesforce.api), 16
simple_salesforce (module), 25
simple_salesforce.api (module), 16
simple_salesforce.bulk (module), 22
simple_salesforce.exceptions (module), 23
simple_salesforce.login (module), 24
simple_salesforce.tests (module), 16
simple_salesforce.tests.test_util (module), 15
simple_salesforce.util (module), 25

T
test_date_to_iso8601() (sim-
ple_salesforce.tests.test_util.TestXMLParser
method), 16
test_expired_session() (sim-
ple_salesforce.tests.test_util.TestExceptionHandler
method), 15

36 Index