Business Central API Library

This library is designed to help ruby/rails based applications communicate with the publicly available API for dynamics 365 business central.

If you are unfamiliar with the business central API, you should first read the documentation located at


Add this line to your application's Gemfile:

gem 'business-central'

And then execute:

$ bundle

Or install it yourself as:

$ gem install business-central

Basic Usage

This gem supports both basic and OAuth2 authentication methods:

require 'business_central'

client =
    username: '<username>',                 # Basic authentication username
    password: '<password>',                 # Basic authentication password
    url: '<url>',                           # URL for API defaults to
    web_service_url: '<url>',               # URL for custom web services defaults to 
    application_id: '<application_id>',     # Oauth2 authentication application ID
    secret_key: '<application_secret_key>', # OAuth2 authentication application secret key
    oauth2_login_url: '<url>',              # OAuth2 authentication login URL defaults to
    default_company_id: '<company_id>',     # Default company ID used in all requests (if required)
    debug: false                            # Output requests to console

Basic Authentication:

require 'business_central'

client =
    username: '<username>',
    password: '<password>',
    url: '<url>',
    default_company_id: '11111111-2222-3333-4444-555555555555'

Oauth2 Authentication

require 'business_central'

# Create client - used to connect to the API
client =
    application_id: '<application_id>',
    secret_key: '<application_secret_key>',
    url: '<url>',
    default_company_id: '11111111-2222-3333-4444-555555555555'

# Controller endpoint 1
client.authorize({ state: '1234' }, oauth_authorize_callback: redirect_url )

# Redirect URL endpoint - safely store the token to be re-used later
token = client.request_token(params[:code], oauth_token_callback: redirect_url)

    token: token.token,
    refresh_token: token.refresh_token,
    expires_at: DateTime.current + 3600,
    expires_in: 3600

Calling objects

    # Find all vendors

    # Find vendor by ID

    # Query vendor by display name
    client.vendors.where("displayName eq 'First Up Consultants'")

    # Create a new vendor
    client.vendors.create({ display_name: 'hello testing' })

    # Update an existing vendor by ID
    client.vendors.update('39a7ef39-ba0f-ed11-90ed-00224895e26b', { phone_number: '1112' })

    # Delete a vendor

    # ---------

    # Find all vendor default dimensions
    client.vendors(id: '557d12d7-25f5-ec11-82f1-000d3a299c8c').default_dimensions.all

    # Query vendor default dimensions by dimension code
    client.vendors(id: '557d12d7-25f5-ec11-82f1-000d3a299c8c').default_dimensions.where("dimensionCode eq 'DEPARTMENT'")

    # Create a new vendor default dimension
    client.vendors(id: '557d12d7-25f5-ec11-82f1-000d3a299c8c').default_dimensions.create({ dimension_code: 'DEPARTMENT' })

    # Update an existing vendor default dimension
    client.vendors(id: '557d12d7-25f5-ec11-82f1-000d3a299c8c').default_dimensions.update('6576ecf4-25f5-ec11-82f1-000d3a299c8c', { dimension_code: 'NEW_DEPARTMENT' })

    # Delete a vendor default dimension
    client.vendors(id: '557d12d7-25f5-ec11-82f1-000d3a299c8c').default_dimensions.destroy('6576ecf4-25f5-ec11-82f1-000d3a299c8c')
rescue StandardError => e
  puts e.message
rescue BusinessCentral::ApiException => e
  puts e.message

All objects should be callable, assuming the endpoint exists.

OData Web Services

require 'business_central'

client =
    username: '<username>',
    password: '<password>',
    web_service_url: '<url>'

# Query a record 
company = client.web_service.object("Company('?')/Purchase_Order", 'My Company').get

# Create a record
client.web_service.object("Company('?')/Purchase_Order", 'My Company').post({})

# Update a record
client.web_service.object("Company('?')/Purchase_Order", 'My Company').patch({})

# Delete a record
client.web_service.object("Company('?')/Purchase_Order", 'My Company').delete


After checking out the repo, run bundle install to install dependencies. Then, run rake test to run the tests.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to


Bug reports and pull requests are welcome on GitHub at


The gem is available as open source under the terms of the MIT License.