We have introduced a new Get API session details (GET /v3/login/session) endpoint. You can now get information about the current organization, current user, and MFA status of the organization.

See GET /v3/login/session in the API reference for more information.

An MFA ID is generated when you set rememberMe as true in your POST /v3/mfa/challenge/validate request.

To create a new MFA-trusted API session, you can now set an MFA ID and device name in your API login (POST /v3/login) request. In addition, BILL partners can create a new MFA-trusted API session by setting an MFA ID and device name in the API login as user (POST /v3/partner/login-as-user) request.

See POST /v3/login and POST /v3/partner/login-as-user in the API reference for more information.

We have introduced Guides section documentation for working with the BILL Spend & Expense API. The BILL Spend & Expense API enables you to build with virtual card and expense management services for real-time visibility and control over the finances of a business.

On September 13, 2024, BILL will update the current API certificate for api.bill.com. Updating API certificates every 90 days is a common practice for maintaining a high level of security. We expect no impact to API services unless you are pinning certificates or are managing them manually.

BEST PRACTICE: Avoid certificate pinning

We highly recommend that you do not pin any BILL API certificates. Certificate pinning is not scalable, requires maintenance, and can cause downtime for your integrations in the production environment.

If you are pinning certificates for api.bill.com, update the certificate to use all five Root CAs listed on https://pki.goog/repository/ (GTS Root R1, GTS Root R2, GTS Root R3, GTS Root R4, and GlobalSign R4).

For questions or concerns, email us at [email protected].

We have introduced new features for the BILL webhook API. BILL partners can now perform subscription and event operations at the partner level.

As a BILL partner, when you create a subscription for events, you get event notifications for all the organizations created with your partner appKey. To create a subscription at the partner level, simply set the required header values. The base URL and body parameters in the POST /v3/subscriptions request are the same for partner users and organization users.

We have introduced a set of Multi-Factor Authentication (MFA) API endpoints. There are two stages in the BILL MFA process.

1. MFA setup: Add a valid phone number for setting up MFA in the organization (with POST /v3/mfa/setup), and then complete the setup by validating the entered phone number (with POST /v3/mfa/validate). At this point, the phone number is registered for the MFA sign in operation.

2. MFA sign in: Generate an MFA challenge (with POST /v3/mfa/challenge), and then complete MFA sign in by validating the MFA challenge (with POST /v3/mfa/challenge/validate). At this point, your API session is MFA trusted.

The PENDING risk verification decision status is now updated to IN_PROGRESS. We made this update for further simplifying the meaning of different status values.

See POST /v3/risk-verifications in the API reference for more information.

In the payments API response, you now receive information about the bills that a payment amount is applied to.

When you pay a bill with POST /v3/payments or when you pay multiple bills with one POST /v3/payments/bulk, you now see a billPayments object in the response. For each bill payment, the billPayment object includes the bill payment id, bill id, and amount applied to the bill.

See Payments for more information.

BILL is introducing a more stable sandbox environment for you to continue testing with the BILL v2 API - https://api-stage.bill.com/api/v2/. In addition, we have migrated the developer keys of all current API customers to the new environment.

On August 31, 2024, BILL will sunset the current sandbox environment. To continue testing with the BILL v2 API, set up a test organization in the new environment and start making your v2 API calls with the new base URL. See the next set of sections in this email for more information.

📘

NOTE

August 31, 2024 onwards, after the current sandbox environment is sunset, your test data in the current sandbox environment will not be available.

This change does not affect any integrations in the BILL production environment.

URL changes

The API base URL and web app URL is changing as part of introducing the new sandbox environment.

Developer actions

Now that the developer key migration is complete, you can take advantage of testing with the new sandbox environment.

Complete the provided set of recommended steps.

1. Sign up and create a new BILL developer account at https://www-test.bill.com/signup?env=stage. Make sure that you enter the email address you use for your current sandbox developer account.
2. Select Accounts Payable & Receivable and click Get Started to complete your BILL account activation flow. This includes adding a valid phone number for the two-step verification process.
3. When your sign-up is complete, you land on the Get started section. You can continue testing with BILL features. For example, adding a vendor, bill, customer, and invoice.
4. At any point, you can sign in to your developer account at https://login.stage.us.bill.com/neo/login with your created user name (email address) and password.

API sign in credentials

Set the required fields to sign in with /v2/Login.json.

Sample /v2/ListOrgs.json request

curl --request POST \
--url 'https://api-stage.bill.com/api/v2/ListOrgs.json' \
--header 'accept: application/json' \
--header 'content-type: application/x-www-form-urlencoded' \
--data 'userName={email_address}' \
--data 'password={password}' \
--data 'devKey={developer_key}'

Sample /v2/Login.json request

curl --request POST \
--url 'https://api-stage.bill.com/api/v2/Login.json' \
--header 'accept: application/json' \
--header 'content-type: application/x-www-form-urlencoded' \
--data 'userName={username}' \
--data 'password={password}' \
--data 'devKey={developer_key}' \
--data 'orgId={organization_id}'

After signing in, you can continue testing with BILL v2 API operations, including adding a vendor, creating a bill, and submitting a payment. For questions or concerns, email us at [email protected].

We have added pagination in the get list of event notifications (GET /v3/events/subscription/{subscriptionId}) and get list of subscriptions (GET /v3/subscriptions) endpoints.

See Get list of event notifications and Get list of subscriptions for more information.