Vericred

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

• Futures
• Sideloading data
• Pagination (TODO)

Additional Documentation

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

Installation

Add this line to your application's Gemfile:

gem 'vericred'

And then execute:

$ bundle

Or install it yourself as:

$ gem install vericred

With Rails

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

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

Usage

Retrieving an Individual Record

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

Retrieving a List of Records

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

Retrieving a total count from the List endpoint

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

Searching for Plans

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

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

Using Futures

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)

Error Handling

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

Development

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.

Contributing

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.

License

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