Skip to main content

Authorization

Follow this guide to create a new BILL v3 API credential that will allow Nexla to authenticate to and exchange data with your BILL v3 API account.
bill_v3_api_auth.png

BILL v3 API

Prerequisites​

Before creating a credential, gather the values required by the BILL v3 API POST /v3/login endpoint. These include your BILL username, password, organization ID, and a developer key issued from your BILL account.

BILL Account & Organization​

A BILL account is required to access the v3 API. Production credentials are created from your live BILL organization, while testing credentials are created from a sandbox developer account.

  1. Sign in to BILL at the appropriate environment for your use case.

    • Production: Sign in at https://app.bill.com using the email address and password for your BILL organization.

    • Sandbox: Sign in at the BILL sandbox web app using the developer account email address and password created during sandbox sign-up. For details on creating a sandbox account, refer to the Sandbox API sign up guide.

  2. Locate your Organization ID. In the BILL web app, navigate to Settings. The organization ID is displayed at the bottom of the settings page and is required when signing in to the API.

Generate a Developer Key​

The developer key (devKey) identifies your application to BILL on every API request and must be included in the devKey HTTP header.

  1. While signed in to the BILL web app, click Settings.

  2. Click Sync & Integrations > Manage Developer Keys.

  3. Click Generate developer key.

  4. Review the BILL developer terms of service. Accept the terms, then click Generate key.

  5. BILL takes up to a minute to generate the developer key. Click Reload page after a few moments to view your generated key.

    Important

    Store the developer key in a secure location such as a password manager. Treat it as a secret credential and do not share it publicly.

For complete details on BILL keys and tokens, refer to the BILL keys and tokens documentation.

API Environments​

BILL provides distinct base URLs for production and sandbox environments. Select the environment that matches the credentials and developer key you generated.

  • Production: https://api.bill.com

  • Sandbox: https://gateway.stage.bill.com/connect

For additional details, refer to the BILL v3 API Reference Overview.

Create a BILL v3 API Credential​

  • To create a new BILL v3 API credential, after selecting the data source/destination type, click the Add Credential tile to open the Add New Credential overlay.

Credential Name & Description​

  1. Enter a name for the credential in the Credential Name field and a short, meaningful description in the Credential Description field.

    Resource descriptions are recommended but are not required. They should be used to provide information about the resource purpose, data freshness, etc. that can help the owner and other users efficiently understand and utilize the resource.

BILL v3 API Authentication Settings​

The BILL v3 API uses token-based authentication. Nexla exchanges your username, password, organization ID, and developer key for a sessionId by calling the POST /v3/login endpoint. The returned sessionId is automatically used as the sessionId header on all subsequent API requests.

  1. Enter the email address associated with your BILL account in the Username field.

  2. Enter the password for your BILL account in the Password field.

    The password value is stored as a secured credential field and is only used when Nexla exchanges credentials for a session.

  3. Enter your BILL organization ID in the Organization ID field. This value is found at the bottom of the Settings page in the BILL web app and identifies the BILL organization that will be accessed by Nexla.

  4. Enter the developer key generated in your BILL account in the Developer Key field. The developer key is sent in the devKey header on every BILL v3 API request.

  5. Select the BILL API environment that matches your credentials from the API Base URL field.

    • Production (https://api.bill.com): Select this option to access your live BILL organization data.

    • Sandbox (https://gateway.stage.bill.com/connect): Select this option when working with a sandbox developer account for testing and integration development.

    Production credentials cannot be used against the sandbox environment, and sandbox credentials cannot be used against production. Ensure the username, password, organization ID, developer key, and base URL all correspond to the same BILL environment.

Save the Credential​

  1. Once all of the relevant steps in the above sections have been completed, click the Save button at the bottom of the overlay to save the configured credential.

  2. The newly added credential will now appear in a tile on the Authenticate screen during data source/destination creation and can be selected for use with a new data source or destination.