> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lumos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Bill.com

## After this article

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

## Capabilities

| Functionality | Type | Sync | Provision | Description |
| :- | :- | :- | :- | :- |
| Users | Account | Yes | Yes | User accounts |
| Roles | Permission | Yes | Yes | Roles in Bill.com |

| Deprovisioning Action | Type | Description |
| :- | :- | :- |
| Deactivate | User | Deactivate (archive) a user in Bill.com |

## 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

<Note>
  The API endpoints this integration uses are available to logged-in Lumos customers. [Log in](/login) to view them.
</Note>

## 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`).