kombo

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

Note

The Kombo Ruby SDK is currently in beta. The core API structure, methods, and input/output objects are considered stable. We may still make minor adjustments, but all changes will be clearly documented in the changelog. We do not foresee any blockers for production use.

Table of Contents

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

SDK Installation

The SDK can be installed using RubyGems:

gem install kombo

SDK Example Usage

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

Specifying an integration ID

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

Region Selection

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:

Example

require 'kombo'

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

Available Resources and Operations

Available methods

Assessment

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

Ats

• 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

Connect

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

General

• 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

Hris

• 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

Pagination

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

Error Handling

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:

Property	Type	Description
message	string	The error message
status_code	int	The HTTP status code
raw_response	Faraday::Response	The raw HTTP response
body	string	The response content

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:

Error Type	Status Code	Content Type
Models::Errors::KomboGeneralError	default	application/json
Errors::APIError	4XX, 5XX	*/*

Example

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

Custom HTTP Client

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

Debugging

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.

Requirements

This SDK supports Ruby 3.0 and above.

Development

Contributions

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.

SDK Created by Speakeasy