API request format

All Bill.com API requests follow a set of rules.

Example requests

Example 01: Sign in to your sandbox developer account

In this example, you sign in to your Bill.com sandbox developer account with /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 Sign up process for more information.

curl --request POST \
--url '<API_Base_URL>/Login.json' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data 'userName={username}' \
--data 'password={password}' \
--data 'orgId={organization_id}' \
--data 'devKey={developer_key}'

Example 02: Create a bill

In this example, you create a bill with /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 '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" : "2022-02-07",
    "dueDate" : "2022-02-10",
    "billLineItems" : [ {
      "entity" : "BillLineItem",
      "amount" : 15.00
    } ]
  }
}'

❗️

WARNING

Personal Identifiable Information (PII) is NOT safe as query string parameters.
Bill.com 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.

Request format details

Format

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.com web app audit trail. In the audit trail, the username is displayed in the Username-API format.

See Audit trails in the Bill.com Help for more information.

<Entity>.json

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

You can set the entity value for different Bill.com business objects - Organization, Accounts Receivable (AR), Accounts Payable (AP), Bill approvals, and Bill.com network operations.

Request method

Bill.com 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.com API requests to application/x-www-form-urlencoded.

Parameter data types

The Bill.com 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.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 &lt; and &gt; 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

There are no symbols to represent non-printable ASCII characters and we cannot type them with our keyboards.

Audit trails in the Bill.com web app

When a record is modified with a Bill.com API, an audit trail is logged in the Bill.com web app. In the web app audit trail, the user's name is saved as <name>-API. See Audit trails in the Bill.com Help for more information.


Did this page help you?