BILL Spend & Expense API
Guides
System status

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.

ComponentDescription
<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>.jsonUse <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 methodBILL API requests use the HTTPS POST method.

The one exception is for retrieving bill or invoice attachments with the /GetDocumentPages.json API.
ParametersAfter 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 typeSet 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, and sessionId.

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 validationDescription
< and > charactersThe < and > characters are not permitted as text input in API requests. These characters are encoded as &lt; and &gt; respectively in responses.
Character length limitThe character length limit is 4000.
URLsBILL and all its partnered financial institutions are allowlisted URLs. Any other URL is not permitted.
Non-printable ASCII charactersA 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 3 months ago