Users for BILL partners
As a BILL partner, you can create and manage users for a created BILL organization. You can also sign in as a created user and perform organization-level BILL API operations.
See Organizations for BILL partners to learn more about creating an organization as a BILL partner.
IMPORTANT
This operation requires partner-level permissions.
- A
sessionId
header value generated with/v3/partner/login
- An
appKey
header value- The
organizationId
of the organization
Creating an user
In your POST /v3/partner/users
request, set the required fields.
Field | Description |
---|---|
firstName | User first name |
lastName | User last name |
email | User email address |
username | Username for signing in as the user |
acceptTermsOfService | Set as true if the user accepts the BILL terms of service |
Sample request
In this cURL example, a user is created for the organization (organizationId
) specified in the request header. 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/partner/roles
.
NOTE
If you do not set
roleId
in yourPOST /v3/partner/users
request, the defaultADMINISTRATOR
user role is assigned to the created user.
curl --request POST \
--url 'https://gateway.stage.bill.com/connect/v3/partner/users' \
--header 'content-type: application/json' \
--header 'appKey: {application_key}' \
--header 'sessionId: {partner_session_id}' \
--header 'organizationId: {organization_id}' \
--data '{
"firstName": "Tomato",
"lastName": "Soupsmith",
"email": "[email protected]",
"roleId": "{role_id}",
"username": "tsoupsm!th1",
"acceptTermsOfService": true
}'
Response
In the response, a BILL-generated user id
is available. The value begins with 006
. The created user is assigned the CLERK
role.
See User roles and permissions in the BILL Help Center to learn about BILL user roles.
{
"id": "{user_id}",
"archived": false,
"firstName": "Tomato",
"lastName": "Soupsmith",
"email": "[email protected]",
"role" : {
"id": "{role_id}",
"type": "CLERK",
"description": "Clerk user role"
},
"createdTime": "2024-12-20T22:16:27.000+00:00",
"updatedTime": "2024-12-20T22:16:27.000+00:00"
}
You can use the generated user id
for other partner-level and organization-level BILL operations. You can also sign in as the created user and perform organization-level BILL API operations.
Initiating BILL risk verification
When you create an organization and then create a user for that organization, it is important that you add a phone number for the created user (with POST /v3/partner/risk-verifications/{userId}/phone
), and then initiate risk verification (with POST /v3/risk-verifications
).
NOTE
See /v3/partner/risk-verifications/{userId}/phone in the API reference for more information about adding a phone number for a created 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 risk approval for the organization. |
Signing in as a user
In your POST /v3/partner/login-as-user
request, set the required fields.
Field | Description |
---|---|
sessionId header value | API session ID generated with /v3/partner/login |
appKey header value | Application key sent to you by BILL when you create a partner account |
organizationId | BILL-generated ID of the organization you want to sign in to |
userId | BILL-generated ID of the user you want to sign in as |
In the response, a BILL-generated sessionId
is available. Use this sessionId
and devKey
for performing organization-level BILL API operations, such as creating a bill or paying a vendor.
Updated 2 months ago