Connect with a vendor in the BILL Network

Search for and send a connection request to a vendor in the BILL Network. In this example workflow, your BILL organization is the customer that is sending a connection request to the vendor Happy Music Supplies in the BILL Network.

👍

BILL Network sandbox setup is required

Complete the BILL Network sandbox setup before proceeding with searching for and connecting with a BILL Network vendor.

Create a vendor in your organization

Create a vendor with the BILL web app or with POST /v3/vendors with the minimum required information. This is how you want to identify the vendor in your BILL organization.

In this cURL example, a vendor called Happy is created. This is how the vendor appears in your BILL organization.

curl --request POST \
--url 'https://gateway.stage.bill.com/connect/v3/vendors' \
--header 'content-type: application/json' \
--header 'devKey: {developer_key}' \
--header 'sessionId: {session_id}' \
--data '{
  "name": "Happy", 
  "accountType": "BUSINESS",
  "email": "[email protected]", 
  "phone": "9876543210",
  "address": {
    "line1": "123 Main Street",
    "city": "San Jose",
    "stateOrProvince": "CA",
    "zipOrPostalCode": "95002",
    "country": "US"
  },
  "billCurrency": "USD"
}'

Network connection status

You can get the Network connection status of a vendor when you create a vendor (POST/v3/vendors) or get vendor details (GET /v3/vendors or GET /v3/vendors/{vendorId}).

In the API response, networkStatus is available for providing information about the BILL Network connection status. This field can have one of four status values.

👍

Get Network connection status

You can get the Network connection status of a vendor when you create a vendor (POST/v3/vendors) or get vendor details (GET /v3/vendors or GET /v3/vendors/{vendorId}).

In the next set of steps, after you connect with a vendor called Happy Music Supplies in the BILL Network, BILL updates the created vendor called Happy with the Network vendor payment information.

Search for the vendor

Search for the vendor in the BILL Network with POST /v3/network. In this cURL example, a search request is sent for a vendor called Happy Music Supplies in the BILL Network.

curl --request GET \
--url 'https://gateway.stage.bill.com/connect/v3/network?name=Happy%20Music%20Supplies&scope=BILL' \
--header 'content-type: application/json' \
--header 'devKey: {developer_key}' \
--header 'sessionId: {session_id}'

In the response, the search result displays the Payment Network ID (PNI id) and address details of the vendor. Use the PNI id to send a connection request to the vendor in the BILL Network.

Send a connection request

Send a connection request to the vendor with POST /v3/network/invitation/vendor/{vendorId}.

In this cURL example, a connection request is sent to the vendor in the BILL Network. In the request, vendorId is set as the BILL-generated ID of the vendor record (called Happy) you created in your BILL organization. Retrieve the vendorId with GET /v3/vendors. In addition, networkId is set as the PNI id of the selected vendor from the Network search results.

curl --request POST \
--url 'https://gateway.stage.bill.com/connect/v3/network/invitation/vendor/{vendorId}' \
--header 'content-type: application/json' \
--header 'devKey: {developer_key}' \
--header 'sessionId: {session_id}' \
--data '{
  "networkId": "{PNI_id}",
  "networkType": "BILL"
}'

When you send the connection request, BILL automatically connects you with the organization. In this connection workflow, your organization is the customer and Happy Music Supplies is the vendor.