Business objects
In the Bill.com system, an Entity is defined as a business object. For example, a Bill payment requires a Vendor entity so that a Bill entity can be paid. The API request to pay a Bill creates a Sent Pay entity.
The developer platform is the framework to manage entities and perform operations. The APIs allow you to fetch and manipulate Entity data via CRUD operations (Create, Read, Update, and Delete). All API requests and responses follow common rules and formats.
- Create API calls must pass all the required fields.
- Update API calls require the Object ID, other mandatory fields, and updated fields.
Tip: The mandatory fields are highlighted in the sample request and marked as mandatory in the Parameters section of each API guide.
- An Update operation cannot modify read-only fields. Any such operation is ignored.
- Calls to Read, Delete, or Undelete an entity only need the Object ID.
- Responses of the CRUD operations return the complete set of entity parameters.
Organization ID
API operations in Bill.com are associated with an Organization.
Note: Companies may set up more than one Bill.com Organization.
To get a list of Organizations that a User can access, invoke the ListOrgs operation. You need to pass the Organization ID when calling the Login endpoint that generates the session ID. This specifies the Organization that the data needs to be fetched, created, updated, and deleted when the API calls are made.
To find the Organization ID, login to the Bill.com application. Go to Settings > Your Company > Profile and look at the end of the URL, ".../Organization?id=".
Authentication and session management
The Login request requires the username, password, dev key and organization ID to generate the session ID. To ensure that your API calls are authenticated, you need to pass the dev key and the session ID with each API request.
If API calls are not made for 35 minutes, the sessionId is marked as invalid and you need to call the Login endpoint to obtain a new session ID. A session can also be ended with a Logout request.
Audit trail
Record changes in Bill.com are logged in the entity's audit trail (available in the Bill.com UI). In the audit trail API changes are identified with -API in front of the user (or Token) name. This differentiates changes made with the application UI or other methods, such as Sync, Import/Export.
Throttle requests
For Login endpoint and ListOrgs endpoint, Bill.com has a request limit of 200 per developer key, per min.
Bill.com has an upper request limit of 18,000 per developer key, per hour. If exceeded, the following error displays:
{
"response_status" : 1,
"response_message" : "Error",
"response_data" : {
"error_code" : "BDC_1144",
"error_message" : "Max number of allowed requests per hour reached: 18000."
}
}When you get this error, subsequent API calls must wait until the next hour.
For each Bill.com Organization, the concurrent request limit is three per Developer Key and per Organization. When the maximum number of concurrent requests are made, all subsequent calls fail - until one of the initial requests are completed. If exceeded, this error is displayed:
{
"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 again.
To avoid this error, configure your application with an upper bound for total number of concurrent calls and throttling to evenly spread out the calls.