This guide is designed to help you quickly transition from Portal 2 to the new and improved Platform. Using our V2 Shim package for assistance with the transition, you can get started on the new Platform within a few hours. To help you compare and contrast between your Portal 2 implementation and the Platform implementation, we created this Github Repository as a way to help you see the upgrade process from beginning to the end.

Before You Begin

With the new Platform, comes a brand new place to sign up for it. Before getting started on your upgrade, you’ll need to sign up for a new account.

Install the V2 Shims package

Before you can start using all the wonderful tools in this guide to implement Flatfile, you’ll need to install a couple of packages, the V2 Shims and Flatfile API packages.

If you are using our @flatfile/react package, be sure to install version 7.2.24 or higher to get the Platform React component.

npm install @flatfile/v2-shims @flatfile/api

Convert Your Config

The Portal 2 configuration is what contains your settings and fields in your Portal implementation.

const importer = new FlatfileImporter(
    { } // This is your configuration object

You’ll be able to use this configuration object with the V2 Shims package to configure your new implementation. Keep in mind that the below snippets use a couple of new concepts like a Job and Listener. While you don’t need to learn about these to get started, they are useful for adding new functionality onto your importer at some point in the future.

import FlatfileImporter from '@flatfile/adapter'

const config = {
    type: 'Contacts',
    fields: [
            key: 'name',
            label: 'Name',
            description: 'Contact name',
            validators: [
                { validate: 'required' }

const importer = new FlatfileImporter('LICENSE_KEY', config)

Converting your Record Hooks

If you’re transitioning from a V2 Record Hook to a Platform Record Hook in your code, you can make the conversion by simply extracting and wrapping your existing Record Hook code in the V2 Shim convertHook method.

If you’re using V2 Record Hooks mode to split hooks on “init” or on “change”, Platform does not have this mode functionality. It does, however, have better overall hooks performance and a new Bulk Record Hook method that make mode unnecessary.

const importer = new FlatfileImporter('LICENSE_KEY', config)

const recordHooksCallback = async (record) => {
    let out = {};

    if (record.firstName && !record.lastName) {
        out.lastName = {
            value: 'Rock',
            info: [
                    message: 'No last name provided so welcome to the Rock fam.',
                    level: 'warning'
    return out;