API request format
All BILL API requests follow a set of rules. In this section, we explain the request format details and then showcase examples.
Request format details
A BILL API request can be broken down into different components.
Component | Description |
---|---|
<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.Any record modifications made using the API are recorded in the BILL web app audit trail. In the audit trail, the username is displayed in the Username-API format.See Audit trails in the BILL Help Center for more information. |
<Entity>.json | Use <Entity>.json value in the endpoint format to define a BILL operation.You can set the entity value for different BILL business objects - Organization, Accounts Receivable (AR), Accounts Payable (AP), Bill approvals, and BILL network operations. |
Request method | BILL API requests use the HTTPS POST method.The one exception is for retrieving bill or invoice attachments with the /GetDocumentPages.json API. |
Parameters | After signing 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 : A session ID is generated in response to signing 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 | Set the Content-Type value in BILL API requests to application/x-www-form-urlencoded . |
Example requests
Signing in to your sandbox developer account
In this example, you sign in to your BILL sandbox developer account with /v2/Login.json
.
The required fields for signing in are userName
, password
, orgId
, and devKey
. Retrieve these values as part of your sandbox sign up process. See API sign up process for more information.
curl --request POST \
--url '<API_Base_URL>/Login.json' \
--header 'accept: application/json' \
--header 'content-type: application/x-www-form-urlencoded' \
--data 'userName={username}' \
--data 'password={password}' \
--data 'orgId={organization_id}' \
--data 'devKey={developer_key}'
Creating a bill
In this example, you create a bill with /v2/Crud/Create/Bill.json
. Set devKey
for uniquely identifying your developer account and sessionId
for providing the currently signed in API session.
In response, a new bill is created and a unique bill id
is generated.
curl –request POST \
--url '<API_Base_URL>/Crud/Create/Bill.json' \
--header 'accept: application/json' \
--header 'content-type: application/x-www-form-urlencoded' \
--data 'devKey={developer_key}' \
--data 'sessionId={session_id}' \
--data 'data={
"obj":{
"entity": "Bill",
"isActive": "1",
"vendorId": "{vendor_id}",
"invoiceNumber": "14800",
"invoiceDate": "2024-12-07",
"dueDate": "2024-12-10",
"billLineItems": [{
"entity": "BillLineItem",
"amount": 15.00
}]
}'
WARNING
Personal Identifiable Information (PII) is NOT safe as query string parameters.
BILL PII includes (but is not limited to)userName
,password
,devKey
, andsessionId
.URLs are commonly stored in browser histories and server logs. In an API request, sending sensitive information with query string parameters is not safe.
If an attacker has access to a URL that includes query string parameters, they may have access to the PII.
Parameter data types
The BILL API request objects can be of different data types. See the API documentation for information about parameters and their data types.
API text input validation
All BILL text input fields are free-form. Validating input in freeform text fields ensures that no bad data is in circulation. All API text input is validated based on a set of rules.
The result of any validation exception is the BDC_1544
error code.
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 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 is 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 There are no symbols to represent non-printable ASCII characters. These characters cannot be typed with a keyboard. |
Audit trails in the BILL web app
When a record is modified with a BILL API, an audit trail is logged in the BILL web app. In the web app audit trail, the user's name is saved as <name>-API
. See Audit trails in the BILL Help Center for more information.
Updated 28 days ago