Onfido

A thin wrapper for Onfido's API.

This gem supports both v1 and v2 of the Onfido API. Refer to Onfido's API documentation for details of the expected requests and responses for both.

Installation

Add this line to your application's Gemfile:

gem 'onfido', '~> 0.12.0'

The gem is compatible with Ruby 2.2.0 and onwards. Earlier versions of Ruby have reached end-of-life, are no longer supported and no longer receive security fixes.

Configuration

There are 5 configuration options:

Onfido.configure do |config|
  config.api_key = 'MY_API_KEY'
  config.api_version = 'v2'
  config.logger = Logger.new(STDOUT)
  config.open_timeout = 30
  config.read_timeout = 80
end

Usage

You can make API calls by using an instance of the API class:

api = Onfido::API.new

Alternatively, you can set an API key here instead of in the initializer:

api = Onfido::API.new(api_key: 'API_KEY')

Resources

All resources share the same interface when making API calls. Use .create to create a resource, .find to find one, and .all to fetch all resources.

Note: All param keys should be a symbol e.g. { type: 'express', reports: [{ name: 'identity' }] }

Applicants

Applicants are the object upon which Onfido checks are performed.

api.applicant.create(params)                  # => Creates an applicant
api.applicant.update('applicant_id', params)  # => Updates an applicant
api.applicant.destroy('applicant_id')         # => Destroy an applicant
api.applicant.find('applicant_id')            # => Finds a single applicant
api.applicant.all                             # => Returns all applicants

Documents

Documents provide supporting evidence for Onfido checks.

api.document.create('applicant_id', file: 'http://example.com', type: 'passport') # => Creates a document
api.document.find('applicant_id', 'document_id') # => Finds a document
api.document.download('applicant_id', 'document_id') # => Downloads a document as a binary data
api.document.all('applicant_id') # => Returns all applicant's documents

Note: The file parameter must be a File-like object which responds to #read and #path. Previous versions of this gem supported providing a URL to a file accessible over HTTP or a path to a file in the local filesystem. You should instead load the file yourself and then pass it in to #create.

Live Photos

Live Photos, like documents, can provide supporting evidence for Onfido checks.

api.live_photo.create('applicant_id', file: 'http://example.com')
api.live_photo.find(applicant_id, live_photo_id) # => Finds a live photo
api.live_photo.download(applicant_id, live_photo_id) # => Downloads a live photo as binary data
api.live_photo.all(applicant_id) # => Returns all applicant's live photos

Note: The file parameter must be a File-like object which responds to #read and #path. Previous versions of this gem supported providing a URL to a file accessible over HTTP or a path to a file in the local filesystem. You should instead load the file yourself and then pass it in to #create.

Checks

Checks are requests for Onfido to check an applicant, by commissioning one or more "reports" on them.

api.check.create('applicant_id', type: 'express', reports: [{ name: 'identity' }])
api.check.find('applicant_id', 'check_id')
api.check.resume('check_id')
api.check.all('applicant_id')

Reports

Reports provide details of the results of some part of a "check". They are created when a check is created, so the Onfido API only provides support for finding and listing them. For paused reports specifically, additional support for resuming and cancelling reports is also available.

api.report.find('check_id', 'report_id')
api.report.all('check_id')
api.report.resume('check_id', 'report_id')
api.report.cancel('check_id', 'report_id')

Report Type Groups

Report type groups provide a convenient way to group and organize different types of reports. The Onfido API only provides support for finding and listing them.

api.report_type_group.find('report_type_group_id')
api.report_type_group.all()

Address Lookups

Onfido provides an address lookup service, to help ensure well-formatted addresses are provided when creating "applicants". To search for addresses by postcode, use:

api.address.all('SE1 4NG')

Webhook Endpoints

Onfido allows you to set up and view your webhook endpoints via the API, as well as through the dashboard.

api.webhook.create(params)          # => Creates a webhook endpoint
api.webhook.find('webhook_id')      # => Finds a single webhook endpoint
api.webhook.all                     # => Returns all webhook endpoints

SDK Tokens

Onfido allows you to generate JSON Web Tokens via the API in order to authenticate with Onfido's JavaScript SDK.

api.sdk_token.create(applicant_id: 'applicant_id', referrer: 'referrer')

Pagination

All resources that support an all method also support pagination. By default, the first 20 records are fetched.

Error Handling

There are three classes of errors raised by the library, all of which subclass Onfido::OnfidoError:

• Onfido::ServerError is raised whenever Onfido returns a 5xx response
• Onfido::RequestError is raised whenever Onfido returns any other kind of error
• Onfido::ConnectionError is raised whenever a network error occurs (e.g., a timeout)

All three error classes provide the response_code, response_body, json_body, type and fields of the error (although for Onfido::ServerError and Onfido::ConnectionError the last three are likely to be nil).

def create_applicant
  api.applicant.create(params)
rescue Onfido::RequestError => e
  e.type          # => 'validation_error'
  e.fields        # => { "email": { "messages": ["invalid format"] } }
  e.response_code # => '422'
end

Webhooks

Each webhook endpoint has a secret token, generated automatically and exposed in the API. When sending a request, Onfido includes a signature computed using the request body and this token in the X-Signature header.

This provided signature should be compared to one you generate yourself with the token to check that a webhook is a genuine request from Onfido.

if Onfido::Webhook.valid?(request.raw_post,
                          request.headers["X-Signature"],
                          ENV['ONFIDO_WEBHOOK_TOKEN'])
  process_webhook
else
  render status: 498, text: "498 Token expired/invalid"
end

Roadmap

• Improve test coverage with more scenarios
• Add custom errors based on the response code
• Improve pagination handling (use information passed in link header)

Contributing

1. Fork it ( https://github.com/hvssle/onfido/fork )
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request