The Bill.com Developer Platform lets you interact with the Bill.com service through easy-to-use APIs, enabling you to automate the actions that a Bill.com user would perform through our application. This documentation walks you through various aspects of the platform, to get you started on building a high-quality integration with Bill.com. 

Actors

Developer

Developers are independent of organizations or users within the Bill.com system, and would register with Bill.com in order to provide an integration with another application or value-added service in addition to the Bill.com service. Each developer is identified by a unique Developer Key, which needs to be passed with every API call.

Organization

Organizations are the entities that reflect real-world businesses. An organization may have one or more users with access to the various functions within the organization (such as creating bills, approving bills, making a payment, etc). Performing an operation for a specific organization is achieved by creating a login session with username, password, and organization ID (a unique identifier which is required for most API calls), and passing the session ID with each operation.

User

One or more users can access an organization, and one user can have the same login credentials associated with more than one organization. Therefore, both the user and the organization need to be passed on every API call, so we know which user is performing the operation, and in which organization to perform the operation. This is achieved by creating login session with user name, password and organization id and passing the session id with each operation.

For API calls only, the user login credentials can be replaced by a Token name and password. A Token can be generated on the Bill.com application and can only be used for API calls.

Entity

Entity is a Business Object in the Bill.com system that is acted upon to achieve a certain objective. For example, to make a bill payment, you need an entity of a type Vendor that is getting paid, an entity of type Bill that is being paid, and an entity of type SentPay for the payment. 

Working with Bill.com Business Objects

The developer platform provides a framework that all entities comply with, making it easy to understand the different entities, and the operations that can be performed. All entities (exceptions noted) can be created, updated and read using the same set of CRUD (Create, Read, Update & Delete) operations. They all follow the same rules and same format for API request and responses.  All entities can also be listed and searched using the List & Search APIs, as descibed in the API Reference section. 

When creating an entity, the Create API call needs to pass in all the fields that are marked as 'required'. When updating an entity, only the Object Id and the fields to be updated need to be passed. Some fields are read-only, and hence cannot be updated using an Update operation. Those fields that are read-only in the Update operation are ignored and not changed. To read, delete and undelete an entity, only the Object Id needs to be passed. All the CRUD operations always return the complete entity in the response.  

The action and type of entity are specified in each operation's URL:
<API End Point URL>/Crud/<Operation>(e.g. Create/Read/Update/Delete/Undelete)/<Entity URL>.json

Entity Create Read Update Delete Undelete Entity URL
Approval Policy ApprovalPolicy
Approval Policy Approver ApprovalPolicyApprover
BankAccount BankAccount
Bill (AP) Bill
Bill Payment (AP)
PayBills: pay via Bill.com;
RecordAPPayment: record
payments made outside of Bill.com


VoidAPPayment

CancelAPPayment

SentPay
Chart of Account ChartOfAccount
Class ActgClass
Customer Customer
Customer Bank Account ✓ (Needs special

permission)

CustomerBankAccount
Customer Contact CustomerContact
Department Department
Employee Employee
Inbox Document
UploadAttachment
n/a
Invoice (AR)


RecordARPayment

ChargeCustomer (needs special

permission)


VoidARPayment
Invoice
Invoice Payment (AR) ReceivedPay
Invoice Product Item
Job Job
Location Location
Money Movement

MoneyMovement
Organization
(Available for bank partners only)

(Read and ListOrgs)

(Available for bank partners only)

(Available for bank partners only)

Organization
Recurring Bill RecurringBill
User User
Vendor Vendor
Vendor Bank Account
(Needs special
permission)
VendorBankAccount
Vendor Credit VendorCredit

Getting an Organization ID

Most of the operations in Bill.com are associated with an organization, and thus need an organization id to be passed in the Login call.

To get a list of organizations that a user has access to, invoke the ListOrgs operation, which takes in username and password for the user. Organizations ids can be read from the response of this operation, and can be used in the Login request to obtain a session id, which will be used in the subsequent API calls. The organization ID can also be found by logging into Bill.com, clicking the gear icon, and then clicking Your Company > Profile. It can be found at the end of the url,  ".../Organization?id=" .

Authentication and Session Management

Every API request needs a valid session id, which is obtained by issuing a Login request. Login API takes in an organization id, developer (or application) key, and user credentials (or Token), and returns a valid session id, as well as an end-point URL, which should be used for any subsequent API requests. This session id will remain valid for up to 35 minutes without activity. If the session becomes inactive, you will have to issue a new Login request and obtain a new session ID. You can explicitly end the session by issuing a Logout request.

Throttling

The request limit for each Bill.com organization is 18,000 requests per developer key, per hour.  If you exceed this limit, you will get the following error:

{
  "response_status" : 1,
  "response_message" : "Error",
  "response_data" : {
    "error_code" : "BDC_1144",
    "error_message" : "Max number of allowed requests per hour reached: 18000."
  }
}

Once you receive this error, subsequent API calls will have to wait until the next hour.

The concurrent request limit for each Bill.com organization is 3, per developer key, per organization. If the maximum number of concurrent requests have been made, all subsequent calls will fail until one of the initial requests completes.  If you exceed this limit, you will get the following error:

{
  "response_status" : 1,
  "response_message" : "Error",
  "response_data" : {
    "error_code" : "BDC_1322",
    "error_message" : "Max number of concurrent requests per organization reached."
  }
}

It is important that your application is able to handle this error and retry appropriately.

To avoid this error, your application should set an upper bound for the total the number of concurrent calls as well as implement throttling to spread out your calls evenly.

Auditing

Any changes to records in Bill.com will be logged in the entity's audit trail, which you can view on the Bill.com application. In the audit trail, changes made using the API show "-API" in front of the user's (or Token's) name, in order to differentiate them from changes made using the application UI, or other methods.

Permissions

Operations invoked through the Bill.com API are executed using the same Bill.com business logic as if they had been issued on the Bill.com application. The business logic includes verifying that the user has adequate permissions to execute the operation. The results of the business logic, including error information, are contained in the response of the Bill.com API.

To access any data via the API, the user needs the permission to manage the entity that they are trying to access via the API. For example, only users who are authorized to make payments from the default bank account for Payables can make PayBills call via the API.