Project

checkhim

0.0
The project is in a healthy, maintained state
checkhimcheckhim/ruby-sdkHomepageDocumentationSource CodeBug TrackerWiki
Official, well-tested Ruby client for the CheckHim API enabling phone number verification with robust error handling.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
 Popularity
Downloads
491
Stars
1
Forks
0
Watchers
0
 Releases
Current version
0.1.0
Total releases
1
First release
2025-09-16
Latest release
2025-09-16
 Development
Primary Language
Ruby
Licenses
MIT
Average date of last 50 commits
2025-09-16
Reverse Dependencies
0

 Dependencies

Development

rake
~> 13.0
rspec
~> 3.12
rubocop
>= 1.50, < 2.0
webmock
~> 3.19

Runtime

json
>= 2.0
 Project Readme

CheckHim Ruby SDK

RubyGems.org Listing ยท Project Site

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: opensource@checkhim.tech

License

Released under the MIT License. See LICENSE for details.