System status

BILL API Reference Overview (v3 BETA)

❗️

Changes to BILL API access

At this time, we are providing BILL API access only for select partners. Please reach out to your account manager for more information.

🚧

BILL v3 API is currently in BETA

The BILL v3 API is currently in beta and is subject to improvements and changes. All improvements and changes will be documented.

For any BILL v2 API feature that is not available with the v3 API, you can continue to use the stable v2 API for that feature.

The API Reference section enables you to view sample code in your choice of language and also test API calls in the documentation.

Use the BILL API to integrate your application with BILL Accounts Receivable (AR) and Accounts Payable (AP) automation capabilities.

Prerequisites

Sign in to your BILL developer account with the POST /v3/login API endpoint. The required fields for signing in are username, password, organizationId, and devKey.

Sign in credentialsDescription
UsernameYour username is the email address used to sign in to your BILL developer account.
PasswordYour password is used to sign in to your BILL developer account.
Organization IDYour BILL developer account represents your organization in BILL. The organization ID is a unique alphanumeric value that begins with 008.
Developer keyYour developer key is used to identify your developer account in your API requests.

You sign in as an organization user

When you sign in to your BILL developer account, 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.

Sample request

In this cURL example, you sign in to your BILL developer account in the API sandbox environment with POST /v3/login. See Development environments for information about the API sandbox and production environments.

📘

NOTE

The header value in the v3 API requests is content-type: application/json.

curl --request POST \
--url 'https://gateway.stage.bill.com/connect/v3/login' \
--header 'content-type: application/json' \
--data '{
  "username": "{username}", 
  "password": "{password}",
  "organizationId": "{organization_id}", 
  "devKey": "{developer_key}"
}'

Response

In the response, your API session is created and a generated sessionId is available. Use the sessionId in all subsequent API calls to confirm that you are in a signed-in API session. In addition, userId is the BILL-generated ID of the signed-in user.

{
    "sessionId": "{session_id}",
    "organizationId": "{organization_id}",
    "userId": "{user_id}"
}

See API login in the API reference for more information.