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.

Sample request

In this cURL example, a user is created for the organization (organizationId) specified in the request header.

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]",
  "username": "tsoupsm!th1",
  "acceptTermsOfService": true
}'

Response

In the response, a BILL-generated user id is available. The value begins with 006. At the partner level, all created users have the ADMINISTRATOR user 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": "ADMINISTRATOR"
    },
    "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 initiate risk verification with POST /v3/risk-verifications.

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.

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