Developer-friendly & type-safe Ruby SDK for the Kombo Unified API.

• kombo
  • SDK Installation
  • SDK Example Usage
  • Region Selection
  • Available Resources and Operations
  • Pagination
  • Error Handling
  • Custom HTTP Client
  • Debugging
  • Requirements
• Development
  • Contributions

The SDK can be installed using RubyGems:

gem install kombo

require 'kombo'

Models = ::Kombo::Models
s = ::Kombo::Kombo.new(
  security: Models::Shared::Security.new(
    api_key: '<YOUR_BEARER_TOKEN_HERE>',
  ),
)

res = s.general.check_api_key()

unless res.get_check_api_key_positive_response.nil?
  # handle response
end

The majority of Kombo API endpoints are for interacting with a single "integration" (i.e., a single connection to one of your customers' systems). For these endpoints, specify the integration_id when initializing the SDK:

require 'kombo'

Models = ::Kombo::Models
s = ::Kombo::Kombo.new(
  integration_id: 'workday:HWUTwvyx2wLoSUHphiWVrp28',
  security: Models::Shared::Security.new(
    api_key: '<YOUR_BEARER_TOKEN_HERE>',
  ),
)

res = s.hris.get_employees()

unless res.get_employees_positive_response.nil?
  # handle response
end

The Kombo platform is available in two regions: Europe and United States.

By default, the SDK uses the EU region. If you use the US region (hosted at api.us.kombo.dev), set the server option when initializing the SDK:

require 'kombo'

Models = ::Kombo::Models
s = ::Kombo::Kombo.new(
  server: :us,
  security: Models::Shared::Security.new(
    api_key: '<YOUR_BEARER_TOKEN_HERE>',
  ),
)

• get_packages - Get packages
• set_packages - Set packages
• get_open_orders - Get open orders
• update_order_result - Update order result

• get_applications - Get applications
• move_application_to_stage - Move application to stage
• add_application_result_link - Add result link to application
• add_application_note - Add note to application
• get_application_attachments - Get application attachments
• add_application_attachment - Add attachment to application
• reject_application - Reject application
• get_candidates - Get candidates
• create_candidate - Create candidate
• get_candidate_attachments - Get candidate attachments
• add_candidate_attachment - Add attachment to candidate
• add_candidate_result_link - Add result link to candidate
• add_candidate_tag - Add tag to candidate
• remove_candidate_tag - Remove tag from candidate
• get_tags - Get tags
• get_application_stages - Get application stages
• get_jobs - Get jobs
• create_application - Create application
• get_users - Get users
• get_offers - Get offers
• get_rejection_reasons - Get rejection reasons
• get_interviews - Get interviews
• import_tracked_application - Import tracked application

• create_connection_link - Create connection link
• get_integration_by_token - Get integration by token

• check_api_key - Check API key
• trigger_sync - Trigger sync
• send_passthrough_request - Send passthrough request
• delete_integration - Delete integration
• get_integration_details - Get integration details
• set_integration_enabled - Set integration enabled
• create_reconnection_link - Create reconnection link
• get_integration_fields - Get integration fields
• update_integration_field - Updates an integration fields passthrough setting
• get_custom_fields - Get custom fields with current mappings
• update_custom_field_mapping - Put custom field mappings
• get_tools - Get tools

• get_employees - Get employees
• get_employee_form - Get employee form
• create_employee_with_form - Create employee with form
• add_employee_document - Add document to employee
• get_employee_document_categories - Get employee document categories
• get_groups - Get groups
• get_employments - Get employments
• get_locations - Get work locations
• get_absence_types - Get absence types
• get_time_off_balances - Get time off balances
• get_absences - Get absences
• create_absence - Create absence
• delete_absence - Delete absence
• get_legal_entities - Get legal entities
• get_timesheets - Get timesheets
• get_performance_review_cycles - Get performance review cycles
• get_performance_reviews - Get performance reviews

Some of the endpoints in this SDK support pagination. You make your SDK calls as usual, but the returned response object also supports iteration so you can consume all pages in a loop.

Here's an example using get_integration_fields:

require 'kombo'

Models = ::Kombo::Models
s = ::Kombo::Kombo.new(
  security: Models::Shared::Security.new(
    api_key: '<YOUR_BEARER_TOKEN_HERE>',
  ),
)

result = s.general.get_integration_fields(integration_id: '<id>')

result.each do |page|
  puts page
end

Handling errors in this SDK should largely match your expectations. All operations return a response object or raise an error.

By default an API error will raise a Errors::APIError, which has the following properties:

When custom error responses are specified for an operation, the SDK may also throw their associated exception. You can refer to respective Errors tables in SDK docs for more details on possible exception types for each operation. For example, the check_api_key method throws the following exceptions:

require 'kombo'

Models = ::Kombo::Models
s = ::Kombo::Kombo.new(
      security: Models::Shared::Security.new(
        api_key: '<YOUR_BEARER_TOKEN_HERE>',
      ),
    )

begin
    res = s.general.check_api_key()

    unless res.get_check_api_key_positive_response.nil?
      # handle response
    end
rescue Models::Errors::KomboGeneralError => e
  # handle e.container data
  raise e
rescue Errors::APIError => e
  # handle default exception
  raise e
end

The Ruby SDK uses Faraday for HTTP. You can pass a custom connection when initializing the client if you need to customize behavior.

You can enable debug logging by configuring your logger and passing it to the SDK client when supported. Be careful not to log secrets (e.g. API keys) in production.

This SDK supports Ruby 3.0 and above.

While we value open-source contributions to this SDK, this library is generated programmatically. Any manual changes added to internal files will be overwritten on the next generation. We look forward to hearing your feedback. Feel free to open a PR or an issue with a proof of concept and we'll do our best to include it in a future release.