CheckHim Ruby SDK

Official Ruby client for the CheckHim Number Verification API.

Key Features

  • Simple, expressive API
  • Robust, typed error mapping
  • Lightweight (no heavy HTTP dependencies)
  • Built-in timeouts and sensible defaults
  • Thread-safe client (no global mutable state)

Installation

Add to your Gemfile:

gem 'checkhim'

Or install directly:

gem install checkhim

Quick Start

require 'checkhim'

client = CheckHim::Client.new('ch_test_your_api_key')

begin
  result = client.verify('+5511984339000')
  puts "Valid: #{result.valid?} Carrier: #{result.carrier}"
rescue CheckHim::Error => e
  warn "Error: #{e.message} (#{e.code})"
end

Successful Response

{
  "carrier": "Oi",
  "valid": true
}

Error Response Format

{
  "error": "verification failed: Network is forbidden (code: 6)",
  "code": "REJECTED_NETWORK"
}

Error Classes

All errors inherit from CheckHim::Error.

Code Class Meaning
REJECTED_NETWORK CheckHim::RejectedNetwork Network forbidden
REJECTED_PREFIX_MISSING CheckHim::RejectedPrefixMissing Missing country/area prefix
REJECTED_FORMAT CheckHim::RejectedFormat Invalid formatting
REJECTED_SUBSCRIBER_ABSENT CheckHim::RejectedSubscriberAbsent Subscriber unreachable/absent
REJECTED_UNKNOWN_SUBSCRIBER CheckHim::RejectedUnknownSubscriber Unknown subscriber
REJECTED_UNDELIVERABLE CheckHim::RejectedUndeliverable Undeliverable route
UNDELIVERABLE_NOT_DELIVERED CheckHim::UndeliverableNotDelivered Inactive or not delivered
TEMPORARY_FAILURE CheckHim::TemporaryFailure Transient failure; retry later
SERVICE_UNAVAILABLE CheckHim::ServiceUnavailable Upstream service unavailable

Other unexpected 4xx/5xx responses raise CheckHim::APIError. Network issues raise CheckHim::NetworkError.

Handling Errors

begin
  client.verify('+244921000111')
rescue CheckHim::RejectedNetwork => e
  # handle specific code
rescue CheckHim::TemporaryFailure
  sleep 2; retry
rescue CheckHim::Error => e
  warn "General failure: #{e.message} (#{e.code})"
end

Configuration Options

client = CheckHim::Client.new(
  'ch_live_key',
  open_timeout: 3,
  read_timeout: 8,
  endpoint: 'https://api.checkhim.tech/api/v1'
)

Versioning

This library follows semantic versioning: MAJOR.MINOR.PATCH.

Development

git clone https://github.com/checkhim/ruby-sdk.git
cd ruby-sdk
bundle install
rake spec

Contributing

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/improve-thing)
  3. Add tests for your change
  4. Ensure rake spec passes and add documentation
  5. Submit a pull request

Security

Do not open public issues for sensitive security topics. Email: [email protected]

License

Released under the MIT License. See LICENSE for details.