basecrm-ruby

BaseCRM Official API V2 library client for ruby

Installation

Make sure you have rubygems installed.

The gem is available via Rubygems. To install, use the following command:

sudo gem install basecrm

If you use Bundler, put the line below in your Gemfile:

gem 'basecrm'

To get the latest version, put this in your Gemfile:

gem 'basecrm', :git => 'git://github.com/basecrm/basecrm-ruby.git'

Usage

require "basecrm"

# Then we instantiate a client (as shown below)

Build a client

Using this api without authentication gives an error

client = BaseCRM::Client.new(access_token: "<YOUR_PERSONAL_ACCESS_TOKEN>")

Client Options

The following options are available while instantiating a client:

  • access_token: Personal access token
  • base_url: Base url for the api
  • user_agent: Default user-agent for all requests
  • timeout: Request timeout
  • verbose: Verbose/debug mode
  • logger: Logger used in verbose mode

Architecture

The library follows few architectural principles you should understand before digging deeper. 1. Interactions with resources are done via service objects. 2. Service objects are exposed as methods on client instances. 3. Service objects expose resource-oriented actions. 4. Actions return Plain Old Ruby Objects.

For example, to interact with deals API you will use DealsService, which you can get if you call:

client = BaseCRM::Client.new(access_token: "<YOUR_PERSONAL_ACCESS_TOKEN>")
client.deals # => BaseCRM::DealsService

When you want to fetch all resources you will use #all method which returns paginated resource (which implements Enumerable):

client = BaseCRM::Client.new(access_token: "<YOUR_PERSONAL_ACCESS_TOKEN>")
client.deals.all.map { |deal| deal.name } # => Array<String>

To retrieve list of resources and use filtering you will call #where method:

client = BaseCRM::Client.new(accss_token: "<YOUR_PERSONAL_ACCESS_TOKEN>")
client.deals.where(organization_id: google.id, hot: true) # => Array<BaseCRM::Deal>

To find a resource by it's unique identifier use #find method:

client = BaseCRM::Client.new(access_token: "<YOUR_PERSONAL_ACCESS_TOKEN>")
client.deals.find(id) # => BaseCRM::Deal

When you'd like to create a resource, or update it's attributes you want to use either #create or #update methods. Both of them can take either Hash or a model class e.g. Deal instance. For example if you want to create a new deal you will call:

client = BaseCRM::Client.new(access_token: "<YOUR_PERSONAL_ACCESS_TOKEN>")
coffeeshop = client.contacts.where(name: "Coffee Shop")

deal = client.deals.create(name: "Website redesign", contact_id: coffeeshop.id)
deal.value = 1000
deal.currency = "USD"

client.deals.update(deal) # => BaseCRM::Deal

To destroy a resource use #destroy method:

client = BaseCRM::Client.new(access_token: "<YOU_PERSONAL_ACCESS_TOKEN>")
client.deals.destroy(id) # => true

There other non-CRUD operations supported as well. Please contact corresponding service files for in-depth documentation.

Full example

Create a new organization and after that change it's attributes (website).

client = BaseCRM::Client.new(access_token: "<YOUR_PERSONAL_ACCESS_TOKEN>")
lead = client.leads.create(organization_name: "Design service company")

lead.website = "http://www.designservices.com"
client.leads.update(lead)

Resources and actions

Documentation for every action can be found in corresponding service files under lib/basecrm/services directory.

Account

client = BaseCRM::Client.new(access_token: "<YOUR_PERSONL_ACCESS_TOKEN>")
client.accounts # => BaseCRM::AccountsService

Actions:

  • Retrieve account details - client.accounts.self

AssociatedContact

client = BaseCRM::Client.new(access_token: "<YOUR_PERSONL_ACCESS_TOKEN>")
client.associated_contacts # => BaseCRM::AssociatedContactsService

Actions:

  • Retrieve deal's associated contacts - client.associated_contacts.all
  • Create an associated contact - client.associated_contacts.create
  • Remove an associated contact - client.associated_contacts.destroy

Contact

client = BaseCRM::Client.new(access_token: "<YOUR_PERSONL_ACCESS_TOKEN>")
client.contacts # => BaseCRM::ContactsService

Actions:

  • Retrieve all contacts - client.contacts.all
  • Create a contact - client.contacts.create
  • Retrieve a single contact - client.contacts.find
  • Update a contact - client.contacts.update
  • Delete a contact - client.contacts.destroy

Deal

client = BaseCRM::Client.new(access_token: "<YOUR_PERSONL_ACCESS_TOKEN>")
client.deals # => BaseCRM::DealsService

Actions:

  • Retrieve all deals - client.deals.all
  • Create a deal - client.deals.create
  • Retrieve a single deal - client.deals.find
  • Update a deal - client.deals.update
  • Delete a deal - client.deals.destroy

Lead

client = BaseCRM::Client.new(access_token: "<YOUR_PERSONL_ACCESS_TOKEN>")
client.leads # => BaseCRM::LeadsService

Actions:

  • Retrieve all leads - client.leads.all
  • Create a lead - client.leads.create
  • Retrieve a single lead - client.leads.find
  • Update a lead - client.leads.update
  • Delete a lead - client.leads.destroy

LossReason

client = BaseCRM::Client.new(access_token: "<YOUR_PERSONL_ACCESS_TOKEN>")
client.loss_reasons # => BaseCRM::LossReasonsService

Actions:

  • Retrieve all reasons - client.loss_reasons.all
  • Create a loss reason - client.loss_reasons.create
  • Retrieve a single reason - client.loss_reasons.find
  • Update a loss reason - client.loss_reasons.update
  • Delete a reason - client.loss_reasons.destroy

Note

client = BaseCRM::Client.new(access_token: "<YOUR_PERSONL_ACCESS_TOKEN>")
client.notes # => BaseCRM::NotesService

Actions:

  • Retrieve all notes - client.notes.all
  • Create a note - client.notes.create
  • Retrieve a single note - client.notes.find
  • Update a note - client.notes.update
  • Delete a note - client.notes.destroy

Pipeline

client = BaseCRM::Client.new(access_token: "<YOUR_PERSONL_ACCESS_TOKEN>")
client.pipelines # => BaseCRM::PipelinesService

Actions:

  • Retrieve all pipelines - client.pipelines.all

Source

client = BaseCRM::Client.new(access_token: "<YOUR_PERSONL_ACCESS_TOKEN>")
client.sources # => BaseCRM::SourcesService

Actions:

  • Retrieve all sources - client.sources.all
  • Create a source - client.sources.create
  • Retrieve a single source - client.sources.find
  • Update a source - client.sources.update
  • Delete a source - client.sources.destroy

Stage

client = BaseCRM::Client.new(access_token: "<YOUR_PERSONL_ACCESS_TOKEN>")
client.stages # => BaseCRM::StagesService

Actions:

  • Retrieve all stages - client.stages.all

Tag

client = BaseCRM::Client.new(access_token: "<YOUR_PERSONL_ACCESS_TOKEN>")
client.tags # => BaseCRM::TagsService

Actions:

  • Retrieve all tags - client.tags.all
  • Create a tag - client.tags.create
  • Retrieve a single tag - client.tags.find
  • Update a tag - client.tags.update
  • Delete a tag - client.tags.destroy

Task

client = BaseCRM::Client.new(access_token: "<YOUR_PERSONL_ACCESS_TOKEN>")
client.tasks # => BaseCRM::TasksService

Actions:

  • Retrieve all tasks - client.tasks.all
  • Create a task - client.tasks.create
  • Retrieve a single task - client.tasks.find
  • Update a task - client.tasks.update
  • Delete a task - client.tasks.destroy

User

client = BaseCRM::Client.new(access_token: "<YOUR_PERSONL_ACCESS_TOKEN>")
client.users # => BaseCRM::UsersService

Actions:

  • Retrieve all users - client.users.all
  • Retrieve a single user - client.users.find
  • Retrieve an authenticating user - client.users.self

License

MIT

Bug Reports

Report here.

Contact

BaseCRM developers (developers@getbase.com)