BILL Accountant Console operations

The BILL Accountant Console enables accounting firms to easily manage multiple BILL clients or organizations. With the Accountant Console, you can generate a Console API token for signing in to your client organizations and for performing all BILL AP & AR API operations at the client organization level.

With the API, you can perform client organization operations like pre-seed users and roles, list all vendors, or set up high volume payments without manual data entry.

Your first step is to sign-up and set up your credentials with the BILL Accountant Console. When your sign-up is complete, you can generate a Console API token and then continue with signing in to client organizations with the BILL AP & AR API.

Sign-up to create your BILL Accountant Console account

When you sign-up to create your test BILL Accountant Console account, you set up your username and password for signing in to the Console account.

1. Navigate to the BILL sandbox sign-up form.
2. Enter the required information and click Get Started.

3. Create a password for your account, and click Next. This is the password for your BILL Accountant Console account.
4. Complete 2-step verification. Enter a valid phone number, select a method for receiving a security code, and click Send code. BILL sends your security code to the provided phone number. You can also use a non-US phone number in this step.
5. Enter the security code value. BILL validates this value and directs you to enter an address for your organization. Enter the required information and click Next.

You are directed to the test BILL Accountant Console in the sandbox environment.

👍

Contact the support team to get access to the Console API token generation feature

After your Accountant Console sign-up is complete, contact the support team to get access to the Console API token generation feature.

Generate Console API token

You can generate a Console API token in the BILL Accountant Console for signing in to your client organizations and for performing all BILL AP & AR API operations at the client organization level.

1. Sign in to the BILL sandbox web app. Use your Accountant Console account email address and password.
2. Click Staff in your BILL account.
3. Select a user with the Admin console role. If you are signing in for the first time, this is the user you created at the time of sign-up. The user profile information is available.
4. Click Manage profile > Generate API token.
5. Click Generate Token. Copy the generated key and save it in a safe place, such as a password manager.

Client organization operations

With the Console API token, you can sign in to client organizations with POST /v2/Login.json. You can set up multiple test client organizations and then perform API operations at the client organization level.

❗️

You cannot create client organizations with the API using the console API token

You must set up your client organizations with the BILL Accountant Console web app. You cannot create client organizations with the API using the console API token.

Creating an organization with the API requires a BILL partner appKey.

Set up a test client organization

In this section, we set up a test client organization in your Accountant Console.

1. Sign in to the BILL sandbox web app. Use your Accountant Console account email address and password.
2. Click Clients in your BILL account.
3. Click Add Client, enter the required information, and then click Next.

4. Under products for the test client organization, select Payables and Receivables. The Account subscription is automatically set as Bill to the client.
5. Select Client accounting system as I don't use accounting software, and then click Next. The default Admin console user is added as an Administrator to the client organization. If your Accountant Console has multiple users, you can add more users from the list.
6. Click Finish.

The client organization is added to the list of Clients in your Accountant Console.

Generate a developer key

In this section, we sign in to a client organization and generate a developer key for API access to that organization.

👍

You can use one developer key to sign in to any client organization

When you generate a developer key for one client organization, the key is available for you to use with any of your test client organizations and test users.

1. Sign in to the BILL sandbox web app. Use your Accountant Console account email address and password.
2. Click Tasks in the left navigation.
3. Select the client organization to sign in to. If this is the first time you are signing in to a client organization, accept the BILL General Terms of Service and click CONTINUE.
4. Click Settings in the BILL client organization account.
5. Click Sync & Integrations > Manage Developer Keys.
6. Click Generate developer key. You are prompted to agree to the BILL developer terms of service.
7. Review and accept the terms of service, and then click Generate key. It takes up to a minute for BILL to generate a developer key. Click Reload page in a few moments to view your generated key.

Keep your key in a safe place, such as a password manager.

👍

The client organization ID is available

The client organization ID is available at the bottom of this page. This organization ID is required for signing in to the client organization with the API.

Sign in to the client organization with the API

In this cURL example, you sign in to a client organization with POST /v2/Login.json. The required fields are userName, apiToken, devKey, and orgId.

👍

Console API token sign in with POST /v3/login will be available in the future

Currently, you are required to use the BILL v2 API login endpoint (POST /v2/Login.json) for signing in with the Console API token. In the future, we will provide support for Console API token sign in with the v3 API login endpoint (POST /v3/login).

From the API response, use the generated sessionId and your devKey as header fields in all subsequent BILL v3 API calls.

curl --request POST \
--url 'https://api-stage.bill.com/api/v2/Login.json' \
--header 'accept: application/json' \
--data 'userName={console_admin_email}' \
--data 'apiToken={console_api_token}' \
--data 'orgId={client_organization_id}' \
--data 'devKey={client_developer_key}'

Response

In the response, your API session is created and a generated sessionId is available. In addition, the usersId is the BILL-generated ID of the signed-in user in the client organization. If your API session is inactive for 35 minutes, the session expires and you are automatically signed out.

{
    "response_status": 0,
    "response_message": "Success",
    "response_data": {
        "apiEndPoint": "https://api-stage.bill.com/api/v2",
        "sessionId": "{session_id}",
        "orgId": "{client_organization_id}",
        "usersId": "{client_user_id}",
        "isOrgLocked": false
    }
}

Use the sessionId in all subsequent BILL AP & AR API calls to confirm that you are in a signed-in API session. For example, you can create a vendor in the client organization with POST /v3/vendors or you can add a new user in the client organization with POST /v3/users.

Get the list of your client organizations

Use POST /v2/ListOrgs.json to get the list of organization ID values for all your client organizations in the Accountant Console.

In this cURL example, you get the list of your client organizations.

curl --request POST \
--url 'https://api-stage.bill.com/api/v2/ListOrgs.json' \
--header 'accept: application/json' \
--data 'userName={console_admin_email}' \
--data 'password={console_admin_password}' \
--data 'devKey={client_developer_key}'

Response

In the response, the list of orgId values for all your client organizations is available.