Creating a US vendor

In your POST /v3/vendors request, set the required fields to create a US vendor.

FieldDescription
nameVendor name
accountTypeVendor account type (BUSINESS, PERSON, or NONE)
emailVendor email address
phoneVendor phone number
addressVendor address information. Vendor address details are required for paying the vendor by check or for inviting the vendor to join the BILL network.
- line1
- city
- zipOrPostalCode
- country
paymentInformationVendor bank account information. Vendor bank account details are required for enabling electronic payments to the vendor.
- payeeName
- nameOnAccount
- accountNumber
- routingNumber

See the /v3/vendors API for more information about the other vendor fields you can set.

Sample request

In this cURL example, a vendor is created with the specified details. The address and paymentInformation details are added to enable electronic payments to the vendor.

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

Response

In the response, a BILL-generated vendor id is available. This value begins with 009. You can use this vendor id for other BILL operations.

{
  "id": "{vendor_id}",
  "archived": false,
  "name": "Happy Music Supplies",
  "accountType": "BUSINESS",
  "email": "[email protected]",
  "phone": "9876543210",
  "address": {
    "line1": "123 Main St",
    "city": "San Jose",
    "stateOrProvince": "CA",
    "zipOrPostalCode": "95002",
    "country": "US"
  },
  "paymentInformation": {
    "payeeName": "Happy Music Supplies",
    "payByType": "ACH",
    "virtualCard": {
      "status": "UNENROLLED"
    },
    "bankAccount": {
      "nameOnAccount": "Bill Venderson",
      "accountNumber": "*****2333",
      "routingNumber": "074000010",
      "createdBy": "{user_id}",
      "type": "CHECKING",
      "ownerType": "BUSINESS"
    }
  },
  "additionalInfo": {
    "track1099": false,
    "combinePayments": true
  },
  "bankAccountStatus": "NO_NET_LINKED_ACCOUNT",
  "recurringPayments": false,
  "billCurrency": "USD",
  "createdTime": "2024-12-29T23:25:27.000Z",
  "updatedTime": "2024-12-29T23:25:28.000Z",
  "balance": {
    "amount": 0
  },
  "autoPay": {
    "enabled": false
  }
}

See the /v3/vendors API for more information about the complete list of vendor operations.