Connect with a private organization in the BILL Network

When you search for organizations in the BILL Network, the search result do not include vendor and customer organizations that have the Network profile visibility set as Private. If you send a connection request to a private organization that has auto-connections disabled, the organization must accept your request for you to be connected with the organization.

See Network Profile Visibility Settings in the BILL Help Center to learn about the different profile visibility settings.

❗️

The private organization must manually send their PNI to you

The private organization must manually send their PNI to you for you to send them a connection request with the BILL API. The organization PNI is available in the BILL web app (Settings > Company Profile > Network).

Connecting with a private organization in the BILL Network is a 2-step process.

1. Send a connection request
2. Accept the connection request

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 you created in your BILL organization. Retrieve the vendorId with GET /v3/vendors. In addition, networkId is set as the PNI id that you manually receive from the private organization.

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 connect request, BILL sends a connection request email to the private vendor.

Accept the connection request

Accept the connection request with POST /v3/network/invitation/accept.

👍

This endpoint is required only for private organizations that have auto-connections disabled

The private organization receiving the connection request must have auto-connections disabled. If auto-connections are not disabled, BILL automatically connects the organizations in the BILL Network.

In this cURL example, a private vendor organization accepts an invitation from the customer. In the request, networkId is set as the PNI of the customer organization that sent the invitation. Since your BILL organization is the customer that sent this invitation, retrieve the networkId of your BILL organization with GET /v3/network.

In addition, name is set as the new name of the customer to be added in the BILL organization accepting the invitation, and type is set as CUSTOMER to specify that invitation is accepted from a customer.

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

When the invited vendor accepts the invitation, BILL creates a new customer with this name and fills in information about the customer that sent the invitation. BILL also enables payments between the connections.