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.

❗️

IMPORTANT

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.

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.

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 'https://gateway.stage.bill.com/connect/v3/users' \
--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
}'

Response

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

📘

NOTE

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.

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