Wraps the HubSpot REST API for convenient access from ruby applications.
Documentation for the HubSpot REST API can be found here: https://developers.hubspot.com/docs/endpoints
gem install hubspot-ruby
Or with bundler,
gem "hubspot-ruby"
Before using the library, you must initialize it with your HubSpot API key. If you're using Rails, put this code in an initializer:
Hubspot.configure(hapikey: "YOUR_API_KEY")
If you have a HubSpot account, you can get your api key by logging in and visiting this url: https://app.hubspot.com/keys/get
Configure the library with the client ID and secret from your HubSpot App
Hubspot.configure(
client_id: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
client_secret: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
redirect_uri: "https://myapp.com/oauth")
To initiate an OAuth connection to your app, create a URL with the required scopes:
Hubspot::OAuth.authorize_url(["contacts", "content"])
After the user accepts the scopes and installs the integration with their HubSpot account, they will be redirected to the URI requested with the query parameter code
appended to the URL. code
can then be passed to HubSpot to generate an access token:
Hubspot::OAuth.create(params[:code])
To use the returned access_token
string for authentication, you'll need to update the configuration:
Hubspot.configure(
client_id: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
client_secret: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
redirect_uri: "https://myapp.com/oauth",
access_token: access_token)
Now all requests will use the provided access token when querying the API:
Hubspot::Contact.all
When you create a HubSpot OAuth token, it will have an expiration date given by the expires_in
field returned from the create API. If you with to continue using the token without needing to create another, you'll need to refresh the token:
Hubspot::OAuth.refresh(refresh_token)
At this time, OAuth tokens are configured globally rather than on a per-connection basis.
Here's what you can do for now:
Hubspot::Contact.create!("email@address.com", {firstname: "First", lastname: "Last"})
Hubspot::Contact.create_or_update!([{email: 'smith@example.com', firstname: 'First', lastname: 'Last'}])
These methods will return a Hubspot::Contact
object if successful, nil
otherwise:
Hubspot::Contact.find_by_email("email@address.com")
Hubspot::Contact.find_by_id(12345) # Pass the contact VID
Given an instance of Hubspot::Contact
, update its attributes with:
contact.update!({firstname: "First", lastname: "Last"})
Hubspot::Contact.create_or_update!([{vid: '12345', firstname: 'First', lastname: 'Last'}])
Hubspot::Deal.create!(nil, [company.vid], [contact.vid], pipeline: 'default', dealstage: 'initial_contact')
- Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
- Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
- Fork the project.
- Start a feature/bugfix branch.
- Commit and push until you are happy with your contribution.
- Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
- Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
All tests can be run with rake spec
. Isolate fast-running tests with rake spec:quick
.
GET requests are pretty easy to test with VCR, but for POST/PUT requests, you probably want to update verify the state
of a live HubSpot instance. To do this, please add "live" tests to spec/live/
, using the rspec label live: true
in
order to disable VCR.
"Live" tests can be isolated with rake spec:live
.
This project and the code therein was not created by and is not supported by HubSpot, Inc or any of its affiliates.