API Structure – Developer Support

In this section, we explain the Bill.com API request and response format.

Note: The Bill.com rate limit is 18,000 API calls per developer key per hour.

Endpoint format

A Bill.com endpoint includes a base URL, CRUD operation, and entity. Most endpoints are in the <API_Base_URL>/Crud/<Operation>/<Entity>.json format.

Note: There are a few exceptions to this format. See the API documentation for format details for each endpoint.

<API_Base_URL>

Sandbox: https://api-sandbox.bill.com/api/v2/

Production: https://api.bill.com/api/v2/

<Operation>

Many endpoints support all CRUD (Create, Read, Update, Delete) operations.

A select set of endpoints support Undelete and Bulk CRUD operations as well. See the API documentation for more information.

<Entity>.json

The <Entity>.json value in the endpoint format is used to define a Bill.com operation.

You can set the <Entity>.json value for different Organization, Accounts Receivable, Accounts Payable, Approve Payments, and Bill.com Network operations.

Request format

A Bill.com API request format includes the HTTP method, parameters, and content type.

Request method

Bill.com API requests use the HTTP POST method.

Note: The one exception is for retrieving bill or invoice attachments with GetDocumentPages.

Parameters

After logging in, most subsequent API calls require parameters for uniquely identifying your developer account and for specifying other required information.

devKey: The developer key shared with you at the time of provisioning your API access
sessionId: The session ID generated is generated in response to logging in to your developer account
data: In the data object, set required and optional parameters. See the API documentation for parameter details for each endpoint.

Content type The content-type in Bill.com API requests are set to application/x-www-form-urlencoded.

Example request

In this example, you create a bill with /Crud/Create/Bill.json. Set the devKey and sessionId values for uniquely identifying your developer account and for stating the current API session.

curl –request POST '<API_Base_URL>/Crud/Create/Bill.json' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data 'devKey={developer_key}&sessionId={session_ID}' \
--data 'data={
  "obj" : {
    "entity" : "Bill",
    "isActive" : "1",
    "vendorId" : "{vendor_ID}",
    "invoiceNumber" : "14800",
    "invoiceDate" : "2021-11-27",
    "dueDate" : "2021-11-30",
    "billLineItems" : [ {
      "entity" : "BillLineItem",
      "amount" : 15.00
    } ]
  }
}'

Response format

A Bill.com API response format includes fields for response status and data.

`response_status`	`0`: Success `1`: Error
`response_message`	`Success` `Error`
`response_data`	Operation-specific response data if the request is successful. Error code and error message if the request is invalid or incomplete.

Object types

The Bill.com API request and response objects can be of different data types. See the API documentation for information about parameters and their data types.

Text input validation

All Bill.com text input fields are free-form. Validating input in freeform text fields ensures that no bad data is in circulation. The result of any validation exception is the BDC_1544 error code and Validation exception: ${paramName0}, fieldName: ${paramName1} error message.

Text input validation	Description
< and > characters	The < and > characters are not permitted as text input in API requests. These characters are encoded as `<` and `>` respectively in responses.
Character length limit	The character length limit is 4000
URLs	Bill.com and all its partnered financial institutions are allowlisted URLs. Any other URL is not permitted.
Non-printable ASCII characters	A select list of non-printable ASCII characters are not permitted as text input in API requests. `NULL`, `SOH`, `STX`, `ETX`, `EOT`, `ENQ`, `ACK`, `BEL`, `BS`, `SO`, `SI`, `DLE`, `DC1`, `DC2`, `DC3`, `DC4`, `NAK`, `SYN`, `ETB`, `CAN`, `EM`, `SUB`, `ESC`, `FS`, `GS`, `RS`, `US`, and `DEL` Note: There are no symbols to represent non-printable ASCII characters and we cannot type them with our keyboards.