BILL v3 API in Postman

In the API reference section, you can test with the BILL v3 API endpoints and get an actual response. For example, fill in the required fields for creating a customer (name, email, sessionId, and devKey) and click Try It! to see the server response.

Since the BILL v3 API documentation is auto-generated with OpenAPI, you can also import the OpenAPI specification in Postman and test with the API endpoints on Postman.

📘

NOTE

This section assumes that you have a Postman account and access to the Postman app (or web app). See postman.com for more information.

Importing the OpenAPI spec in Postman

Use the published BILL v3 API OpenAPI specification in the next set of steps.

  1. Copy the contents of the OpenAPI specification.
  2. In Postman, click File > Import. The import modal appears.
  3. Paste the contents of the OpenAPI specification. Postman provides two options for importing the specification.
  4. Select the Postman Collection option and click Import.

The BILL v3 API is imported as Connect API in your Postman Workspace under Collections.

Setting up your sandbox environment

When you save all your sandbox environment variables in Postman, you can simply refer to the variables when you are testing with the API.

For example, if you save the base URL as a baseUrl variable, you can then use the variable for any API operation, such as creating a customer. In this case, the path in Postman will be POST {{baseUrl}}/v3/customers.

  1. In your Postman Workspace, click New > Environment. Set up the environment variables for your sandbox environment.
VariableCurrent value
baseUrlhttps://gateway.stage.bill.com/connect
usernameYour username
passwordYour password
devKeyYour developer key
orgIdYour organization ID
  1. Click Save to save this sandbox environment information.

The environment is available in Postman under Environments. You can set this environment from the list at the top-right in Postman.

Signing in with /v3/login in Postman

When you are ready to test with the BILL v3 API in Postman, sign in with POST /v3/login.

  1. Under Collections, click Connect API > v3 > login > API login. The POST /v3/login endpoint appears.
  2. Under Body, set the type as raw, and update the required information. In this example, we update the variable names that we saved as environment variables in the previous section.
{
  "devKey": "{{devKey}}",
  "organizationId": "{{orgId}}",
  "password": "{{password}}",
  "username": "{{username}}"
}
  1. Under Tests, paste the following code to save the sessionId value as an environment variable in Postman for all your subsequent API calls.
let jsonData = pm.response.json();
let sessionId = jsonData.sessionId;
pm.globals.set("sessionId", sessionId);
  1. Click Save, and then click Send. The success 200 OK response is available. The response includes the sessionId, which is required for all subsequent API calls along with your developer key.

For example, for creating a customer (Connect API > v3 > customers > Create a customer), when you set sessionId as {{sessionId}} and devKey as {{devKey}} under Headers, these values are set by the sandbox environment variables.