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.

FieldDescription
firstNameUser first name
lastNameUser last name
emailUser email address
usernameUsername for signing in as the user
acceptTermsOfServiceSet 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 your POST /v3/partner/users request, the default ADMINISTRATOR 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.

ValueDescription
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 risk approval for the organization.

Signing in as a user

In your POST /v3/partner/login-as-user request, set the required fields.

FieldDescription
sessionId header valueAPI session ID generated with /v3/partner/login
appKey header valueApplication key sent to you by BILL when you create a partner account
organizationIdBILL-generated ID of the organization you want to sign in to
userIdBILL-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.