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.
Operation | API endpoint |
---|---|
Get organization details | GET /v3/organizations/{organizationId} |
Update an organization | PATCH /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.
Field | Description |
---|---|
firstName | User first name |
lastName | User last name |
email | User email address |
roleId | BILL-generated ID of the user role. The value begins with 0po .You can get the list of available user roles with GET /v3/roles . |
acceptTermsOfService | Set 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 '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.
Value | Description |
---|---|
REVIEW | Risk verification is in progress |
IN_PROGRESS | Risk verification is in progress. BILL waiting for more information about vendors in the organization. BILL requests the vendor in question for more information. |
HOLD | Risk verification is complete. BILL has set the approval on hold. BILL requests the organization owner for more information. |
APPROVE | Risk verification is complete. BILL has approved the organization for BILL AP and AR operations. |
DECLINE | Risk verification is complete. BILL has declined the organization. |
See the /v3/users for more information about the complete list of user operations.
Updated 3 months ago