Ruby API v3 Client files and sample apps

  • API version: v3
  • Package version: 1.0.0
  • Build package: io.swagger.codegen.languages.RubyClientCodegen


See the Hubspot API docs.


gem install 'hubspot-api-client'

Getting Started

Please follow the installation procedure and then run the following code:

# Load the gem
require 'hubspot-api-client'

# Setup client
client = 'your_access_token')

# Get contacts
contacts = client.crm.contacts.basic_api.get_page


Hapikey support:

Please, note that hapikey is no longer supported after v13.1.0. You can get more info about hapikey sunset here. Also, plese, visit a migration guide if you need help with a migration process.

Get all:

get_all method is available for all objects (Companies, Contacts, Deals and etc).

client = 'your_oauth2_access_token')
all_contacts = client.crm.contacts.basic_api.get_all

You'll need to create a private app to get your access token or you can obtain OAuth2 access token.

Please note that pagination is used under the hood to get all results.

do_search method is available for all objects (Companies, Contacts, Deals and etc).

Only 3 FilterGroups with max 3 Filters are supported.

Example search by date

require 'hubspot-api-client'
require 'date'

api_client = "YOUR_ACCESS_TOKEN")
# timestamp in milliseconds
timestamp = (DateTime.parse("XXXX-XX-XXTXX:XX:XX.XXXZ").to_time.to_f * 1000).to_i.to_s
body = {
            "value": timestamp,
api_response = api_client.crm.contacts.search_api.do_search(
  body: body
puts api_response

Crm Object Schemas client usage:


client = 'your_oauth2_access_token')

labels = {
  singular: 'My object',
  plural: 'My objects'

option = {
  label: 'Option A',
  value: 'A',
  description: 'Choice number one',
  display_order: 1,
  hidden: false

property = {
  name: 'property001',
  label: 'My object property',
  group_name: 'my_object_information',
  options: [option],
  display_order: 2,
  type: 'enumeration',
  field_type: 'select'

body = {
  labels: labels,
  required_properties: ['property001'],
  searchable_properties: [],
  primary_display_property: 'property001',
  secondary_display_properties: [],
  properties: [property],
  associated_objects: ['CONTACT'],
  name: 'my_object'

api_response = client.crm.schemas.core_api.create(body: body)

Error handling

You can rescue an ApiError by passing a block to the method

require 'hubspot-api-client'

client = 'your_access_token')

contacts = client.crm.contacts.basic_api.get_page { |error| error.message }

You can set number of retry attempts and delay in seconds before retry on specific status code of response.

Available params:

  • max_retries (maximum number of retries)
  • seconds_delay (pause in seconds between retries)
  • passing a block (block that handles errors occured)
require 'hubspot-api-client'

# Set handlers of statuses you want to handle
retry_config = {
  500..530 => { max_retries: 2, seconds_delay: 2 },
  400 => { max_retries: 3, seconds_delay: 3 }

client = 'your_access_token')

contacts = client.crm.contacts.basic_api.get_page(retry: retry_config) { |error| error.code }

Sample apps

Please, take a look at our Sample apps