Client API #

get_my_news_feed(site_id: str | None = None)[source]#

This method retrieves the news feed for the user calling the function. (Reference)

Parameters:: site_id (str, None) – The ID of an Experience Cloud site against which to query (optional)
Returns:: The news feed data
Raises:: RuntimeError

get_user_news_feed(user_id: str, site_id: str | None = None)[source]#

This method retrieves another user’s news feed. (Reference)

Parameters:

user_id (str) – The ID of the user whose feed you wish to return
site_id (str, None) – The ID of an Experience Cloud site against which to query (optional)

Returns:

The news feed data

Raises:

RuntimeError, salespyforce.errors.exceptions.MissingRequiredDataError

post_comment(feed_element_id: str, message_text: str | None = None, message_segments: list | None = None, site_id: str | None = None, created_by_id: str | None = None)[source]#

This method publishes a comment on a Chatter feed item. (Reference)

Parameters:

feed_element_id (str) – The ID of the feed element on which to post the comment
message_text (str, None) – Plaintext to be used as the message body
message_segments (list, None) – Collection of message segments to use instead of a plaintext message
site_id (str, None) – The ID of an Experience Cloud site against which to query (optional)
created_by_id (str, None) – The ID of the user to impersonate (Experimental)

Returns:

The response of the POST request

Raises:

post_feed_item(subject_id: str, message_text: str | None = None, message_segments: list | None = None, site_id: str | None = None, created_by_id: str | None = None)[source]#

This method publishes a new Chatter feed item. (Reference)

Parameters:

subject_id (str) – The Subject ID against which to publish the feed item (e.g. 0F9B000000000W2)
message_text (str, None) – Plaintext to be used as the message body
message_segments (list, None) – Collection of message segments to use instead of a plaintext message
site_id (str, None) – The ID of an Experience Cloud site against which to query (optional)
created_by_id (str, None) – The ID of the user to impersonate (Experimental)

Returns:

The response of the POST request

Raises:

RuntimeError, salespyforce.errors.exceptions.MissingRequiredDataError

class Knowledge(sfdc_object: Salesforce)[source]#

Bases: object

This class includes methods associated with Salesforce Knowledge.

archive_article(article_id: str)[source]#

This function archives a published knowledge article. (Reference)

Added in version 1.3.0.

Parameters:: article_id (str) – The ID of the article to archive
Returns:: The API response from the POST request
Raises:: RuntimeError

assign_data_category(article_id: str, category_group_name: str, category_name: str)[source]#

This method assigns a single data category for a knowledge article. (Reference)

Added in version 1.2.0.

Parameters:

article_id (str) – The ID of the article to update
category_group_name (str) – The unique Data Category Group Name
category_name (str) – The unique Data Category Name

Returns:

The API response from the POST request

Raises:

check_for_existing_article(title: str, sobject: str | None = None, return_id: bool = False, return_id_and_number: bool = False, include_archived: bool = False)[source]#

This method checks to see if an article already exists with a given title and returns its article number. (Reference 1. Reference 2)

Parameters:

title (str) – The title of the knowledge article for which to check
sobject (str, None) – The Salesforce object to query (Knowledge__kav by default)
return_id (bool) – Determines if the Article ID should be returned (False by default)
return_id_and_number (bool) – Determines if Article ID and Article Number should be returned (False by default)
include_archived (bool) – Determines if archived articles should be included (False by default)

Returns:

The Article Number, Article ID, or both (if found), or a blank string if not found

create_article(article_data: dict, sobject: str | None = None, full_response: bool = False)[source]#

This method creates a new knowledge article draft. (Reference)

Parameters:

article_data (dict) – The article data used to populate the article
sobject (str, None) – The Salesforce object to query (Knowledge__kav by default)
full_response (bool) – Determines if the full API response should be returned instead of the article ID (False by default)

Returns:

The API response or the ID of the article draft

Raises:

create_draft_from_master_version(article_id: str | None = None, knowledge_article_id: str | None = None, article_data: dict | None = None, sobject: str | None = None, full_response: bool = False)[source]#

This method creates an online version of a master article. (Reference)

Changed in version 1.5.0: The salespyforce.errors.exceptions.MissingRequiredDataError exception class is now raised when required parameters are missing instead of the generic RuntimeError exception.

Parameters:

article_id (str, None) – The Article ID from which to create the draft
knowledge_article_id (str, None) – The Knowledge Article ID (KnowledgeArticleId) from which to create the draft
article_data (dict, None) – The article data associated with the article from which to create the draft
sobject (str, None) – The Salesforce object to query (Knowledge__kav by default)
full_response (bool) – Determines if the full API response should be returned instead of the article ID (False by default)

Returns:

The API response or the ID of the article draft

Raises:

create_draft_from_online_article(article_id: str, unpublish: bool = False)[source]#

This method creates a draft knowledge article from an online article. (Reference)

Parameters:

article_id (str) – The ID of the online article from which to create the draft
unpublish (bool) – Determines if the online article should be unpublished when the draft is created (False by default)

Returns:

The API response from the POST request

Raises:

delete_article_draft(version_id: str, sobject: str | None = None, use_knowledge_management_endpoint: bool = True)[source]#

This function deletes an unpublished knowledge article draft.

Changed in version 1.5.0: An optional sobject parameter can now be passed to specify the sObject against which to query.

Added in version 1.4.0.

Parameters:

version_id (str) – The 15-character or 18-character Id (Knowledge Article Version ID) value
sobject (str, None) – The Salesforce object to query (Knowledge__kav by default)
use_knowledge_management_endpoint (bool) – Leverage the /knowledgeManagement/articleVersions/masterVersions/ endpoint rather than the /sobjects/Knowledge__kav/ endpoint (True by default)

Returns:

The API response from the DELETE request

Raises:

RuntimeError, salespyforce.errors.exceptions.DataMismatchError

get_article_details(article_id: str, sobject: str | None = None, use_knowledge_articles_endpoint: bool | None = None)[source]#

This method retrieves details for a single knowledge article. (Reference)

Changed in version 1.4.0: A logic issue was resolved and the new optional use_knowledge_articles_endpoint parameter can now be set to force the knowledgeArticles endpoint to be used for the GET request rather than the sobjects endpoint.

Parameters:

article_id (str) – The Article ID for which to retrieve details
sobject (str, None) – The Salesforce object to query (Knowledge__kav by default)
use_knowledge_articles_endpoint (bool, None) – Optionally use the knowledgeArticles endpoint rather than sobjects to retrieve the article details (False by default)

Returns:

The details for the knowledge article

Raises:

get_article_id_from_number(article_number: str | int, sobject: str | None = None, return_uri: bool = False) → str[source]#

This method returns the Article ID when an article number is provided. (Reference 1, Reference 2)

Warning

The ability to retrieve the article URI/URL rather than the ID will be moved to a separate function in a future release.

Parameters:

article_number (str, int) – The Article Number to query
sobject (str, None) – The Salesforce object to query (Knowledge__kav by default)
return_uri (bool) – Determines if the URI of the article should be returned rather than the ID (False by default)

Returns:

The Article ID or Article URI, or a blank string if no article is found

Raises:

TypeError, RuntimeError

get_article_metadata(article_id: str) → dict[source]#

This method retrieves metadata for a specific knowledge article. (Reference)

Parameters:: article_id (str) – The Article ID for which to retrieve details
Returns:: The article metadata as a dictionary
Raises:: RuntimeError

get_article_url(article_id: str | None = None, article_number: str | int | None = None, sobject: str | None = None) → str[source]#

This function constructs the URL to view a knowledge article in Lightning or Classic.

Parameters:

article_id (str, None) – The Article ID for which to retrieve details
article_number (str, int, None) – The article number for which to retrieve details
sobject (str, None) – The Salesforce object to query (Knowledge__kav by default)

Returns:

The article URL as a string

Raises:

RuntimeError, salespyforce.errors.exceptions.MissingRequiredDataError

get_article_version(article_id: str)[source]#

This method retrieves the version ID for a given master article ID. (Reference)

Parameters:: article_id (str) – The Article ID for which to retrieve details
Returns:: The version ID for the given master article ID
Raises:: RuntimeError

get_articles_list(query: str | None = None, sort: str | None = None, order: str | None = None, page_size: int = 20, page_num: int = 1) → list[source]#

This method retrieves a list of knowledge articles. (Reference)

Parameters:

query (str, None) – A SOQL query with which to filter the results (optional)
sort (str, None) – Optionally sort the results with one of the following values: LastPublishedDate, CreatedDate, Title, or ViewScore
order (str, None) – Optionally define the ORDER BY as ASC or DESC
page_size (int) – The number of results per page (20 by default)
page_num (int) – The starting page number (1 by default)

Returns:

The list of retrieved knowledge articles

Raises:

RuntimeError, salespyforce.errors.exceptions.MissingRequiredDataError

get_validation_status(article_id: str | None = None, article_details: dict | None = None, sobject: str | None = None, use_knowledge_articles_endpoint: bool | None = None) → str[source]#

This method retrieves the Validation Status for a given Article ID. (Reference)

Changed in version 1.5.0: The use_knowledge_articles_endpoint parameter is now supported, which allows you to specify the REST path to utilize for the API query.

Changed in version 1.4.0: This method now returns an empty string rather than a None value if the ValidationStatus field is not found in the article details data, and a more specific exception class is used when input data is missing instead of the generic RuntimeError exception class.

Parameters:

article_id (str, None) – The Article ID for which to retrieve details
article_details (dict, None) – The dictionary of article details for the given article
sobject (str, None) – The Salesforce object to query (Knowledge__kav by default)
use_knowledge_articles_endpoint (bool, None) – Optionally use the knowledgeArticles endpoint rather than sobjects to retrieve the article details (False by default)

Returns:

The validation status as a text string

Raises:

publish_article(article_id: str, major_version: bool = True, full_response: bool = False)[source]#

This method publishes a draft knowledge article as a major or minor version. (Reference)

Parameters:

article_id (str) – The Article ID to publish
major_version (bool) – Determines if the published article should be a major version (True by default)
full_response (bool) – Determines if the full API response should be returned (False by default)

Returns:

A Boolean value indicating the success of the action or the API response from the PATCH request

Raises:

RuntimeError, salespyforce.errors.exceptions.MissingRequiredDataError

publish_multiple_articles(article_id_list: list, major_version: bool = True)[source]#

This method publishes multiple knowledge article drafts at one time. (Reference)

Changed in version 1.5.0: The salespyforce.errors.exceptions.MissingRequiredDataError exception class is now raised when required parameters are missing instead of a more generic exception.

Parameters:

article_id_list (list) – A list of Article IDs to be published
major_version (bool) – Determines if the published article should be a major version (True by default)

Returns:

The API response from the POST request

Raises:

update_article(record_id: str, article_data: dict, sobject: str | None = None, include_status_code: bool = False)[source]#

This method updates an existing knowledge article draft. (Reference)

Parameters:

record_id (str) – The ID of the article draft record to be updated
article_data (dict) – The article data used to update the article
sobject (str, None) – The Salesforce object to query (Knowledge__kav by default)
include_status_code (bool) – Determines if the API response status code should be returned (False by default)

Returns:

A Boolean indicating if the update operation was successful, and optionally the API response status code

Raises:

TypeError, RuntimeError, ValueError, salespyforce.errors.exceptions.InvalidURLError

api_call_with_payload(method: str, endpoint: str, payload: dict, params: dict | None = None, headers: dict | None = None, timeout: int | None = None, show_full_error: bool = True, return_json: bool = True)[source]#

This method performs a POST call against the Salesforce instance. (Reference)

Changed in version 1.4.0: A global constant is now leveraged for the API timeout value instead of hardcoding the value. (Timeout is still 30 seconds in this version)

Parameters:

method (str) – The API method (post, put, or patch)
endpoint (str) – The API endpoint to query
payload (dict) – The payload to leverage in the API call
params (dict, None) – The query parameters (where applicable)
headers (dict, None) – Specific API headers to use when performing the API call
timeout (int, None) – The timeout period in seconds (defaults to 30)
show_full_error (bool) – Determines if the full error message should be displayed (defaults to True)
return_json – Determines if the response should be returned in JSON format (defaults to True)

Returns:

The API response in JSON format or as a requests object

Raises:

can_access_record(access_type: str, record_id: str, user_id: str | None = None, record_access_data: dict | None = None, raise_exc_on_failure: bool = True) → bool[source]#

This method evaluates if a user can access a specific record given the access type.

Added in version 1.4.0.

Parameters:

access_type (str) – The type of access to evaluate (read, edit, or delete)
record_id (str) – The ID of the record
user_id (str, None) – The ID of the user to evaluate (defaults to the current/running user if not defined)
record_access_data (dict, None) – The user record access data that has already been retrieved (optional)
raise_exc_on_failure (bool) – Raises an exception rather than returning a None value (True by default)

Returns:

Boolean value indicating the access level for the given field

Raises:

can_delete_record(record_id: str, user_id: str | None = None, record_access_data: dict | None = None, raise_exc_on_failure: bool = True) → bool[source]#

This method evaluates if a user has access to delete a specific record.

Added in version 1.4.0.

Parameters:

record_id (str) – The ID of the record
user_id (str, None) – The ID of the user to evaluate (defaults to the current/running user if not defined)
record_access_data (dict, None) – The user record access data that has already been retrieved (optional)
raise_exc_on_failure (bool) – Raises an exception rather than returning a None value (True by default)

Returns:

Boolean value indicating the access level for the given field

Raises:

can_edit_record(record_id: str, user_id: str | None = None, record_access_data: dict | None = None, raise_exc_on_failure: bool = True) → bool[source]#

This method evaluates if a user has access to edit a specific record.

Added in version 1.4.0.

Parameters:

record_id (str) – The ID of the record
user_id (str, None) – The ID of the user to evaluate (defaults to the current/running user if not defined)
record_access_data (dict, None) – The user record access data that has already been retrieved (optional)
raise_exc_on_failure (bool) – Raises an exception rather than returning a None value (True by default)

Returns:

Boolean value indicating the access level for the given field

Raises:

can_read_record(record_id: str, user_id: str | None = None, record_access_data: dict | None = None, raise_exc_on_failure: bool = True) → bool[source]#

This method evaluates if a user has access to read a specific record.

Added in version 1.4.0.

Parameters:

record_id (str) – The ID of the record
user_id (str, None) – The ID of the user to evaluate (defaults to the current/running user if not defined)
record_access_data (dict, None) – The user record access data that has already been retrieved (optional)
raise_exc_on_failure (bool) – Raises an exception rather than returning a None value (True by default)

Returns:

Boolean value indicating the access level for the given field

Raises:

RuntimeError, salespyforce.errors.exceptions.APIRequestError

check_user_record_access(record_id: str, user_id: str | None = None) → dict[source]#

This method checks the Read, Edit, and Delete access for a given record and user.

Added in version 1.4.0.

Parameters:

record_id (str) – The Id value of the record against which to check the user access
user_id (str, None) – The Id of the user to evaluate (or the current user’s ID if not explicitly defined)

Returns:

Dictionary with Boolean values for HasReadAccess, HasEditAccess, and HasDeleteAccess

Raises:

connect()[source]#

This method connects to the Salesforce instance to obtain the access token. (Reference)

Returns:: The API call response with the authorization information
Raises:: RuntimeError

create_sobject_record(sobject: str, payload: dict)[source]#

This method creates a new record for a specific sObject. (Reference)

Parameters:

sobject (str) – The sObject under which to create the new record
payload (dict) – The JSON payload with the record details

Returns:

The API response from the POST request

Raises:

RuntimeError, TypeError

delete(endpoint: str, params: dict | None = None, headers: dict | None = None, timeout: int | None = None, show_full_error: bool = True, return_json: bool = True)[source]#

This method performs a DELETE request against the Salesforce instance. (Reference)

Added in version 1.4.0.

Parameters:

endpoint (str) – The API endpoint to query
params (dict, None) – The query parameters (where applicable)
headers (dict, None) – Specific API headers to use when performing the API call
timeout (int, None) – The timeout period in seconds (defaults to 30)
show_full_error (bool) – Determines if the full error message should be displayed (defaults to True)
return_json – Determines if the response should be returned in JSON format (defaults to True)

Returns:

The API response in JSON format or as a requests object

Raises:

TypeError, RuntimeError, salespyforce.errors.exceptions.InvalidURLError

describe_object(object_name: str)[source]#

This method returns the full (describe) information for a specific sObject. (Reference)

Parameters:: object_name (str) – The name of the Salesforce object
Returns:: The Salesforce object data
Raises:: RuntimeError

download_image(image_url: str, record_id: str, field_name: str, file_path: str | None = None, sobject: str | None = None) → str[source]#

This method downloads an image using the sObject Rich Text Image Retrieve functionality. (Reference 1, Reference 2)

Changed in version 1.5.0: Errors are now logged and Exceptions are raised when downloading the image fails.

Parameters:

image_url (str) – The URL for the image to be downloaded
record_id (str) – The Record ID where the image is found
field_name (str) – The field name within the record where the image is found
file_path (str, None) – The path to the directory where the image should be saved (current directory if not defined)
sobject (str, None) – The sObject for the record where the image is found (Knowledge__kav by default)

Returns:

The full path to the downloaded image

Raises:

TypeError, RuntimeError, salespyforce.errors.exceptions.InvalidURLError

get(endpoint: str, params: dict | None = None, headers: dict | None = None, timeout: int | None = None, show_full_error: bool = True, return_json: bool = True)[source]#

This method performs a GET request against the Salesforce instance. (Reference)

Changed in version 1.4.0: A global constant is now leveraged for the API timeout value instead of hardcoding the value. (Timeout is still 30 seconds in this version)

Parameters:

endpoint (str) – The API endpoint to query
params (dict, None) – The query parameters (where applicable)
headers (dict, None) – Specific API headers to use when performing the API call
timeout (int, None) – The timeout period in seconds (defaults to 30)
show_full_error (bool) – Determines if the full error message should be displayed (defaults to True)
return_json – Determines if the response should be returned in JSON format (defaults to True)

Returns:

The API response in JSON format or as a requests object

Raises:

static get_18_char_id(record_id: str) → str[source]#

This method converts a 15-character Salesforce record ID to its 18-character case-insensitive form.

Added in version 1.4.0.

Parameters:: record_id (str) – The Salesforce record ID to convert (or return unchanged if already 18 characters)
Returns:: The 18-character Salesforce record ID
Raises:: ValueError

get_all_sobjects()[source]#

This method returns a list of all Salesforce objects. (i.e. sObjects) (Reference)

Returns:: The list of all Salesforce objects
Raises:: RuntimeError

get_api_versions() → list[source]#

This method returns the API versions for the Salesforce releases. (Reference)

Returns:: A list containing the API metadata from the /services/data endpoint.
Raises:: RuntimeError

get_latest_api_version() → str[source]#

This method returns the latest Salesforce API version by querying the authorized org.

Added in version 1.4.0.

Returns:: The latest Salesforce API version for the authorized org as a string (e.g. 65.0)

get_org_limits()[source]#

This method returns a list of all org limits.

Added in version 1.1.0.

Returns:: The Salesforce org governor limits data
Raises:: RuntimeError

get_rest_resources()[source]#

This method returns a list of all available REST resources. (Reference)

Returns:: The list of all available REST resources for the Salesforce org
Raises:: RuntimeError

get_sobject(object_name: str, describe: bool = False)[source]#

This method returns basic information or the full (describe) information for a specific sObject. (Reference 1, Reference 2)

Parameters:

object_name (str) – The name of the Salesforce object
describe (bool) – Determines if the full (i.e. describe) data should be returned (defaults to False)

Returns:

The Salesforce object data

Raises:

TypeError, RuntimeError, ValueError, salespyforce.errors.exceptions.InvalidURLError

patch(endpoint: str, payload: dict, params: dict | None = None, headers: dict | None = None, timeout: int | None = None, show_full_error: bool = True, return_json: bool = True)[source]#

This method performs a PATCH call against the Salesforce instance. (Reference)

Changed in version 1.4.0: A global constant is now leveraged for the API timeout value instead of hardcoding the value. (Timeout is still 30 seconds in this version)

Parameters:

endpoint (str) – The API endpoint to query
payload (dict) – The payload to leverage in the API call
params (dict, None) – The query parameters (where applicable)
headers (dict, None) – Specific API headers to use when performing the API call
timeout (int, None) – The timeout period in seconds (defaults to 30)
show_full_error (bool) – Determines if the full error message should be displayed (defaults to True)
return_json – Determines if the response should be returned in JSON format (defaults to True)

Returns:

The API response in JSON format or as a requests object

Raises:

post(endpoint: str, payload: dict, params: dict | None = None, headers: dict | None = None, timeout: int | None = None, show_full_error: bool = True, return_json: bool = True)[source]#

This method performs a POST call against the Salesforce instance. (Reference)

Changed in version 1.4.0: A global constant is now leveraged for the API timeout value instead of hardcoding the value. (Timeout is still 30 seconds in this version)

Parameters:

endpoint (str) – The API endpoint to query
payload (dict) – The payload to leverage in the API call
params (dict, None) – The query parameters (where applicable)
headers (dict, None) – Specific API headers to use when performing the API call
timeout (int, None) – The timeout period in seconds (defaults to 30)
show_full_error (bool) – Determines if the full error message should be displayed (defaults to True)
return_json – Determines if the response should be returned in JSON format (defaults to True)

Returns:

The API response in JSON format or as a requests object

Raises:

TypeError, RuntimeError, ValueError, salespyforce.errors.exceptions.InvalidURLError

put(endpoint: str, payload: dict, params: dict | None = None, headers: dict | None = None, timeout: int | None = None, show_full_error: bool = True, return_json: bool = True)[source]#

This method performs a PUT call against the Salesforce instance. (Reference)

Changed in version 1.4.0: A global constant is now leveraged for the API timeout value instead of hardcoding the value. (Timeout is still 30 seconds in this version)

Parameters:

endpoint (str) – The API endpoint to query
payload (dict) – The payload to leverage in the API call
params (dict, None) – The query parameters (where applicable)
headers (dict, None) – Specific API headers to use when performing the API call
timeout (int, None) – The timeout period in seconds (defaults to 30)
show_full_error (bool) – Determines if the full error message should be displayed (defaults to True)
return_json – Determines if the response should be returned in JSON format (defaults to True)

Returns:

The API response in JSON format or as a requests object

Raises:

TypeError, RuntimeError, ValueError, salespyforce.errors.exceptions.InvalidURLError

retrieve_current_user_info(all_data: bool = False, raise_exc_on_error: bool = False, on_init: bool = False) → dict[source]#

This method retrieves the userinfo data for the current/running user.

Added in version 1.4.0.

Parameters:

all_data (bool) – Returns all userinfo data from the API when True instead of only the relevant fields/values (False by default)
raise_exc_on_error (bool) – Raises an exception if the API retrieval attempt fails when True (False by default)
on_init (bool) – Indicates if the method is being called during the core object instantiation (False by default)

Returns:

The user info data within a dictionary

Raises:

RuntimeError, salespyforce.errors.exceptions.APIRequestError

search_string(string_to_search: str)[source]#

This method performs a SOSL query to search for a given string. (Reference)

Added in version 1.1.0.

Parameters:: string_to_search (str) – The string for which to search
Returns:: The SOSL response data in JSON format
Raises:: RuntimeError

soql_query(query: str, replace_quotes: bool = True, next_records_url: bool = False)[source]#

This method performs a SOQL query and returns the results in JSON format. (Reference 1, Reference 2)

Parameters:

query (str) – The SOQL query to perform
replace_quotes (bool) – Determines if double-quotes should be replaced with single-quotes (True by default)
next_records_url (bool) – Indicates that the query parameter is a nextRecordsUrl value.

Returns:

The result of the SOQL query

Raises:

RuntimeError, TypeError

update_sobject_record(sobject: str, record_id: str, payload: dict)[source]#

This method updates an existing sObject record. (Reference)

Parameters:

sobject (str) – The sObject under which to update the record
record_id (str) – The ID of the record to be updated
payload (dict) – The JSON payload with the record details to be updated

Returns:

The API response from the PATCH request

Raises:

Core Module#

Module:: salespyforce.core
Synopsis:: This module performs the core Salesforce-related operations
Usage:: from salespyforce import Salesforce
Example:: sfdc = Salesforce(helper=helper_file_path)
Created By:: Jeff Shurtliff
Last Modified:: Jeff Shurtliff
Modified Date:: 01 Mar 2026

salespyforce.core.compile_connection_info(base_url: str, org_id: str, username: str, password: str, endpoint_url: str, client_id: str, client_secret: str, security_token: str) → dict[source]#

This function compiles the connection info into a dictionary that can be consumed by the core object.

Parameters:

base_url (str) – The base URL of the Salesforce instance
org_id (str) – The Org ID of the Salesforce instance
username (str) – The username of the API user
password (str) – The password of the API user
endpoint_url (str) – The endpoint URL for the Salesforce instance
client_id (str) – The Client ID for the Salesforce instance
client_secret (str) – The Client Secret for the Salesforce instance
security_token (str) – The Security Token for the Salesforce instance

Returns:

The connection info in a dictionary

salespyforce.core.define_connection_info() → dict[source]#

This function prompts the user for the connection information.

Returns:: The connection info in a dictionary

Additional Modules#

Module:: salespyforce.api
Synopsis:: Defines the basic functions associated with the Salesforce API
Created By:: Jeff Shurtliff
Last Modified:: Jeff Shurtliff
Modified Date:: 01 Mar 2026

salespyforce.api.api_call_with_payload(sfdc_object, method: str, endpoint: str, payload: dict, params: dict | None = None, headers: dict | None = None, timeout: int | None = None, show_full_error: bool = True, return_json: bool = True)[source]#

This method performs a POST call against the Salesforce instance. (Reference)

Changed in version 1.4.0: The full URL for the API call is now constructed prior to making the call. The provided URL is also now evaluated to ensure it is a valid Salesforce URL. Additionally, a global constant is now leveraged for the API timeout value instead of hardcoding the value. (Timeout is still 30 seconds in this version)

Parameters:

sfdc_object (class[salespyforce.Salesforce]) – The instantiated SalesPyForce object
method (str) – The API method (post, put, or patch)
endpoint (str) – The API endpoint to query
payload (dict) – The payload to leverage in the API call
params (dict, None) – The query parameters (where applicable)
headers (dict, None) – Specific API headers to use when performing the API call
timeout (int, None) – The timeout period in seconds (defaults to 30)
show_full_error (bool) – Determines if the full error message should be displayed (defaults to True)
return_json – Determines if the response should be returned in JSON format (defaults to True)

Returns:

The API response in JSON format or as a requests object

Raises:

TypeError, RuntimeError, ValueError, salespyforce.errors.exceptions.InvalidURLError

salespyforce.api.delete(sfdc_object, endpoint: str, params: dict | None = None, headers: dict | None = None, timeout: int | None = None, show_full_error: bool = True, return_json: bool = True)[source]#

This method performs a DELETE request against the Salesforce instance.

Added in version 1.4.0.

Parameters:

sfdc_object (class[salespyforce.Salesforce]) – The instantiated SalesPyForce object
endpoint (str) – The API endpoint to query
params (dict, None) – The query parameters (where applicable)
headers (dict, None) – Specific API headers to use when performing the API call
timeout (int, None) – The timeout period in seconds (defaults to 30)
show_full_error (bool) – Determines if the full error message should be displayed (defaults to True)
return_json – Determines if the response should be returned in JSON format (defaults to True)

Returns:

The API response in JSON format or as a requests object

Raises:

TypeError, RuntimeError, salespyforce.errors.exceptions.InvalidURLError

salespyforce.api.get(sfdc_object, endpoint: str, params: dict | None = None, headers: dict | None = None, timeout: int | None = None, show_full_error: bool = True, return_json: bool = True)[source]#

This method performs a GET request against the Salesforce instance. (Reference)

Parameters:

sfdc_object (class[salespyforce.Salesforce]) – The instantiated SalesPyForce object
endpoint (str) – The API endpoint to query
params (dict, None) – The query parameters (where applicable)
headers (dict, None) – Specific API headers to use when performing the API call
timeout (int, None) – The timeout period in seconds (defaults to 30)
show_full_error (bool) – Determines if the full error message should be displayed (defaults to True)
return_json – Determines if the response should be returned in JSON format (defaults to True)

Returns:

The API response in JSON format or as a requests object

Raises:

TypeError, RuntimeError, salespyforce.errors.exceptions.InvalidURLError

Module:: salespyforce.chatter
Synopsis:: Defines the Chatter-related functions associated with the Salesforce Connect API
Created By:: Jeff Shurtliff
Last Modified:: Jeff Shurtliff
Modified Date:: 27 Feb 2026

salespyforce.chatter.get_group_feed(sfdc_object, group_id: str, site_id: str | None = None)[source]#

This function retrieves a group’s news feed. (Reference)

Parameters:

sfdc_object (class[salespyforce.Salesforce]) – The instantiated SalesPyForce object
group_id (str) – The ID of the group whose feed you wish to return
site_id (str, None) – The ID of an Experience Cloud site against which to query (optional)

Returns:

The news feed data

Raises:

salespyforce.chatter.get_my_news_feed(sfdc_object, site_id: str | None = None)[source]#

This function retrieves the news feed for the user calling the function. (Reference)

Parameters:

sfdc_object (class[salespyforce.Salesforce]) – The instantiated SalesPyForce object
site_id (str, None) – The ID of an Experience Cloud site against which to query (optional)

Returns:

The news feed data

Raises:

salespyforce.chatter.get_user_news_feed(sfdc_object, user_id: str, site_id: str | None = None)[source]#

This function retrieves another user’s news feed. (Reference)

Parameters:

sfdc_object (class[salespyforce.Salesforce]) – The instantiated SalesPyForce object
user_id (str) – The ID of the user whose feed you wish to return
site_id (str, None) – The ID of an Experience Cloud site against which to query (optional)

Returns:

The news feed data

Raises:

RuntimeError salespyforce.errors.exceptions.MissingRequiredDataError

salespyforce.chatter.post_comment(sfdc_object, feed_element_id: str, message_text: str | None = None, message_segments: list | None = None, site_id: str | None = None, created_by_id: str | None = None)[source]#

This function publishes a comment on a Chatter feed item. (Reference)

Changed in version 1.5.0: This function now utilizes centralized constants and a new helper function to construct the endpoint and payload. It also now raises the salespyforce.errors.exceptions.MissingRequiredDataError exception rather than the generic RuntimeError exception.

Parameters:

sfdc_object (class[salespyforce.Salesforce]) – The instantiated SalesPyForce object
feed_element_id (str) – The ID of the feed element on which to post the comment
message_text (str, None) – Plaintext to be used as the message body
message_segments (list, None) – Collection of message segments to use instead of a plaintext message
site_id (str, None) – The ID of an Experience Cloud site against which to query (optional)
created_by_id (str, None) – The ID of the user to impersonate (Experimental)

Returns:

The response of the POST request

Raises:

salespyforce.chatter.post_feed_item(sfdc_object, subject_id: str, message_text: str | None = None, message_segments: list | None = None, site_id: str | None = None, created_by_id: str | None = None)[source]#

This function publishes a new Chatter feed item. (Reference)

Changed in version 1.4.0: The function now raises the salespyforce.errors.exceptions.MissingRequiredDataError exception rather than the generic RuntimeError exception.

Parameters:

sfdc_object (class[salespyforce.Salesforce]) – The instantiated SalesPyForce object
subject_id (str) – The Subject ID against which to publish the feed item (e.g. 0F9B000000000W2)
message_text – Plaintext to be used as the message body
message_segments (list, None) – Collection of message segments to use instead of a plaintext message
site_id (str, None) – The ID of an Experience Cloud site against which to query (optional)
created_by_id (str, None) – The ID of the user to impersonate (Experimental)

Returns:

The response of the POST request

Raises:

RuntimeError, salespyforce.errors.exceptions.MissingRequiredDataError

Module:: salespyforce.decorators
Synopsis:: Decorators that can be used to include additional functionality with functions and methods
Created By:: Jeff Shurtliff
Last Modified:: Jeff Shurtliff
Modified Date:: 25 Feb 2026

salespyforce.decorators.deprecated(*, since: str, replacement: str | None = None, removal: str | None = None, category: ~typing.Type[Warning] = <class 'DeprecationWarning'>, stacklevel: int = 2) → Callable[[F], F][source]#

This decorator marks a callable as deprecated and emits a warning at runtime.

Added in version 1.4.0.

Parameters:

since (str) – Version when deprecation started
replacement (str, None) – Suggested replacement usage (string)
removal (str, None) – Version when it will be removed (optional)
category (type[Warning]) – Warning category (default: DeprecationWarning)
stacklevel (int) – Warning stacklevel (default: 2)

Module:: salespyforce.knowledge
Synopsis:: Defines the Knowledge-related functions associated with the Salesforce API
Created By:: Jeff Shurtliff
Last Modified:: Jeff Shurtliff
Modified Date:: 28 Feb 2026

salespyforce.knowledge.archive_article(sfdc_object, article_id: str)[source]#

This function archives a published knowledge article. (Reference)

Added in version 1.3.0.

Parameters:

sfdc_object (class[salespyforce.Salesforce]) – The instantiated SalesPyForce object
article_id (str) – The ID of the article to archive

Returns:

The API response from the PATCH request

Raises:

salespyforce.knowledge.assign_data_category(sfdc_object, article_id: str, category_group_name: str, category_name: str)[source]#

This function assigns a single data category for a knowledge article. (Reference)

Added in version 1.2.0.

Parameters:

sfdc_object (class[salespyforce.Salesforce]) – The instantiated SalesPyForce object
article_id (str) – The ID of the article to update
category_group_name (str) – The unique Data Category Group Name
category_name (str) – The unique Data Category Name

Returns:

The API response from the POST request

Raises:

salespyforce.knowledge.check_for_existing_article(sfdc_object, title: str, sobject: str | None = None, return_id: bool = False, return_id_and_number: bool = False, include_archived: bool = False) → str | Tuple[str, str][source]#

This method checks to see if an article already exists with a given title and returns its article number. (Reference 1, Reference 2)

Changed in version 1.2.2: You can now specify whether archived articles are included in the query results.

Parameters:

sfdc_object (class[salespyforce.Salesforce]) – The instantiated SalesPyForce object
title (str) – The title of the knowledge article for which to check
sobject (str, None) – The Salesforce object to query (Knowledge__kav by default)
return_id (bool) – Determines if the Article ID should be returned (False by default)
return_id_and_number (bool) – Determines if Article ID and Article Number should be returned (False by default)
include_archived (bool) – Determines if archived articles should be included (False by default)

Returns:

The Article Number, Article ID, or both, if found, or a blank string if not found

Raises:

TypeError

salespyforce.knowledge.create_article(sfdc_object, article_data: dict, sobject: str | None = None, full_response: bool = False)[source]#

This function creates a new knowledge article draft. (Reference)

Parameters:

sfdc_object (class[salespyforce.Salesforce]) – The instantiated SalesPyForce object
article_data (dict) – The article data used to populate the article
sobject (str, None) – The Salesforce object to query (Knowledge__kav by default)
full_response (bool) – Determines if the full API response should be returned instead of the article ID (False by default)

Returns:

The API response or the ID of the article draft

Raises:

salespyforce.errors.exceptions.MissingRequiredDataError

salespyforce.knowledge.create_draft_from_master_version(sfdc_object, article_id: str | None = None, knowledge_article_id: str | None = None, article_data: dict | None = None, sobject: str | None = None, full_response: bool = False)[source]#

This function creates an online version of a master article. (Reference)

Parameters:

sfdc_object (class[salespyforce.Salesforce]) – The instantiated SalesPyForce object
article_id (str, None) – The Article ID from which to create the draft
knowledge_article_id (str, None) – The Knowledge Article ID (KnowledgeArticleId) from which to create the draft
article_data (dict, None) – The article data associated with the article from which to create the draft
sobject (str, None) – The Salesforce object to query (Knowledge__kav by default)
full_response (bool) – Determines if the full API response should be returned instead of the article ID (False by default)

Returns:

The API response or the ID of the article draft

Raises:

salespyforce.knowledge.create_draft_from_online_article(sfdc_object, article_id: str, unpublish: bool = False)[source]#

This function creates a draft knowledge article from an online article. (Reference)

Parameters:

sfdc_object (class[salespyforce.Salesforce]) – The instantiated SalesPyForce object
article_id (str) – The ID of the online article from which to create the draft
unpublish (bool) – Determines if the online article should be unpublished when the draft is created (False by default)

Returns:

The API response from the POST request

Raises:

salespyforce.knowledge.delete_article_draft(sfdc_object, version_id: str, sobject: str | None = None, use_knowledge_management_endpoint: bool = True)[source]#

This function deletes an unpublished knowledge article draft.

Changed in version 1.5.0: An optional sobject parameter can now be passed to specify the sObject against which to query.

Added in version 1.4.0.

Parameters:

sfdc_object (class[salespyforce.Salesforce]) – The instantiated SalesPyForce object
version_id (str) – The 15-character or 18-character Id (Knowledge Article Version ID) value
sobject (str, None) – The Salesforce object to query (Knowledge__kav by default)
use_knowledge_management_endpoint (bool) – Leverage the /knowledgeManagement/articleVersions/masterVersions/ endpoint rather than the /sobjects/Knowledge__kav/ endpoint (True by default)

Returns:

The API response from the DELETE request

Raises:

RuntimeError, salespyforce.errors.exceptions.DataMismatchError

salespyforce.knowledge.get_article_details(sfdc_object, article_id: str, sobject: str | None = None, use_knowledge_articles_endpoint: bool | None = None)[source]#

This function retrieves details for a single knowledge article. (Reference)

Parameters:

sfdc_object (class[salespyforce.Salesforce]) – The instantiated SalesPyForce object
article_id (str) – The Article ID for which to retrieve details
sobject (str, None) – The Salesforce object to query (Knowledge__kav by default)
use_knowledge_articles_endpoint (bool, None) – Optionally use the knowledgeArticles endpoint rather than sobjects to retrieve the article details (False by default)

Returns:

The details for the knowledge article

Raises:

salespyforce.knowledge.get_article_id_from_number(sfdc_object, article_number: str | int, sobject: str | None = None, return_uri: bool = False) → str[source]#

This method returns the Article ID when an article number is provided. (Reference 1, Reference 2)

Warning

The ability to retrieve the article URI/URL rather than the ID will be moved to a separate function in a future release.

Changed in version 1.4.0: A logic issue has been fixed and improved to make this function more robust and stable.

Parameters:

sfdc_object (class[salespyforce.Salesforce]) – The instantiated SalesPyForce object
article_number (str, int) – The Article Number to query
sobject (str, None) – The Salesforce object to query (Knowledge__kav by default)
return_uri (bool) – Determines if the URI of the article should be returned rather than the ID (False by default)

Returns:

The Article ID or Article URI, or a blank string if no article is found

Raises:

TypeError, RuntimeError

salespyforce.knowledge.get_article_metadata(sfdc_object, article_id: str)[source]#

This function retrieves metadata for a specific knowledge article. (Reference)

Parameters:

sfdc_object (class[salespyforce.Salesforce]) – The instantiated SalesPyForce object
article_id (str) – The Article ID for which to retrieve details

Returns:

The article metadata as a dictionary

Raises:

salespyforce.errors.exceptions.MissingRequiredDataError

salespyforce.knowledge.get_article_url(sfdc_object, article_id: str | None = None, article_number: str | int | None = None, sobject: str | None = None) → str[source]#

This function constructs the URL to view a knowledge article in Lightning or Classic.

Changed in version 1.2.0: Changed when lightning URLs are defined and fixed an issue with extraneous slashes.

Parameters:

sfdc_object (class[salespyforce.Salesforce]) – The instantiated SalesPyForce object
article_id (str, None) – The Article ID for which to retrieve details
article_number (str, int, None) – The article number for which to retrieve details
sobject (str, None) – The Salesforce object to query (Knowledge__kav by default)

Returns:

The article URL as a string

Raises:

salespyforce.knowledge.get_article_version(sfdc_object, article_id: str)[source]#

This function retrieves the version ID for a given master article ID. (Reference)

Parameters:

sfdc_object (class[salespyforce.Salesforce]) – The instantiated SalesPyForce object
article_id (str) – The Article ID for which to retrieve details

Returns:

The version ID for the given master article ID

Raises:

RuntimeError, salespyforce.errors.exceptions.MissingRequiredDataError

salespyforce.knowledge.get_articles_list(sfdc_object, query: str | None = None, sort: str | None = None, order: str | None = None, page_size: int = 20, page_num: int = 1) → list[source]#

This function retrieves a list of knowledge articles. (Reference)

Changed in version 1.4.0: The errors now log as errors via the logger rather than to the stderr console.

Parameters:

sfdc_object (class[salespyforce.Salesforce]) – The instantiated SalesPyForce object
query (str, None) – A SOQL query with which to filter the results (optional)
sort (str, None) – One of the following optional values: LastPublishedDate, CreatedDate, Title, or ViewScore
order (str, None) – Optionally define the ORDER BY as ASC or DESC
page_size (int) – The number of results per page (20 by default)
page_num (int) – The starting page number (1 by default)

Returns:

The list of retrieved knowledge articles

salespyforce.knowledge.get_validation_status(sfdc_object, article_id: str | None = None, article_details: dict | None = None, sobject: str | None = None, use_knowledge_articles_endpoint: bool | None = None) → str[source]#

This function retrieves the Validation Status for a given Article ID. (Reference)

Changed in version 1.5.0: The use_knowledge_articles_endpoint parameter is now supported, which allows you to specify the REST path to utilize for the API query.

Changed in version 1.4.0: The function now returns an empty string rather than a None value if the ValidationStatus field is not found in the article details data, and a more specific exception class is used when input data is missing instead of the generic RuntimeError exception class.

Parameters:

sfdc_object (class[salespyforce.Salesforce]) – The instantiated SalesPyForce object
article_id (str, None) – The Article ID for which to retrieve details
article_details (dict, None) – The dictionary of article details for the given article
sobject (str, None) – The Salesforce object to query (Knowledge__kav by default)
use_knowledge_articles_endpoint (bool, None) – Optionally use the knowledgeArticles endpoint rather than sobjects to retrieve the article details (False by default)

Returns:

The validation status as a text string

Raises:

salespyforce.knowledge.publish_article(sfdc_object, article_id: str, major_version: bool = True, full_response: bool = False)[source]#

This function publishes a draft knowledge article as a major or minor version. (Reference)

Parameters:

sfdc_object (class[salespyforce.Salesforce]) – The instantiated SalesPyForce object
article_id (str) – The Article ID to publish
major_version (bool) – Determines if the published article should be a major version (True by default)
full_response (bool) – Determines if the full API response should be returned (False by default)

Returns:

A Boolean value indicating the success of the action or the API response from the PATCH request

Raises:

RuntimeError, salespyforce.errors.exceptions.MissingRequiredDataError

salespyforce.knowledge.publish_multiple_articles(sfdc_object, article_id_list: list, major_version: bool = True)[source]#

This function publishes multiple knowledge article drafts at one time. (Reference)

Changed in version 1.5.0: The salespyforce.errors.exceptions.MissingRequiredDataError exception class is now raised when required parameters are missing instead of a more generic exception.

Parameters:

sfdc_object (class[salespyforce.Salesforce]) – The instantiated SalesPyForce object
article_id_list (list) – A list of Article IDs to be published
major_version (bool) – Determines if the published article should be a major version (True by default)

Returns:

The API response from the POST request

Raises:

salespyforce.knowledge.update_article(sfdc_object, record_id: str, article_data: dict, sobject: str | None = None, include_status_code: bool = False)[source]#

This function updates an existing knowledge article draft. (Reference)

Parameters:

sfdc_object (class[salespyforce.Salesforce]) – The instantiated SalesPyForce object
record_id (str) – The ID of the article draft record to be updated
article_data (dict) – The article data used to update the article
sobject (str, None) – The Salesforce object to query (Knowledge__kav by default)
include_status_code (bool) – Determines if the API response status code should be returned (False by default)

Returns:

A Boolean indicating if the update operation was successful, and optionally the API response status code

Raises: