Restforce

1. Add restforce to your Gemfile, then run bundle install (or install it manually with gem install).

gem 'restforce', '~> 5.0.0'

The gem only supports Ruby 2.5 onwards. To use Restforce with earlier versions of Ruby, you'll need to use an earlier version of the gem.

2. Instantiate a Restforce client object with your API authentication details. You can use your username and password as below, or authenticate with OAuth.

# Don't commit your authentication details with your code - use environment variables <3
export SALESFORCE_USERNAME="username"
export SALESFORCE_PASSWORD="password"
export SALESFORCE_SECURITY_TOKEN="security token"
export SALESFORCE_CLIENT_ID="client id"
export SALESFORCE_CLIENT_SECRET="client secret"
export SALESFORCE_API_VERSION="38.0"

client = Restforce.new

3. Query Salesforce like a pro.

my_leads = client.query("SELECT Id, Source FROM Lead where OwnerId = 'INSERT_USER_ID_HERE'")
# => #<Restforce::Collection >

To discover all the great things you can do with Restforce, check out the README and the full documentation.

• 10th July 2020: We've released a new major version of the gem, v5.0.0. This version drops support for Ruby 2.4, introduces a number of other breaking changes (e.g. tweaks to how errors are defined) and brings exciting new features, including support for Faraday v1.0. For more details, see the changelog and upgrade guide.
• 23rd January 2020: v4.2.2 has been released, fixing a pesky bug with how we generate the results returned by the library.
• 5th December 2019: v4.2.1 is now available, fixing a bug with authentication errors and a Faraday deprecation warning.
• 23rd October 2019: v4.2.0 has been released, adding support for platform events, CDC, generic events and more in the Streaming API.
• 20th October 2019: v4.1.0 is now available, adding support for JWT authentication.
• 9th October 2019: v4.0.0 has launched, bringing support for the bulk API, better errors and a fix for how IDs are escaped. This version officially drops support for Ruby 2.3 - if you want to use Ruby 2.3, then v3.2.0 of the gem includes the same features and bug fixes.
• 16th August 2018: v3.1.0 has been released, adding support for replying missed messages when using Salesforce's Streaming API.
• 4th August 2018: v3.0.1 is now available, fixing a bug introduced by v3.0.0 which led to a NoMethodError when upserting an existing record.
• 2nd August 2018: v3.0.0 has been released. It drops support for Ruby 2.0, 2.1 and 2.2 (which have all reached end-of-life) and fixes a number of bugs.
• 21st August 2017: Restforce has moved (again!), now to restforce/restforce. Thanks to @antwonlee for letting us have the organisation name!
• 19th August 2017: Restforce has moved to its own organisation on GitHub - the source code and community is now at restforcegem/restforce.
• 25th April 2017: v2.5.3 is now available. It fixes a bug where upsert and upsert! mutated the provided attributes, starts raising an error where a custom external ID field name is supplied to upsert and upsert! but it is missing from the provided attributes, and uses the client's configured SSL options for authentication requests. (changelog)
• 3rd April 2017: v2.5.2 has been released. It fixes a bug with logging that caused logs related to custom headers (added in v2.5.1) and Gzip to be missing, and improves compatability with versions of Hashie since v3.5.0. (changelog)
• 16th March 2017: v2.5.1 is now available. It adds support for setting custom headers and upserting with an ID, and relaxes the gem's dependency on Faraday to allow upgrading it to 1.0. (changelog)
• 7th December 2016: v2.5.0 has been released. It removes compatability with Ruby 1.9.3 and improves the security of the gem's caching behaviour by hashing authentication credentials in cache keys. (changelog)
• 20th October 2016: v2.4.2 is now available. It relaxes the gem's dependencies for users of Ruby 2.0.0 onwards to allow wider compatability (e.g. with Rails 4). (changelog)
• 18th October 2016: v2.4.1 has just been released. It adds compatability with pre-released versions of Ruby 2.4.0. (changelog)
• 29th July 2016: v2.4.0 is available via RubyGems.org. It supports the Document resource, which behaves just like Attachment. (changelog)
• 15th July 2016: v2.3.0 is live on RubyGems.org. It allows you to optionally specify the Salesforce API version with a SALESFORCE_API_VERSION environment variable. (changelog)
• 6th June 2016: v2.2.1 is now available from RubyGems.org. It adds support for a new get_deleted method. (changelog)
• 16th March 2016: v2.2.0 has just been released. It improves the handling of errors returned by the API, notably raising an error when a 300 is returned due to an external ID matching multiple records for an upsert operation. (changelog)
• 9th March 2016: v2.1.3 is now available. It returns a new Restforce::ServerError when Salesforce is experiencing problems, and improves the handling of the response body in errors. (changelog)

We welcome contributions and bug reports so we can together make Restforce as great as possible 💕

We'd love to have you involved, whether it's your first open source contribution or your thousandth. To get started, see our CONTRIBUTING.md, and take note of our code of conduct.

If you have any questions, contact Tim Rogers, the maintainer.

Want help using Restforce, with contributing, or have another question?

Get in touch with Tim Rogers, the maintainer of Restforce, at tim@restforce.org.