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.

Add this line to your application's Gemfile:

gem 'onfido', '~> 0.15.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.

There are 6 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
  config.region = nil
end

The gem will use the default region if no region is specified.

To specify the US region do: config.region = :us

See https://documentation.onfido.com/#regions for supported regions.

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')

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 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')         # => Schedule an applicant for deletion
api.applicant.restore('applicant_id')         # => Restore an applicant scheduled for deletion
api.applicant.find('applicant_id')            # => Finds a single applicant
api.applicant.all                             # => Returns all applicants

Note: Calling api.applicant.destroy adds the applicant and all associated documents, photos, videos, checks, and reports to the deletion queue. They will be deleted 20 days after the request is made. An applicant that is scheduled for deletion can be restored but applicants that have been permanently deleted cannot. See https://documentation.onfido.com/#delete-applicant for more information.

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, 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 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.find_by_url('applicants/a90e7a17-677a-49ab-a171-281f96c77bde/checks/c9f41bef-0610-4d2f-9982-ae9387876edc')
api.check.resume('check_id')
api.check.all('applicant_id')

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 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()

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')

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

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')

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

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

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

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

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