Primary Modules

This section provides details around the primary modules used in the salespyforce package, which are listed below.


Init Module (salespyforce)

The Init Module is covered on this page.


Core Module (salespyforce.core)

The Core Module is covered on this page.


API Module (salespyforce.api)

This module handles basic interactions with the Salesforce API.

Module:

salespyforce.api

Synopsis:

Defines the basic functions associated with the Salesforce API

Created By:

Jeff Shurtliff

Last Modified:

Jeff Shurtliff

Modified Date:

03 Feb 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)

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

  • 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

Return to Top


Chatter Module (salespyforce.chatter)

This module handles interactions with Salesforce Chatter.

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:

03 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:

RuntimeError

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:

RuntimeError

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.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)

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:

RuntimeError

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

Return to Top


Knowledge Module (salespyforce.knowledge)

This module handles interactions with Salesforce Knowledge.

Module:

salespyforce.knowledge

Synopsis:

Defines the Knowledge-related functions associated with the Salesforce API

Created By:

Jeff Shurtliff

Last Modified:

Jeff Shurtliff

Modified Date:

03 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 POST request

Raises:

RuntimeError

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:

RuntimeError

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)[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

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:

ValueError, TypeError, RuntimeError

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:

RuntimeError

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:

RuntimeError

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

This function deletes an unpublished knowledge article draft.

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

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

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:

  • 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:

RuntimeError, salespyforce.errors.exceptions.DataMismatchError

salespyforce.knowledge.get_article_id_from_number(sfdc_object, article_number, 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:

RuntimeError

salespyforce.knowledge.get_article_url(sfdc_object, article_id: str | None = None, article_number=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:

ValueError

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.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)[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) → str[source]

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

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)

Returns:

The validation status as a text string

Raises:

RuntimeError, salespyforce.errors.exceptions.MissingRequiredDataError

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.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)

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:

RuntimeError, TypeError, ValueError

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:

ValueError, TypeError, RuntimeError

Return to Top