Skip to main content
The Nmbr Component offers a fully-featured payroll suite in a lightweight integration. It takes less than an hour for a single developer to add payroll features to any app using our embeddable payroll module, designed and built by our in-house experts to work seamlessly with your data in any environment. To get started, you will need the following:
  • A Partner ID, API Key, and API Secret from our Portal.
  • The ability to add a server-side endpoint in your app’s API
  • The ability to add or change HTML pages in your app’s UI

​
How it works

You will be adding a javascript <script> tag to your existing web application in order to load and display the Nmbr Component. The component is loaded in an iframe and sized to fit its container. You will need to ensure access to the page containing the component is sufficiently protected via authentication and authorization, as the Nmbr Component has no access to your front-end user information.

​
Security

Interacting with the Nmbr Component along with any API calls required to load or change data requires a signature created by your web server. Before making an API request, the component will use your signing endpoint to retrieve a signature to be sent with the API request. The Nmbr API automatically validates this signature to ensure secure communication between the Nmbr Component and the Nmbr API.

​
1 - Set up the Signing Endpoint

​
Install a JWT library

Nmbr Components use JSON Web Tokens (JWTs) signed on your server to prove a user is authorized to read and write payroll data. Their website features libraries in several languages, although some listed may be out of date. 
gem install jwt
🙋 Don’t want to use a library? You may also implement signing yourself by following the JWT spec (RFC 7519).

​
Create a signing endpoint

Add an endpoint on your server to sign pre-formed JWTs. When you mount Nmbr Components in your app (step 2), this endpoint will be used to initialize the library. 
# app.rb
require 'jwt'
require 'sinatra'

NMBR_API_SECRET = ENV['NMBR_API_SECRET'] || 'invalid-secret'

# Sign request bodies with the SHA-256 hash of your API Secret,
# formatted as a hex string (though base64 is supported too)
SIGNING_HASH = Digest::SHA256.hexdigest(NMBR_API_SECRET)

post '/sign_nmbr_request' do
  # Your app should authenticate the user and
  # ensure they are authorized to administer payroll
  payload = JSON.parse(request.body.read)
  token = JWT.encode(payload, SIGNING_HASH, 'HS256')
  status 201
  body token
end

# Start the server
set :port, ENV['PORT'] || 8080
run Sinatra::Application

​
2 - Mount the Run Screen

The Nmbr Component uses a single script to securely initialize, load, and orchestrate UI from Nmbr’s servers inside your app.

​
Install host.js

Download the script directly from Nmbr’s CDN
payroll.html
<!DOCTYPE html>
<html>
  <head>
    <title>Nmbr Components Demo</title>
    <script type="importmap">
    {
      "imports": {
        "@nmbrco/components": "https://static.sandbox.nmbr.co/components/*/host.js"
      }
    }
    </script>

    <!-- Meta tags; style links; other scripts; etc -->
  </head>

  <body>
    <!-- Continued below>
  </body>
</html>
If you’re using Vite, the importmap below won’t work. See Using Vite for the alternative.

​
Initialize Nmbr Components

As soon as your page allows it, initialize host.js to start loading resources that will make the components load faster and smoother for your users.
payroll.html
<!DOCTYPE html>
<html>
  <head>
    <!-- Critical scripts; the importmap from above; etc -->

    <script type="module">
      import nmbr from '@nmbrco/components';

      // You must provide these when initializing the host script.
      // These are anonymized identifiers we generate that do not contain PII.
      const partnerId = 'your-partner-id';
      const companyId = 'user-company-id';

      // Initialize Nmbr Components as early as you can
      // to minimize perceived latency for the user.
      window.components = nmbr.initialize({
        companyId,
        partnerId,
        sandbox: true,
        signingUrl: '/sign_nmbr_request', // Use the same value as above
        // [optional params]
        // sandbox: false,
        // sign: async (json: string): Promise<string> => {
        //   const response = await fetch(this.signingUrl, {
        //     method: 'POST',
        //     headers: {
        //       Accept: 'text/plain',
        //       'Content-Type': 'application/json',
        //     },
        //     body: json,
        //   });
        //
        //   return response.text();
        // },
      });
    </script>

    <!-- Meta tags; style links; other scripts; etc -->
  </head>

  <body>
    <!-- Continued below -->
  </body>
</html>

​
Types

The type information for the configuration object passed to nmbr.initialize is as follows: 
type InitializationConfig = {
  signingUrl?: string | never; // A `signingUrl` must be provided if the `sign` function is not provided
  sign?: (message: string) => Promise<string> | never; // A `sign` function must be provided if the `signingUrl` is not provided
  companyId: string; // The company ID to load the component for
  partnerId: string; // Your partner ID
  sandbox?: boolean;
  theme?: CustomTheme; //  See Theming > Type Information
  settings?: Settings; // See Customization > Settings > Available Settings
};
For more information on the theme types, see the Theming page For more information on the settings types, see the Customization page

​
Using Vite

If you’re using Vite, the importmap pattern won’t work. In dev mode, Vite tries to resolve package-name imports like @nmbrco/components from your local node_modules folder before the browser sees the importmap. Since @nmbrco/components is loaded from Nmbr’s CDN rather than installed as an npm package, Vite returns a 404. If you’re using Vite, use this dynamic import instead of the importmap install and static import shown above. The full URL points directly at Nmbr’s CDN, so Vite doesn’t try the node_modules lookup:
payroll.html
<!DOCTYPE html>
<html>
  <head>
    <!-- Critical scripts; etc. No importmap needed. -->

    <script type="module">
      // @nmbrco/components is a CDN script, not an npm package.
      // Use a dynamic import with the full URL so Vite skips the node_modules lookup.
      const nmbr = (await import('https://static.sandbox.nmbr.co/components/*/host.js')).default;

      const partnerId = 'your-partner-id';
      const companyId = 'user-company-id';

      window.components = nmbr.initialize({
        companyId,
        partnerId,
        sandbox: true,
        signingUrl: '/sign_nmbr_request',
      });
    </script>

    <!-- Meta tags; style links; other scripts; etc -->
  </head>

  <body>
    <!-- Continued below -->
  </body>
</html>

​
Load the Run Payroll component

Once your host.js script is initialized, you may embed Nmbr’s Run Payroll component into any element on your page.
payroll.html
<!DOCTYPE html>
<html>
  <head>
    <!-- From above -->
  </head>

  <body>
    <header>
      <!-- Your app's topbar content -->
    </header>

    <div>
      <aside>
        <!-- Your app's sidebar content -->
      </aside>

      <main id="nmbr-container">
        <!-- Your app might do more; we will embed directly here -->
      </main>
      <script type="text/javascript">
        // Start loading the component as soon as its container is in the DOM
        const container = document.querySelector('#nmbr-container');
        const frame = components.load('run', container, {
          // hideUntilReady = false
        });

        frame.ready
          .then(() => console.log('Nmbr Components Run Screen loaded'))
          .catch((err) =>
            console.error('Could not load Nmbr Components Run Screen', err),
          );
      </script>
    </div>
  </body>
</html>

​
3 - Test your page

At this point, you have finished writing all code required to set up Nmbr Components. Let’s see it in action!

​
Load the payroll page

Start by loading the page you set up in Step 2; you should see the embedded iframe start loading in your container. New companies will always start at the Company Setup screen; once they have completed setup the component will default to the Payroll Dashboard.

​
Run a payroll in sandbox

Once you’ve confirmed the component is loading, it is time to submit data. To simulate payroll before you go live, import the sandbox version of the scripts and provide the additional option sandbox: true for Nmbr Components. (You may also need to provide different partner credentials configured for the sandbox environment). 
<script type="importmap">
  {
    "imports": {
      "@nmbrco/components": "https://static.sandbox.nmbr.co/components/*/host.js"
    }
  }
</script>

const components = nmbr.initialize({
  // ...
  sandbox: true,
});

​
Congratulations!

You have successfully embedded Nmbr Components in your app. Consider next how else to customize your integration:
  • Mirror business, employee, and other data to Nmbr to pre-fill payroll fields