@truework/sdk

@truework/sdk

The official Truework API Node.js SDK.

Quick Links

• Getting Started
• Terminology
• Usage
  • Verifications
  • Companies
• Testing
  • Verifications
  • Companies
• Contributing

Resources

• 📚 API Documentation
• 🏠 Truework
• 👷‍♀️ Careers

Getting Started

npm i @truework/sdk --save

const { truework } = require('@truework/sdk');

const client = truework({ token: TRUEWORK_ACCESS_TOKEN });

By default, the SDK will use the latest version of our API. To request a different version, pass it when configuring your client.

const client = truework({
  token: TRUEWORK_ACCESS_TOKEN,
  version: '2019-10-15',
});

To set a timeout on requests, pass in the timeout value in milliseconds when configuring the client. If a request times out, it will abort with got.TimeoutError. Most applicable when used in conjunction with synchronous creation of verifications.

const client = truework({
  token: TRUEWORK_ACCESS_TOKEN,
  timeout: 6000,
});

To use the SDK to call the Truework Sandbox, configure the client for the sandbox environment.

const { truework, ENVIRONMENT } = require('@truework/sdk');

const client = truework({
  token: TRUEWORK_SANDBOX_TOKEN,
  environment: ENVIRONMENT.SANDBOX,
});

Terminology

Please review the API Documentation for all terminology. If you're using Typescript, have a look at the types.

Usage

All requests are made using got, and so responses implement a got response object.

const {
  body: { count, results },
} = await client.verifications.get();

Verifications

verifications.get([params])

Request

• params - object - optional
  • state - string - required
  • limit - number
  • offset - number

Response

Returns a PaginatedResponse containing an array of Verifications.

Example

await client.verifications.get();
await client.verifications.get({ limit: 10 });

verifications.getOne(params)

Request

• params - object - required
  • id - string - required

Response

Returns a Verification object.

Example

await client.verifications.getOne({ id: 'abc123' });

verifications.create(params)

Request

• params - object - required
  • type - VerificationType - required
  • permissible_purpose - PermissiblePurpose - required
  • target - Target - required
  • documents - Document
  • additional_information - string

Response

Returns the full Verification object.

Example

await client.verifications.create({
  type: 'employment',
  permissible_purpose: 'employment',
  target: {
    first_name: 'Megan',
    last_name: 'Rapinoe',
    social_security_number: '123121234',
    company: {
      name: 'USWNT',
    },
  },
  additional_information: 'Lorem ipsum dolor...',
});

verifications.create(params, syncParams)

Executes the request synchronously, attempting to return the completed verification rather than sending a webhook on completion. It is recommended to use the client timeout param in conjunction with this method.

Request

• params - object - required
  • type - VerificationType - required
  • permissible_purpose - PermissiblePurpose - required
  • target - Target - required
  • documents - Document
  • additional_information - string
• syncParams - object
  • strategy - RequestSyncStrategy

Response

Returns the full Verification object, with reports if successful.

Example

const {
  truework,
  REQUEST_SYNC_STRATEGIES,
  VERIFICATION_TYPES,
  PERMISSIBLE_PURPOSES,
} = require('@truework/sdk');

const client = truework({
  token: TRUEWORK_ACCESS_TOKEN,
  timeout: 6000,
});

const res = await client.verifications.create(
  {
    type: VERIFICATION_TYPES.EMPLOYMENT,
    permissible_purpose: PERMISSIBLE_PURPOSES.EMPLOYMENT,
    target: {
      first_name: 'Megan',
      last_name: 'Rapinoe',
      social_security_number: '123121234',
      date_of_birth: '1990-09-26',
    },
    additional_information: 'Lorem ipsum dolor...',
  },
  {
    strategy: REQUEST_SYNC_STRATEGIES.SYNC,
  }
);

if (res.body.reports?.length) {
  // verification completed synchronously
}

verifications.cancel(params)

Request

• params - object - required
  • id - string - required
  • cancellationReason - CancellationReason - required
  • cancellationDetails - string

Response

Returns status code 200 on success.

Example

await client.verifications.cancel({
  id: 'abc123',
  cancellationReason: 'other',
});

verifications.reverify(params)

Request

• params - object - required
  • id - string - required
  • report_id - string - required

Response

Returns the full Verification object.

Example

await client.verifications.reverify({
  id: 'abc123',
  rerport_id: 'def123',
});

verifications.getReport(params)

Request

• params - object - required
  • id - string - required, the ID of the Verification

Response

Returns the full Report object associated with the Verification.

Example

await client.verifications.getReport({ id: 'abc123' });

Companies

companies.get(params)

Request

• params - object - required
  • query - string - required
  • limit - number
  • offset - number

Response

Returns a PaginatedResponse containing an array of Companys.

Example

await client.companies.get({ query: 'USWNT' });

Credentials

credentials.createSession(params)

Request

• params - object - required
  • type - VerificationType - required
  • permissible_purpose - PermissiblePurpose - required
  • use_case - UseCase - required
  • target - Target - required

Response

Returns a CredentialsSession

Example

await client.credentials.createSession({
  type: 'employment',
  permissible_purpose: 'employment',
  use_case: 'mortgage',
  target: {
    first_name: 'Megan',
    last_name: 'Rapinoe',
    social_security_number: '123121234',
    date_of_birth: '2020-02-02',
    company: {
      name: 'USWNT',
    },
  },
});

Testing

This SDK provides a naive "mock" mode that can be used for basic testing during CI, etc. It is stateless, meaning no data is persisted between API calls. When enabled, each SDK method will either return stub objects, or simple reflections of the data submitted.

To enable mock mode, initialize your SDK client like this:

const client = truework({
  token: TRUEWORK_ACCESS_TOKEN,
  mock: true,
});

Verification Mocks

verifications.get

Returns a stubbed array of verifications, respective of all query params.

const res = await client.verifications.get({ state: 'processing', limit: 5 });

res.body.results.length; // => 5
res.body.results[0].state; // => processing

verifications.getOne

Returns a stubbed verification object with the same id as is passed to getOne({ id }).

Error States

Any id value is valid, except "AAAA", which will trigger a 404 error response.

try {
  await client.verifications.getOne({ id: 'AAAA' });
} catch (e) {
  console.log(e.response); // error response body
}

verifications.create

Returns a stubbed verification object.

Error States

To trigger an error response, do not pass a type property.

try {
  await client.verifications.create(
    // type: 'employment',
    permissible_purpose: 'employment',
    target: {
      first_name: 'Megan',
      last_name: 'Rapinoe',
      social_security_number: '123121234',
      company: {
        name: 'USWNT',
      },
    },
    additional_information: 'Lorem ipsum dolor...',
  })
} catch (e) {
  console.log(e.response) // error response body
}

verifications.cancel

Returns 200 if successful.

Error States

Any id value is valid, except "AAAA", which will trigger an error response.

try {
  await client.verifications.cancel({ id: 'AAAA' });
} catch (e) {
  console.log(e.response); // error response body
}

verifications.getReport

Returns a stubbed report object if successful.

Error States

Any id value is valid, except "AAAA", which will trigger an error response.

try {
  await client.verifications.getReport({ id: 'AAAA' });
} catch (e) {
  console.log(e.response); // error response body
}

Company Mocks

companies.get

Returns a stubbed array of companies, respective of limit and offset query params.

const res = await client.companies.get({ limit: 5 });

res.body.results.length; // => 5

Contributing

Issues

If you run into problems, or simply have a question, feel free to open an issue!

Commiting

This repo uses commitizen to nicely format commit messages. Upon making edits, stage your changes and simply run git commit to enter the commitizen UI in your terminal.

Note: if you are not prompted with the commitizen UI, run npm ci to re-install and run postinstall hooks to set it up.

Releases

This project is versioned and published automatically using semantic-release. Via a GitHub Action, semantic-release will use the commit message pattern provided by commitizen to automatically version the package. It will then publish to npm, as well as create a new release here in the main repo.

Do not publish this library manually from the command line.

License

MIT License © Truework