{"id":13879969,"url":"https://github.com/zendesk/basecrm-ruby","last_synced_at":"2025-10-11T06:07:47.634Z","repository":{"id":7625134,"uuid":"8984456","full_name":"zendesk/basecrm-ruby","owner":"zendesk","description":"Base CRM API Client","archived":false,"fork":false,"pushed_at":"2022-07-01T14:51:34.000Z","size":183,"stargazers_count":28,"open_issues_count":14,"forks_count":31,"subscribers_count":87,"default_branch":"master","last_synced_at":"2025-10-07T12:44:52.228Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zendesk.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-03-24T10:27:25.000Z","updated_at":"2024-10-23T06:25:14.000Z","dependencies_parsed_at":"2022-09-05T04:31:04.749Z","dependency_job_id":null,"html_url":"https://github.com/zendesk/basecrm-ruby","commit_stats":null,"previous_names":[],"tags_count":26,"template":false,"template_full_name":null,"purl":"pkg:github/zendesk/basecrm-ruby","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zendesk%2Fbasecrm-ruby","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zendesk%2Fbasecrm-ruby/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zendesk%2Fbasecrm-ruby/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zendesk%2Fbasecrm-ruby/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zendesk","download_url":"https://codeload.github.com/zendesk/basecrm-ruby/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zendesk%2Fbasecrm-ruby/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279006324,"owners_count":26084085,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-11T02:00:06.511Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-06T08:02:41.432Z","updated_at":"2025-10-11T06:07:47.618Z","avatar_url":"https://github.com/zendesk.png","language":"Ruby","funding_links":[],"categories":["Ruby"],"sub_categories":[],"readme":"# basecrm-ruby\n\nBaseCRM Official API V2 library client for ruby\n\n## Installation\n\nMake sure you have [rubygems](https://rubygems.org) installed.\n\nThe gem is available via Rubygems. To install, use the following command:\n\n```ruby\ngem install basecrm\n```\n\nIf you use Bundler, put the line below in your Gemfile:\n\n```ruby\ngem 'basecrm'\n```\n\nTo get the latest version, put this in your Gemfile:\n\n```ruby\ngem 'basecrm', :git =\u003e 'git://github.com/zendesk/basecrm-ruby.git'\n```\n\n## Usage\n\n```ruby\nrequire \"basecrm\"\n\n# Then we instantiate a client (as shown below)\n```\n\n### Build a client\n__Using this api without authentication gives an error__\n\n```ruby\nclient = BaseCRM::Client.new(access_token: \"\u003cYOUR_PERSONAL_ACCESS_TOKEN\u003e\")\n```\n\n### Client Options\n\nThe following options are available while instantiating a client:\n\n * __access_token__: Personal access token\n * __base_url__: Base url for the api\n * __user_agent__: Default user-agent for all requests\n * __timeout__: Request timeout\n * __verbose__: Verbose/debug mode\n * __logger__: Logger used in verbose mode\n * __max_retry__: Number of retries on failed requests. Passed to Faraday\n * __retry_statuses__: By default only timeout error will be retries. This allows to retry on specific HTTP statuses. Passed to Faraday\n\n### Architecture\n\nThe library follows few architectural principles you should understand before digging deeper.\n1. Interactions with resources are done via service objects.\n2. Service objects are exposed as methods on client instances.\n3. Service objects expose resource-oriented actions.\n4. Actions return Plain Old Ruby Objects.\n\nFor example, to interact with deals API you will use `DealsService`, which you can get if you call:\n\n```ruby\nclient = BaseCRM::Client.new(access_token: \"\u003cYOUR_PERSONAL_ACCESS_TOKEN\u003e\")\nclient.deals # =\u003e BaseCRM::DealsService\n```\n\nWhen you want to fetch **all** resources you will use `#all` method which returns paginated resource (which implements Enumerable):\n\n```ruby\nclient = BaseCRM::Client.new(access_token: \"\u003cYOUR_PERSONAL_ACCESS_TOKEN\u003e\")\nclient.deals.all.map { |deal| deal.name } # =\u003e Array\u003cString\u003e\n```\n\nTo retrieve list of resources and use filtering you will call `#where` method:\n\n```ruby\nclient = BaseCRM::Client.new(access_token: \"\u003cYOUR_PERSONAL_ACCESS_TOKEN\u003e\")\nclient.deals.where(organization_id: google.id, hot: true) # =\u003e Array\u003cBaseCRM::Deal\u003e\n```\n\nTo find a resource by it's unique identifier use `#find` method:\n\n```ruby\nclient = BaseCRM::Client.new(access_token: \"\u003cYOUR_PERSONAL_ACCESS_TOKEN\u003e\")\nclient.deals.find(id) # =\u003e BaseCRM::Deal\n```\n\nWhen 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:\n\n```ruby\nclient = BaseCRM::Client.new(access_token: \"\u003cYOUR_PERSONAL_ACCESS_TOKEN\u003e\")\ncoffeeshop = client.contacts.where(name: \"Coffee Shop\")\n\ndeal = client.deals.create(name: \"Website redesign\", contact_id: coffeeshop.id)\ndeal.value = BigDecimal(\"1000.99\")\ndeal.currency = \"USD\"\n\nclient.deals.update(deal) # =\u003e BaseCRM::Deal\n```\n\nTo destroy a resource use `#destroy` method:\n\n```ruby\nclient = BaseCRM::Client.new(access_token: \"\u003cYOUR_PERSONAL_ACCESS_TOKEN\u003e\")\nclient.deals.destroy(id) # =\u003e true\n```\n\nThere other non-CRUD operations supported as well. Please contact corresponding service files for in-depth documentation.\n\n### Full example\n\nCreate a new organization and after that change it's attributes (website).\n\n```ruby\nclient = BaseCRM::Client.new(access_token: \"\u003cYOUR_PERSONAL_ACCESS_TOKEN\u003e\")\nlead = client.leads.create(organization_name: \"Design service company\")\n\nlead.website = \"http://www.designservices.com\"\nclient.leads.update(lead)\n```\n\n## Sync API\n\nThe following sample code shows how to perform a full synchronization flow using high-level wrapper.\n\nFirst of all you need an instance of `BaseCRM::Client`. High-level `BaseCRM::Sync` wrapper is using `BaseCRM::SyncService` to interact with the Sync API.\nIn 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.\n\n```ruby\nclient = BaseCRM::Client.new(access_token: \"\u003cYOUR_PERSONAL_ACCESS_TOKEN\u003e\")\nsync = BaseCRM::Sync.new(client: client, device_uuid: \"\u003cYOUR_DEVICES_UUID\u003e\")\n```\n\nNow 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.\n\n```ruby\nsync.fetch do |meta, resource|\n  options = {\n    table: meta.type,\n    statement: meta.sync.event_type,\n    properties: resource\n  }\n\n  DB.execute(options) ? meta.sync.ack : meta.sync.nack\nend\n```\n\nNotice that you must call either `#ack` or `#nack` method on an instance of `BaseCRM::SyncMeta`.\n\n## Resources and actions\n\nDocumentation for every action can be found in corresponding service files under `lib/basecrm/services` directory.\n\n### Account\n\n```ruby\nclient = BaseCRM::Client.new(access_token: \"\u003cYOUR_PERSONAL_ACCESS_TOKEN\u003e\")\nclient.accounts # =\u003e BaseCRM::AccountsService\n```\n\nActions:\n* Retrieve account details - `client.accounts.self`\n\n### AssociatedContact\n\n```ruby\nclient = BaseCRM::Client.new(access_token: \"\u003cYOUR_PERSONAL_ACCESS_TOKEN\u003e\")\nclient.associated_contacts # =\u003e BaseCRM::AssociatedContactsService\n```\n\nActions:\n* Retrieve deal's associated contacts - `client.associated_contacts.all`\n* Create an associated contact - `client.associated_contacts.create`\n* Remove an associated contact - `client.associated_contacts.destroy`\n\n### Call\n\n```ruby\nclient = BaseCRM::Client.new(access_token: \"\u003cYOUR_PERSONAL_ACCESS_TOKEN\u003e\")\nclient.calls # =\u003e BaseCRM::CallsService\n```\n\nActions:\n* Retrieve all calls - `client.calls.all`\n* Create a call - `client.calls.create`\n* Retrieve a single call - `client.calls.find`\n* Update a call - `client.calls.update`\n* Delete a call - `client.calls.destroy`\n\n### CallOutcome\n\n```ruby\nclient = BaseCRM::Client.new(access_token: \"\u003cYOUR_PERSONAL_ACCESS_TOKEN\u003e\")\nclient.call_outcomes # =\u003e BaseCRM::CallOutcomesService\n```\n\nActions:\n* Retrieve all call outcomes - `client.call_outcomes.all`\n\n### Contact\n\n```ruby\nclient = BaseCRM::Client.new(access_token: \"\u003cYOUR_PERSONAL_ACCESS_TOKEN\u003e\")\nclient.contacts # =\u003e BaseCRM::ContactsService\n```\n\nActions:\n* Retrieve all contacts - `client.contacts.all`\n* Create a contact - `client.contacts.create`\n* Retrieve a single contact - `client.contacts.find`\n* Update a contact - `client.contacts.update`\n* Delete a contact - `client.contacts.destroy`\n\n### Deal\n\n```ruby\nclient = BaseCRM::Client.new(access_token: \"\u003cYOUR_PERSONAL_ACCESS_TOKEN\u003e\")\nclient.deals # =\u003e BaseCRM::DealsService\n```\n\nActions:\n* Retrieve all deals - `client.deals.all`\n* Create a deal - `client.deals.create`\n* Retrieve a single deal - `client.deals.find`\n* Update a deal - `client.deals.update`\n* Delete a deal - `client.deals.destroy`\n\n**A note about deal value**\n\nIt is prefered to use a BigDecimal when creating or modyfing a deal value. This guarantees correct precision\n\n```\ndeal.value = BigDecimal(\"1000.98\")\n```\n\nYou should not be using floats as it may result in precision loss.\n\n```\ndeal.value = 1000.98\n```\n\n### DealSource\n\n```ruby\nclient = BaseCRM::Client.new(access_token: \"\u003cYOUR_PERSONAL_ACCESS_TOKEN\u003e\")\nclient.deal_sources # =\u003e BaseCRM::DealSourcesService\n```\n\nActions:\n* Retrieve all sources - `client.deal_sources.all`\n* Create a new source - `client.deal_sources.create`\n* Retrieve a single source - `client.deal_sources.find`\n* Update a source - `client.deal_sources.update`\n* Delete a source - `client.deal_sources.destroy`\n\n### DealUnqualifiedReason\n\n```ruby\nclient = BaseCRM::Client.new(access_token: \"\u003cYOUR_PERSONAL_ACCESS_TOKEN\u003e\")\nclient.deal_unqualified_reasons # =\u003e BaseCRM::DealUnqualifiedReasonsService\n```\n\nActions:\n* Retrieve all deal unqualified reasons - `client.deal_unqualified_reasons.all`\n* Create a deal unqualified reason - `client.deal_unqualified_reasons.create`\n* Retrieve a single deal unqualified reason - `client.deal_unqualified_reasons.find`\n* Update a deal unqualified reason - `client.deal_unqualified_reasons.update`\n* Delete a deal unqualified reason - `client.deal_unqualified_reasons.destroy`\n\n### Lead\n\n```ruby\nclient = BaseCRM::Client.new(access_token: \"\u003cYOUR_PERSONAL_ACCESS_TOKEN\u003e\")\nclient.leads # =\u003e BaseCRM::LeadsService\n```\n\nActions:\n* Retrieve all leads - `client.leads.all`\n* Create a lead - `client.leads.create`\n* Retrieve a single lead - `client.leads.find`\n* Update a lead - `client.leads.update`\n* Delete a lead - `client.leads.destroy`\n\n### LeadSource\n\n```ruby\nclient = BaseCRM::Client.new(access_token: \"\u003cYOUR_PERSONAL_ACCESS_TOKEN\u003e\")\nclient.lead_sources # =\u003e BaseCRM::LeadSourcesService\n```\n\nActions:\n* Retrieve all sources - `client.lead_sources.all`\n* Create a new source - `client.lead_sources.create`\n* Retrieve a single source - `client.lead_sources.find`\n* Update a source - `client.lead_sources.update`\n* Delete a source - `client.lead_sources.destroy`\n\n### LeadUnqualifiedReason\n\n```ruby\nclient = BaseCRM::Client.new(access_token: \"\u003cYOUR_PERSONAL_ACCESS_TOKEN\u003e\")\nclient.lead_unqualified_reasons # =\u003e BaseCRM::LeadUnqualifiedReasonsService\n```\n\nActions:\n* Retrieve all lead unqualified reasons - `client.lead_unqualified_reasons.all`\n\n### LineItem\n\n```ruby\nclient = BaseCRM::Client.new(access_token: \"\u003cYOUR_PERSONAL_ACCESS_TOKEN\u003e\")\nclient.line_items # =\u003e BaseCRM::LineItemsService\n```\n\nActions:\n* Retrieve order's line items - `client.line_items.all`\n* Create a line item - `client.line_items.create`\n* Retrieve a single line item - `client.line_items.find`\n* Delete a line item - `client.line_items.destroy`\n\n### LossReason\n\n```ruby\nclient = BaseCRM::Client.new(access_token: \"\u003cYOUR_PERSONAL_ACCESS_TOKEN\u003e\")\nclient.loss_reasons # =\u003e BaseCRM::LossReasonsService\n```\n\nActions:\n* Retrieve all reasons - `client.loss_reasons.all`\n* Create a loss reason - `client.loss_reasons.create`\n* Retrieve a single reason - `client.loss_reasons.find`\n* Update a loss reason - `client.loss_reasons.update`\n* Delete a reason - `client.loss_reasons.destroy`\n\n### Note\n\n```ruby\nclient = BaseCRM::Client.new(access_token: \"\u003cYOUR_PERSONAL_ACCESS_TOKEN\u003e\")\nclient.notes # =\u003e BaseCRM::NotesService\n```\n\nActions:\n* Retrieve all notes - `client.notes.all`\n* Create a note - `client.notes.create`\n* Retrieve a single note - `client.notes.find`\n* Update a note - `client.notes.update`\n* Delete a note - `client.notes.destroy`\n\n### Order\n\n```ruby\nclient = BaseCRM::Client.new(access_token: \"\u003cYOUR_PERSONAL_ACCESS_TOKEN\u003e\")\nclient.orders # =\u003e BaseCRM::OrdersService\n```\n\nActions:\n* Retrieve all orders - `client.orders.all`\n* Create an order - `client.orders.create`\n* Retrieve a single order - `client.orders.find`\n* Update an order - `client.orders.update`\n* Delete an order - `client.orders.destroy`\n\n### Pipeline\n\n```ruby\nclient = BaseCRM::Client.new(access_token: \"\u003cYOUR_PERSONAL_ACCESS_TOKEN\u003e\")\nclient.pipelines # =\u003e BaseCRM::PipelinesService\n```\n\nActions:\n* Retrieve all pipelines - `client.pipelines.all`\n\n### Product\n\n```ruby\nclient = BaseCRM::Client.new(access_token: \"\u003cYOUR_PERSONAL_ACCESS_TOKEN\u003e\")\nclient.products # =\u003e BaseCRM::ProductsService\n```\n\nActions:\n* Retrieve all products - `client.products.all`\n* Create a product - `client.products.create`\n* Retrieve a single product - `client.products.find`\n* Update a product - `client.products.update`\n* Delete a product - `client.products.destroy`\n\n### Source (Deprecated, use LeadSource or DealSource instead)\n\n```ruby\nclient = BaseCRM::Client.new(access_token: \"\u003cYOUR_PERSONAL_ACCESS_TOKEN\u003e\")\nclient.sources # =\u003e BaseCRM::SourcesService\n```\n\nActions:\n* Retrieve all sources - `client.sources.all`\n* Create a source - `client.sources.create`\n* Retrieve a single source - `client.sources.find`\n* Update a source - `client.sources.update`\n* Delete a source - `client.sources.destroy`\n\n### Stage\n\n```ruby\nclient = BaseCRM::Client.new(access_token: \"\u003cYOUR_PERSONAL_ACCESS_TOKEN\u003e\")\nclient.stages # =\u003e BaseCRM::StagesService\n```\n\nActions:\n* Retrieve all stages - `client.stages.all`\n\n### Tag\n\n```ruby\nclient = BaseCRM::Client.new(access_token: \"\u003cYOUR_PERSONAL_ACCESS_TOKEN\u003e\")\nclient.tags # =\u003e BaseCRM::TagsService\n```\n\nActions:\n* Retrieve all tags - `client.tags.all`\n* Create a tag - `client.tags.create`\n* Retrieve a single tag - `client.tags.find`\n* Update a tag - `client.tags.update`\n* Delete a tag - `client.tags.destroy`\n\n### Task\n\n```ruby\nclient = BaseCRM::Client.new(access_token: \"\u003cYOUR_PERSONAL_ACCESS_TOKEN\u003e\")\nclient.tasks # =\u003e BaseCRM::TasksService\n```\n\nActions:\n* Retrieve all tasks - `client.tasks.all`\n* Create a task - `client.tasks.create`\n* Retrieve a single task - `client.tasks.find`\n* Update a task - `client.tasks.update`\n* Delete a task - `client.tasks.destroy`\n\n### TextMessage\n\n```ruby\nclient = BaseCRM::Client.new(access_token: \"\u003cYOUR_PERSONAL_ACCESS_TOKEN\u003e\")\nclient.text_messages # =\u003e BaseCRM::TextMessagesService\n```\n\nActions:\n* Retrieve text messages - `client.text_messages.all`\n* Retrieve a single text message - `client.text_messages.find`\n\n### User\n\n```ruby\nclient = BaseCRM::Client.new(access_token: \"\u003cYOUR_PERSONAL_ACCESS_TOKEN\u003e\")\nclient.users # =\u003e BaseCRM::UsersService\n```\n\nActions:\n* Retrieve all users - `client.users.all`\n* Retrieve a single user - `client.users.find`\n* Retrieve an authenticating user - `client.users.self`\n\n### Visit\n\n```ruby\nclient = BaseCRM::Client.new(access_token: \"\u003cYOUR_PERSONAL_ACCESS_TOKEN\u003e\")\nclient.visits # =\u003e BaseCRM::VisitsService\n```\n\nActions:\n* Retrieve visits - `client.visits.all`\n\n### VisitOutcome\n\n```ruby\nclient = BaseCRM::Client.new(access_token: \"\u003cYOUR_PERSONAL_ACCESS_TOKEN\u003e\")\nclient.visit_outcomes # =\u003e BaseCRM::VisitOutcomesService\n```\n\nActions:\n* Retrieve visit outcomes - `client.visit_outcomes.all`\n\n## Bug Reports\nReport [here](https://github.com/zendesk/basecrm-ruby/issues).\n\n## Releasing new version of gem\n\n1. Update version [lib/basecrm/version.rb](lib/basecrm/version.rb) and [VERSION](VERSION) and push to `master`\n2. Create new GitHub release with tag name starting with `v` and the version, for example `v1.0.0`\n3. Gem will be automatically built and pushed to rubygems.org with GitHub Action\n\n## Copyright and license\n\nCopyright 2013 Zendesk\n\nLicensed under the [Apache License, Version 2.0](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzendesk%2Fbasecrm-ruby","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzendesk%2Fbasecrm-ruby","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzendesk%2Fbasecrm-ruby/lists"}