BaseCRM Official API V2 library client for ruby
Make sure you have rubygems installed.
The gem is available via Rubygems. To install, use the following command:
geminstallbasecrmIf 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'require"basecrm"# Then we instantiate a client (as shown below)Using this api without authentication gives an error
client=BaseCRM::Client.new(access_token: "<YOUR_PERSONAL_ACCESS_TOKEN>")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
The library follows few architectural principles you should understand before digging deeper.
- Interactions with resources are done via service objects.
- Service objects are exposed as methods on client instances.
- Service objects expose resource-oriented actions.
- 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::DealsServiceWhen 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(access_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::DealWhen 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=BigDecimal("1000.99")deal.currency="USD"client.deals.update(deal)# => BaseCRM::DealTo destroy a resource use #destroy method:
client=BaseCRM::Client.new(access_token: "<YOUR_PERSONAL_ACCESS_TOKEN>")client.deals.destroy(id)# => trueThere other non-CRUD operations supported as well. Please contact corresponding service files for in-depth documentation.
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)The following sample code shows how to perform a full synchronization flow using high-level wrapper.
First of all you need an instance of BaseCRM::Client. High-level BaseCRM::Sync wrapper is using BaseCRM::SyncService to interact with the Sync API.
In addition to the client instance, you must provide a device’s UUID within device_uuid parameter. The device’s UUID must not change between synchronization sessions, otherwise the sync service will not recognize the device and will send all the data again.
client=BaseCRM::Client.new(access_token: "<YOUR_PERSONAL_ACCESS_TOKEN>")sync=BaseCRM::Sync.new(client: client,device_uuid: "<YOUR_DEVICES_UUID>")Now all you have to do is to call #fetch method and pass a block that you might use to store fetched data to a database.
sync.fetchdo |meta,resource|
options={table: meta.type,statement: meta.sync.event_type,properties: resource}DB.execute(options) ? meta.sync.ack : meta.sync.nackendNotice that you must call either #ack or #nack method on an instance of BaseCRM::SyncMeta.
Documentation for every action can be found in corresponding service files under lib/basecrm/services directory.
client=BaseCRM::Client.new(access_token: "<YOUR_PERSONAL_ACCESS_TOKEN>")client.accounts# => BaseCRM::AccountsServiceActions:
- Retrieve account details -
client.accounts.self
client=BaseCRM::Client.new(access_token: "<YOUR_PERSONAL_ACCESS_TOKEN>")client.associated_contacts# => BaseCRM::AssociatedContactsServiceActions:
- 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
client=BaseCRM::Client.new(access_token: "<YOUR_PERSONAL_ACCESS_TOKEN>")client.calls# => BaseCRM::CallsServiceActions:
- Retrieve all calls -
client.calls.all - Create a call -
client.calls.create - Retrieve a single call -
client.calls.find - Update a call -
client.calls.update - Delete a call -
client.calls.destroy
client=BaseCRM::Client.new(access_token: "<YOUR_PERSONAL_ACCESS_TOKEN>")client.call_outcomes# => BaseCRM::CallOutcomesServiceActions:
- Retrieve all call outcomes -
client.call_outcomes.all
client=BaseCRM::Client.new(access_token: "<YOUR_PERSONAL_ACCESS_TOKEN>")client.contacts# => BaseCRM::ContactsServiceActions:
- 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
client=BaseCRM::Client.new(access_token: "<YOUR_PERSONAL_ACCESS_TOKEN>")client.deals# => BaseCRM::DealsServiceActions:
- 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
A note about deal value
It is prefered to use a BigDecimal when creating or modyfing a deal value. This guarantees correct precision
deal.value = BigDecimal("1000.98")
You should not be using floats as it may result in precision loss.
deal.value = 1000.98
client=BaseCRM::Client.new(access_token: "<YOUR_PERSONAL_ACCESS_TOKEN>")client.deal_sources# => BaseCRM::DealSourcesServiceActions:
- Retrieve all sources -
client.deal_sources.all - Create a new source -
client.deal_sources.create - Retrieve a single source -
client.deal_sources.find - Update a source -
client.deal_sources.update - Delete a source -
client.deal_sources.destroy
client=BaseCRM::Client.new(access_token: "<YOUR_PERSONAL_ACCESS_TOKEN>")client.deal_unqualified_reasons# => BaseCRM::DealUnqualifiedReasonsServiceActions:
- Retrieve all deal unqualified reasons -
client.deal_unqualified_reasons.all - Create a deal unqualified reason -
client.deal_unqualified_reasons.create - Retrieve a single deal unqualified reason -
client.deal_unqualified_reasons.find - Update a deal unqualified reason -
client.deal_unqualified_reasons.update - Delete a deal unqualified reason -
client.deal_unqualified_reasons.destroy
client=BaseCRM::Client.new(access_token: "<YOUR_PERSONAL_ACCESS_TOKEN>")client.leads# => BaseCRM::LeadsServiceActions:
- 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
client=BaseCRM::Client.new(access_token: "<YOUR_PERSONAL_ACCESS_TOKEN>")client.lead_sources# => BaseCRM::LeadSourcesServiceActions:
- Retrieve all sources -
client.lead_sources.all - Create a new source -
client.lead_sources.create - Retrieve a single source -
client.lead_sources.find - Update a source -
client.lead_sources.update - Delete a source -
client.lead_sources.destroy
client=BaseCRM::Client.new(access_token: "<YOUR_PERSONAL_ACCESS_TOKEN>")client.lead_unqualified_reasons# => BaseCRM::LeadUnqualifiedReasonsServiceActions:
- Retrieve all lead unqualified reasons -
client.lead_unqualified_reasons.all
client=BaseCRM::Client.new(access_token: "<YOUR_PERSONAL_ACCESS_TOKEN>")client.line_items# => BaseCRM::LineItemsServiceActions:
- Retrieve order's line items -
client.line_items.all - Create a line item -
client.line_items.create - Retrieve a single line item -
client.line_items.find - Delete a line item -
client.line_items.destroy
client=BaseCRM::Client.new(access_token: "<YOUR_PERSONAL_ACCESS_TOKEN>")client.loss_reasons# => BaseCRM::LossReasonsServiceActions:
- 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
client=BaseCRM::Client.new(access_token: "<YOUR_PERSONAL_ACCESS_TOKEN>")client.notes# => BaseCRM::NotesServiceActions:
- 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
client=BaseCRM::Client.new(access_token: "<YOUR_PERSONAL_ACCESS_TOKEN>")client.orders# => BaseCRM::OrdersServiceActions:
- Retrieve all orders -
client.orders.all - Create an order -
client.orders.create - Retrieve a single order -
client.orders.find - Update an order -
client.orders.update - Delete an order -
client.orders.destroy
client=BaseCRM::Client.new(access_token: "<YOUR_PERSONAL_ACCESS_TOKEN>")client.pipelines# => BaseCRM::PipelinesServiceActions:
- Retrieve all pipelines -
client.pipelines.all
client=BaseCRM::Client.new(access_token: "<YOUR_PERSONAL_ACCESS_TOKEN>")client.products# => BaseCRM::ProductsServiceActions:
- Retrieve all products -
client.products.all - Create a product -
client.products.create - Retrieve a single product -
client.products.find - Update a product -
client.products.update - Delete a product -
client.products.destroy
client=BaseCRM::Client.new(access_token: "<YOUR_PERSONAL_ACCESS_TOKEN>")client.sources# => BaseCRM::SourcesServiceActions:
- 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
client=BaseCRM::Client.new(access_token: "<YOUR_PERSONAL_ACCESS_TOKEN>")client.stages# => BaseCRM::StagesServiceActions:
- Retrieve all stages -
client.stages.all
client=BaseCRM::Client.new(access_token: "<YOUR_PERSONAL_ACCESS_TOKEN>")client.tags# => BaseCRM::TagsServiceActions:
- 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
client=BaseCRM::Client.new(access_token: "<YOUR_PERSONAL_ACCESS_TOKEN>")client.tasks# => BaseCRM::TasksServiceActions:
- 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
client=BaseCRM::Client.new(access_token: "<YOUR_PERSONAL_ACCESS_TOKEN>")client.text_messages# => BaseCRM::TextMessagesServiceActions:
- Retrieve text messages -
client.text_messages.all - Retrieve a single text message -
client.text_messages.find
client=BaseCRM::Client.new(access_token: "<YOUR_PERSONAL_ACCESS_TOKEN>")client.users# => BaseCRM::UsersServiceActions:
- Retrieve all users -
client.users.all - Retrieve a single user -
client.users.find - Retrieve an authenticating user -
client.users.self
client=BaseCRM::Client.new(access_token: "<YOUR_PERSONAL_ACCESS_TOKEN>")client.visits# => BaseCRM::VisitsServiceActions:
- Retrieve visits -
client.visits.all
client=BaseCRM::Client.new(access_token: "<YOUR_PERSONAL_ACCESS_TOKEN>")client.visit_outcomes# => BaseCRM::VisitOutcomesServiceActions:
- Retrieve visit outcomes -
client.visit_outcomes.all
MIT
Report here.
BaseCRM developers (developers@getbase.com)