Organizations and Users

In this section, we walk through understanding organizations and users at BILL.

What is an organization?

A BILL organization represents a legal entity (individual or business). When you create a BILL account, you set up a BILL organization with related information, such as your physical address, tax ID, and business category. In addition, you set up a payments funding account, such as a bank account.

Who is a user?

When you sign in to your BILL developer account with /v3/login, you sign in as a user of your BILL organization. In the API response, userId is the BILL-generated ID of the signed-in user.



A BILL partner can perform partner-level operations, which includes creating an organization, and then creating and managing users for that organization. See BILL partner operations for more information.

If you are interested in becoming a BILL partner, please reach out to your account manager for more information.

As an organization-level user, you have permissions to perform a set of BILL API operations. By default, the user that creates a BILL account has the BILL ADMINISTRATOR user role, and is able to perform all organization-level BILL API operations.

BILL provides a set of default user roles.

  • Administrator
  • Accountant
  • Approver
  • Payer
  • Clerk
  • Auditor

See User roles and permissions in the BILL Help Center to learn about BILL user roles.

Organization operations

BILL provides two organization API endpoints for organization-level users. See the /v3/organizations API for more information.

OperationAPI endpoint
Get organization detailsGET /v3/organizations/{organizationId}
Update an organizationPATCH /v3/organizations/{organizationId}

In addition, you can set up a bank account in your BILL organization with POST /v3/bankaccounts. See Bank account setup (v3 API) for more information.

Creating a user

As a user with the ADMINISTRATOR user role in a BILL organization, you can use the BILL API to create other users and also manage user access in the BILL organization.

In your POST /v3/users request, set the required fields to create a user.

firstNameUser first name
lastNameUser last name
emailUser email address
roleIdBILL-generated ID of the user role. The value begins with 0po.

You can get the list of available user roles with GET /v3/roles.
acceptTermsOfServiceSet as true if the user accepts the BILL terms of service

Sample request

In this cURL example, a user is created with the specified details. The roleId is set as the BILL-generated ID of the CLERK user role. You can get the list of available user roles with GET /v3/roles.

curl --request POST \
--url '' \
--header 'content-type: application/json' \
--header 'devKey: {developer_key}' \
--header 'sessionId: {session_id}' \
--data '{
  "firstName": "Clark", 
  "lastName": "Billenterson",
  "email": "[email protected]",
  "roleId": "{role_id}",
  "acceptTermsOfService": true


In the response, a BILL-generated user id is available. This value begins with 006. You can use this user id for other BILL operations. With the BILL CLERK role, the created user has permissions to enter bills.

  "id" : "{user_id}",
  "archived": false,
  "firstName": "Clark",
  "lastName": "Billenterson",
  "email": "[email protected]",
  "role" : {
    "id": "{role_id}",
    "type": "CLERK",
    "description": "Clerk user role"
  "loginId": "{login_id}"
  "createdTime": "2024-12-15T22:58:40.000+00:00",
  "updatedTime": "2024-12-15T22:58:40.000+00:00"

Initiating BILL risk verification

You can add a phone number for the signed-in user (with POST /v3/risk-verifications/{userId}/phone), and then initiate risk verification (with POST /v3/risk-verifications).



See /v3/risk-verifications/{userId}/phone in the API reference for more information about adding a phone number for the signed-in user.

BILL performs a KYC/KYB (Know You Customer/Know Your Business) check based on the provided organization information. When the check is complete, BILL approves the organization for BILL AP and AR operations.

In the API response, the BILL risk verification decision status can have one of five values.

REVIEWRisk verification is in progress
IN_PROGRESSRisk verification is in progress. BILL waiting for more information about vendors in the organization. BILL requests the vendor in question for more information.
HOLDRisk verification is complete. BILL has set the approval on hold. BILL requests the organization owner for more information.
APPROVERisk verification is complete. BILL has approved the organization for BILL AP and AR operations.
DECLINERisk verification is complete. BILL has declined the organization.

See the /v3/users for more information about the complete list of user operations.