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
  • session – Custom requests session, created in calling code. This
    enables the use of requests Session 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 transmitted.
  • 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 status 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:

  • 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 status 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.

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 status code.
  • headers – a dict with additional request headers.
class simple_salesforce.api.Salesforce(username=None, password=None, security_token=None, session_id=None, instance=None, instance_url=None, organizationId=None, sandbox=False, version='38.0', proxies=None, session=None, client_id=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, instance=None, instance_url=None, organizationId=None, sandbox=False, version='38.0', proxies=None, session=None, client_id=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 – True if you want to login to test.salesforce.com, False
    if you want to login to login.salesforce.com.

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.

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 Session features not otherwise exposed by simple_salesforce.
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

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, **kwargs)

Return the result of a Salesforce SOQL query as a dict decoded from the Salesforce response JSON payload.

Arguments:

  • query – the SOQL query to send to Salesforce, e.g.
    SELECT Id FROM Lead WHERE Email = “waldo@somewhere.com
query_all(query, **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 = “waldo@somewhere.com
query_more(next_records_identifier, identifier_is_url=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.

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, method='GET')

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
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, sandbox=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

__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 login.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