A wrapper for Onfido's API. You should always refer to the documentation for valid API calls.
Add this line to your application's Gemfile:
gem 'onfido'
And then execute:
$ bundle
Or install it yourself as:
$ gem install onfido
There are 3 configuration options for Onfido, including your api_key
, throwing exceptions for failed responses and logging the requests. By default, throws_exceptions
is set to true
. If set to false
, the response body will be returned instead.
Onfido.configure do |config|
config.api_key = 'MY_API_KEY'
config.logger = Logger.new(STDOUT)
config.throws_exceptions = false
end
Assuming you have a valid key, you can conveniently make API calls by using an instance of the API
class.
api = Onfido::API.new
All resources share the same interface when making API calls. For creating a resource you can use .create
, for finding one .find
and for fetching all records for a resource .all
.
Note: All param keys should be a symbol e.g. {type: 'express', reports: [{name: 'identity'}]}
To create an applicant, you can simply use
api.applicant.create(params)
To find an existing applicant
api.applicant.find('applicant_id')
To get all applicants
api.applicant.all
To upload a document for an applicant, you can simply use
api.document.create('applicant_id', {file: 'http://example.com', type: 'passport')
The file can both be a File
object or a link to an image.
To create a check for an applicant, you can simply use
api.check.create('applicant_id', {type: 'express', reports: [{name: 'identity'}]})
To find an existing check for an applicant
api.check.find('applicant_id', 'check_id')
To get all checks for an applicant
api.check.all('applicant_id')
To find an existing report for a check
api.report.find('check_id', 'report_id')
To get all reports for a check
api.report.all('check_id')
To search for addresses by postcode
api.address.all('SE1 4NG')
By default, Onfido will attempt to raise errors returned by the API automatically.
If you set the throws_exceptions
to false, it will simply return the response body. This allows you to handle errors manually.
If you rescue Onfido::RequestError, you are provided with the error message itself as well as the type of error, response code and fields that have errored. Here's how you might do that:
def create_applicant
api.applicant.create(params)
rescue Onfido::RequestError => e
e.type # returns 'validation_error'
e.fields # returns {"email": {"messages": ["invalid format"]}
e.response_code # returns '401'
end
- Improve test coverage with more scenarios
- Add custom errors based on the response code.
- Improve documentation
- Fork it ( https://github.com/hvssle/onfido/fork )
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create a new Pull Request