Skip to content
Node.js library for the Onfido API
Branch: master
Clone or download

Latest commit

Fetching latest commit…
Cannot retrieve the latest commit at this time.


Type Name Latest commit message Commit time
Failed to load latest commit information.
test Document the format of responses (#7) Jan 22, 2020
.gitignore Intial Setup (#1) Dec 17, 2019
.tool-versions Intial Setup (#1) Dec 17, 2019
LICENSE Fix travis releasing (#8) Jan 24, 2020
package.json Fix travis releasing (#8) Jan 24, 2020

Onfido Node.js Library

The official Node.js library for integrating with the Onfido API.

Documentation can be found at

This library is only for use on the backend, as it uses Onfido API tokens which must be kept secret. If you do need to collect applicant data in the frontend of your application, we recommend that you use one of the Onfido SDKs.


For npm:

npm install @onfido/api

For Yarn:

yarn add @onfido/api

Getting Started

Require the package:

const { Onfido, Region } = require("@onfido/api");

For TypeScript users, types are available as well:

import { Onfido, Region, Applicant, OnfidoApiError } from "@onfido/api";

Configure with your API token, and region if necessary:

const onfido = new Onfido({
  apiToken: process.env.ONFIDO_API_TOKEN
  // Defaults to EU region (
  // region: Region.US

Using with async/await (in an async function):

try {
  const applicant = await onfido.applicant.create({
    firstName: "Jane",
    lastName: "Doe"

  const check = await onfido.check.create({
    reportNames: ["identity_enhanced"]

  return check;
} catch (error) {
  if (error instanceof OnfidoApiError) {
    // An error response was received from the Onfido API, extra info is available.
  } else {
    // No response was received for some reason e.g. a network error.

Using with promises:

    firstName: "Jane",
    lastName: "Doe"
  .then(applicant =>
      reportNames: ["identity_enhanced"]
  .then(check =>
    // Handle successfully created check.
  .catch(error => {
    // Handle error.

Response format

Most responses will be normal JavaScript objects. Property names will be in camelCase rather than snake_case, including property names in nested objects.

const applicant = await onfido.applicant.create({
  firstName: "Jane",
  lastName: "Doe",
  address: {
    flatNumber: "12",
    postcode: "S2 2DF",
    country: "GBR",

  id: "<APPLICANT_ID>",
  createdAt: "2020-01-22T10:44:01Z",
  firstName: "Jane",
  lastName: "Doe",
  email: null,
  dob: null,
  deleteAt: null,
  href: "/v3/applicants/<APPLICANT_ID>",
  address: {
    flatNumber: "12",
    buildingNumber: null,
    buildingName: null,
    street: null,
    subStreet: null,
    town: null,
    state: null,
    postcode: "S2 2DF",
    country: "GBR",
    line1: null,
    line2: null,
    line3: null
  idNumbers: []

File downloads, for example, will return instances of OnfidoDownload.

These objects will have a content type, e.g. image/png.


Call asStream() to get a Readable stream of the download. You can read more about Readable streams.

const readableStream = download.asStream();

More Documentation

More documentation and code examples can be found at

You can’t perform that action at this time.