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.

❗️

BILL partner operations have additional requirements

This operation requires partner-level permissions.

• A sessionId header value generated with /v3/partner/login
• An appKey header value
• The organizationId of the organization

Create an user

In your POST /v3/partner/users request, set the required fields.

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.

👍

The default user role is ADMINISTRATOR

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: {partner_app_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": "2025-12-20T22:16:27.000+00:00",
    "updatedTime": "2025-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.

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

A set of processingStatus values are available in the API response when risk verification is in progress.

A set of decision status values are available when BILL has made a risk verification decision.

Sign in as a user

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

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.

MFA-trusted API session

Set both rememberMeId and device as additional fields in your POST /v3/partner/login-as-user request to create an MFA-trusted API session.