Vericred

A client gem to interact with the Vericred API. It provides useful helpers for:

• Futures
• Sideloading data
• Pagination (TODO)

Full generated API docs here. Documentation of the REST API itself here.

Add this line to your application's Gemfile:

gem 'vericred'

And then execute:

$ bundle

Or install it yourself as:

$ gem install vericred

Add a configuration block in config/initializers/vericred.rb

Vericred.configure do |config|
  config.api_key = ENV['VERICRED_API_KEY']
end

Vericred::Provider.find(npi) # => Vericred::Provider

Vericred::Provider.search(search_term: 'foo', zip_code: '11215')
  # => [Vericred::Provider, Vericred::Provider]

To return a total count, use the total method in place of the search method

Vericred::Provider.total(search_term: 'foo', zip_code: '11215')
  # => 100

When searching for Plans, you may supply one or more applicants to retrieve pricing. The smoker flag only need be supplied if it is true.

Vericred::Plan.search(
  zip_code: '11215',
  fips_code: '36047',
  market: 'individual',
  applicants: [
    { age: 31 },
    { age: 42, smoker: true }
  ],
  providers: [
    { npi: 1841293990 },
    { npi: 1740283779 }
  ]
)
  # => [Vericred::Plan<premium=401.23>, Vericred::Plan<premium=501.13>]

Sideloaded data is automatically added to the object found. For example, Vericred::ZipCounty includes Vericred::ZipCode and Vericred::County with the following response (simplified)

{
  "zip_counties": [{"id": 1, "zip_code_id": 2, "county_id": 3}],
  "counties": [{"id": 3, "name": "County"}],
  "zip_codes": [{"id": 2, "code": "12345"}]
}

When we .search for Vericred::ZipCounties the records returned already have access to their Vericred::County and Vericred::ZipCode

zip_counties = Vericred::ZipCounty.search(zip_prefix: '12345')
zip_counties.first.county.name # => County
zip_counties.first.zip_code.code # => 12345

Any individual, list of records, or total can be found using a Future. This allows you to make a request early in the execution of your codepath and allow the API to return a result without blocking execution. It also allows you to make requests to the API in parallel.

futures = [npi1, npi2, npi3]
            .map { |id| Vericred::Provider.future.find(npi) }
# do some other stuff in the meantime, then call #value to get the result
providers = futures.map(&:value)

futures =
  [1, 2, 3].map do |i|
    Vericred::Provider.future.total(
      zip_code: '12345',
      radius: i,
      search_term: 'foo'
    )
  end
# do some other stuff in the meantime, then call #value to get the result
totals = futures.map(&:value)

Generic error handling:

begin
  Vericred::Provider.find(npi)
rescue Vericred::Error => e
  # Retry or do something else
end

Handling each possible error

begin
  Vericred::Provider.find(npi)
rescue Vericred::UnauthenticatedError => e
  # No credentials supplied
rescue Vericred::UnauthorizedError => e
  # Invalid credentials
rescue Vericred::UnprocessableEntityError => e
  # Invalid parameters have been specified
rescue Vericred::UnknownError => e
  # Something else has gone wrong - see e.errors for details
end

Every instance of Vericred::Error has an #errors method, which returns the parsed error messages from the server. They are in the format.

{
  "errors": {
    "field_or_category": ["list", "of", "things", "wrong"]
  }
}

When parsed, they can be accessed like:

begin
  Vericred::Provider.find(npi)
rescue Vericred::Error => e
  e.errors.field_or_category.join(', ') # "list, of, things, wrong"
end

After checking out the repo, run bin/setup to install dependencies. Then, run rake rspec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

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 rubygems.org.

Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/vericred. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

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