Skip to main content

​
After this article

You will be able to connect BILL (Bill.com) to Lumos to sync and provision users and roles.

​
Capabilities

​
Required plan and roles

  • BILL account: the account used to connect (Username/Password) should have full read access to the organization entered in the Organization ID field. Because this integration also provisions and deactivates users, connect with an account that can manage users in that organization.
  • Developer Key: you need a BILL Developer Key, which identifies your developer account in API requests. See BILL’s API documentation for how to obtain one.
  • Permission scoping: the connection takes one set of credentials. There is no scope or permission picker on the card and no read-only variant of this integration. What Lumos can do is bounded by the connecting BILL user’s own permissions.

​
Read-only access vs provisioning

Is read-only possible? Not as a supported option. There is one set of credentials, no scope or permission picker on the card, and no read-only variant of this integration to connect instead. What Lumos can reach is bounded by the connecting BILL user’s own permissions, and Lumos expects that user to hold full read access to the organization plus the ability to manage users, because creating users, changing their roles, and deactivating them are all part of this integration. What full provisioning requires. A BILL username, password, and Developer Key for an account with full read access to the organization and the ability to manage users in it, entered along with the Organization ID as described above. Watch out for. Because access follows the connecting user’s own BILL permissions rather than a separate credential mode, if that user’s access changes in BILL, both sync and provisioning are affected together. Narrowing that user’s permissions does not provide a clean read-only connection. It provides a connection whose provisioning actions fail at the point of use. An organization lockout (BILL error code BDC_1107) blocks connection or sync entirely until it’s resolved in BILL.

​
Instructions

Phase 1: Gather BILL values
  1. Username: the email address used to log in to your BILL account.
  2. Password: the password for that BILL account.
  3. Organization ID: the unique alphanumeric value for your organization. It always begins with 008.
  4. Developer Key: from your BILL developer account. See BILL’s API documentation if you need to obtain one.
Phase 2: Connect in Lumos
  1. Find the Bill.com card in your Lumos integrations (reconnect an existing card or add a new one).
  2. Enter the Username, Password, Organization ID, and Developer Key.
  3. Check Enable Sandbox only if you are connecting to the BILL sandbox (staging) environment.
  4. Click Connect.

​
API Endpoints Used

​
Troubleshooting

Connection fails with invalid organization. Double-check the Organization ID. It is always an alphanumeric value beginning with 008, and the connecting user must have access to that specific organization. Connection or sync fails with a permission error. Check whether your BILL organization is locked out (BILL error code BDC_1107, “Organization is locked out”). Resolve the lockout in BILL, then reconnect. Sandbox vs. production mismatch. If credentials are valid but login fails, confirm the Enable Sandbox checkbox matches the environment your Organization ID and Developer Key belong to (sandbox uses gateway.stage.bill.com).