simple-salesforce
A basic Salesforce.com REST API client.
Downloads: 0 (30 days)
Description
*****************
Simple Salesforce
*****************
.. image:: https://github.com/simple-salesforce/simple-salesforce/actions/workflows/test.yml/badge.svg
:target: https://github.com/simple-salesforce/simple-salesforce/actions
.. image:: https://readthedocs.org/projects/simple-salesforce/badge/?version=latest
:target: http://simple-salesforce.readthedocs.io/en/latest/?badge=latest
:alt: Documentation Status
Simple Salesforce is a basic Salesforce.com REST API client built for Python 3.9, 3.10, 3.11, 3.12, and 3.13. 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`_
.. _Official Salesforce.com REST API Documentation: http://www.salesforce.com/us/developer/docs/api_rest/index.htm
Documentation
=============
.. _Official Simple Salesforce documentation: http://simple-salesforce.readthedocs.io/en/latest/
`Official Simple Salesforce documentation`_
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:
.. code-block:: python
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 scheme, as is included in the OAuth2 request process), you can pass that in instead using ``instance_url``:
.. code-block:: python
from simple_salesforce import Salesforce
sf = Salesforce(instance_url='https://na1.salesforce.com', session_id='')
There are also four means of authentication, one that uses username, password and security token; one that uses IP filtering, username, password and organizationId, one that uses a private key to sign a JWT, and one for connected apps that uses username, password, consumer key, and consumer secret;
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 or go to profile -> settings -> Reset My Security Token):
.. code-block:: python
from simple_salesforce import Salesforce
sf = Salesforce(username='myemail@example.com', password='password', security_token='token')
To login using IP-whitelist Organization ID method, simply use your Salesforce username, password and organizationId:
.. code-block:: python
from simple_salesforce import Salesforce
sf = Salesforce(password='password', username='myemail@example.com', organizationId='OrgId')
To login using the JWT method, use your Salesforce username, consumer key from your app, and private key (`How To <https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_auth_jwt_flow.htm#sfdx_dev_auth_jwt_flow>`_):
.. code-block:: python
from simple_salesforce import Salesforce
sf = Salesforce(username='myemail@example.com', consumer_key='XYZ', privatekey_file='filename.key')
To login using a connected app, simply include the Salesforce method and pass in your Salesforce username, password, consumer_key and consumer_secret (the consumer key and consumer secret are provided when you setup your connected app):
.. code-block:: python
from simple_salesforce import Salesforce
sf = Salesforce(username='myemail@example.com', password='password', consumer_key='consumer_key', consumer_secret='consumer_secret')
Connected apps may also be configured with a ``client_id`` and ``client_secret`` (renamed here as ``consumer_key`` and ``consumer_secret``), and a ``domain``.
The ``domain`` for the url ``https://organization.my.salesforce.com`` would be ``organization.my``
.. code-block:: python
from simple_salesforce import Salesforce
sf = Salesforce(consumer_key='sfdc_client_id', consumer_secret='sfdc_client_secret', domain='organization.my')
If you'd like to enter a sandbox, simply add ``domain='test'`` to your ``Salesforce()`` call.
For example:
.. code-block:: python
from simple_salesforce import Salesforce
sf = Salesforce(username='myemail@example.com.sandbox', 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 username/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.
.. code-block:: python
from simple_salesforce import Salesforce
sf = Salesforce(username='myemail@example.com.sandbox', 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 ``simple-salesforce/``, for example ``simple-salesforce/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:
.. code-block:: python
from simple_salesforce import Salesforce
import requests
session = requests.Session()
# manipulate the session instance (optional)
sf = Salesforce(
username='user@example.com', password='password', organizationId='OrgId',
session=session)
Record Management
--------------------------
To create a new 'Contact' in Salesforce:
.. code-block:: python
sf.Contact.create({'LastName':'Smith','Email':'example@example.com'})
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:
.. code-block:: python
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:
.. code-block:: python
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:
.. code-block:: python
sf.Contact.update('003e0000003GuNXAA0',{'LastName': 'Jones', 'FirstName': 'John'})
To delete the contact:
.. code-block:: python
sf.Contact.delete('003e0000003GuNXAA0')
To retrieve a list of Contact records deleted over the past 10 days (datetimes are required to be in UTC):
.. code-block:: python
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 Contact records updated over the past 10 days (datetimes are required to be in UTC):
.. code-block:: python
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.
.. _Salesforce HTTP Status Code: http://www.salesforce.com/us/developer/docs/api_rest/Content/errorcodes.htm
.. _Salesforce API: https://www.salesforce.com/developer/docs/api/
Queries
--------------------------
It's also possible to write select queries in Salesforce Object Query Language (SOQL) and search queries in Salesforce Object Search Language (SOSL).
All SOQL queries are supported and parent/child relationships can be queried using the standard format (Parent__r.FieldName). SOQL queries are done via:
.. code-block:: python
sf.query("SELECT Id, Email, ParentAccount.Name 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)
.. code-block:: python
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
.. code-block:: python
sf.query_all("SELECT Id, Email FROM Contact WHERE LastName = 'Jones'")
While ``query_all`` materializes the whole result into a Python list, ``query_all_iter`` returns an iterator, which allows you to lazily process each element separately
.. code-block:: python
data = sf.query_all_iter("SELECT Id, Email FROM Contact WHERE LastName = 'Jones'")
for row in data:
process(row)
Values used in SOQL queries can be quoted and escaped using ``format_soql``:
.. code-block:: python
sf.query(format_soql("SELECT Id, Email FROM Contact WHERE LastName = {}", "Jones"))
sf.query(format_soql("SELECT Id, Email FROM Contact WHERE LastName = {last_name}", last_name="Jones"))
sf.query(format_soql("SELECT Id, Email FROM Contact WHERE LastName IN {names}", names=["Smith", "Jones"]))
To skip quoting and escaping for one value while still using the format string, use ``:literal``:
.. code-block:: python
sf.query(format_soql("SELECT Id, Email FROM Contact WHERE Income > {:literal}", "USD100"))
To escape a substring used in a LIKE expression while being able to use % around it, use ``:like``:
.. code-block:: python
sf.query(format_soql("SELECT Id, Email FROM Contact WHERE Name LIKE '{:like}%'", "J