BIbill
vendors

Create a vendor

Changed on

Create a new vendor.

Requirements for enabling vendor payments

Vendor address details are required for paying a vendor by check or for inviting the vendor to join the BILL network.

  • line1
  • city
  • stateOrProvince
  • zipOrPostalCode
  • country
  • payeeName

Note: A vendor can be enrolled to accept virtual card payments even without being connected in the BILL network. See Virtual card FAQ in the BILL Help Center for more information.

Address state/province rules for international vendors

The address.stateOrProvince field enforces strict validation for the US, Canada, and Australia:

  • United States (US): 2-character state code (for example, CA, NY).
  • Canada (CA): 2-character province code (for example, AB, BC, ON).
  • Australia (AU): 2 or 3-character state code (for example, WA, NT, ACT, NSW, QLD).
  • All other countries: Free text. Enter the full state or province name (for example, Île-de-France or Bavaria).

Note: Sending a full state or province name for US, Canadian, or Australian addresses returns a 400 Bad Request error. See International vendor in the Guides section for more information.

Requirements for enabling electronic payments to vendors

Vendor bank account details are required for paying a vendor with electronic payment methods.

paymentInformation details about bank accounts are required for adding a vendor bank account.

  • payeeName
  • bankCountry (for international vendors)
  • paymentCurrency (for international vendors)
  • nameOnAccount
  • accountNumber
  • routingNumber (empty for an IBAN accountNumber)
  • type (for international vendors)

regulatoryFields and paymentPurpose are additional required fields for enabling electronic payments to international vendors (not United States) in specific countries.

Note: When you add a vendor bank account in the production environment, BILL requires 2 business days to complete a one-time verification of the bank account. To pay such a vendor, you must set a processDate that is 2 business days from the current date.

See Vendors in the Guides section for more information, sample requests, and responses.

post/v3/vendors

Request

  • Base URL
    https://gateway.stage.bill.com/connect
  • URL
    https://gateway.stage.bill.com/connect/v3/vendors
  • Auth
    none declared

Headers

sessionIdstring nullable

API session ID generated with /v3/login

Example:{{session_id}}
devKeystring nullable

Developer key generated with your BILL developer account

Example:{{developer_key}}

Request body

namestring required

Vendor name

shortNamestring

Vendor short name

accountNumberstring

User account number set by the vendor. Set this field as the billing statement account number for vendor services such as utility or credit card bills.

When you pay the vendor, this value appears on the check memo or electronic payment record.

accountType'NONE' | 'BUSINESS' | 'PERSON'

Vendor account type

emailstring

Vendor email address

phonestring

Vendor phone number

billCurrency'AED' | 'AFN' | 'ALL' | 'AMD' | 'ANG' | 'AOA' | 'ARS' | 'AUD' | 'AWG' | 'AZN' | 'BAM' | 'BBD' | 'BDT' | 'BGN' | 'BHD' | 'BIF' | 'BMD' | 'BND' | 'BOB' | 'BRL' | 'BSD' | 'BTN' | 'BWP' | 'BYN' | 'BZD' | 'CAD' | 'CDF' | 'CHF' | 'CLP' | 'CNY' | 'COP' | 'CRC' | 'CUC' | 'CUP' | 'CVE' | 'CZK' | 'DJF' | 'DKK' | 'DOP' | 'DZD' | 'EGP' | 'ERN' | 'ETB' | 'EUR' | 'FJD' | 'FKP' | 'GBP' | 'GEL' | 'GGP' | 'GHS' | 'GIP' | 'GMD' | 'GNF' | 'GTQ' | 'GYD' | 'HKD' | 'HNL' | 'HRK' | 'HTG' | 'HUF' | 'IDR' | 'ILS' | 'IMP' | 'INR' | 'IQD' | 'IRR' | 'ISK' | 'JEP' | 'JMD' | 'JOD' | 'JPY' | 'KES' | 'KGS' | 'KHR' | 'KMF' | 'KPW' | 'KRW' | 'KWD' | 'KYD' | 'KZT' | 'LAK' | 'LBP' | 'LKR' | 'LRD' | 'LSL' | 'LYD' | 'MAD' | 'MDL' | 'MGA' | 'MKD' | 'MMK' | 'MNT' | 'MOP' | 'MRU' | 'MUR' | 'MVR' | 'MWK' | 'MXN' | 'MYR' | 'MZN' | 'NAD' | 'NGN' | 'NIO' | 'NOK' | 'NPR' | 'NZD' | 'OMR' | 'PAB' | 'PEN' | 'PGK' | 'PHP' | 'PKR' | 'PLN' | 'PYG' | 'QAR' | 'RON' | 'RSD' | 'RUB' | 'RWF' | 'SAR' | 'SBD' | 'SCR' | 'SDG' | 'SEK' | 'SGD' | 'SHP' | 'SLE' | 'SLL' | 'SOS' | 'SPL' | 'SRD' | 'STN' | 'SVC' | 'SYP' | 'SZL' | 'THB' | 'TJS' | 'TMT' | 'TND' | 'TOP' | 'TRY' | 'TTD' | 'TVD' | 'TWD' | 'TZS' | 'UAH' | 'UGX' | 'USD' | 'UYU' | 'UZS' | 'VEF' | 'VND' | 'VUV' | 'WST' | 'XAF' | 'XCD' | 'XDR' | 'XOF' | 'XPF' | 'YER' | 'ZAR' | 'ZMW' | 'ZWD'

Bill currency. Three-letter abbreviation in the ISO 4217 format.

The billCurrency value is the currency in which vendor bills are presented. The value is also the currency used in the invoices you receive from the vendor.

Note: When the vendor bill currency is not USD (For example, EUR), the payment processDate for this vendor must be the next US business day.

See <a href="https://help.bill.com/hc/en-us/articles/360007172671">Country information for international payments</a> in the BILL Help Center for the list of countries that accept international payments with BILL.

Example request

{
  "name": "Happy Music Supplies",
  "accountType": "BUSINESS",
  "email": "info@happymusicsupplies.org",
  "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

Create a vendor response

idstring

BILL-generated ID of the vendor. The value begins with 009.

archivedboolean required

Set as true if the vendor is archived

namestring

Vendor name

shortNamestring

Vendor short name

accountNumberstring

User account number set by the vendor.

When you pay the vendor, this value appears on the check memo or electronic payment record.

accountType'NONE' | 'BUSINESS' | 'PERSON' | 'UNDEFINED'

Vendor account type

emailstring

Vendor email address

phonestring

Vendor phone number. This field is overridden when you connect with a vendor in the BILL network.

rppsIdstring

BILL-generated ID of the verified national vendor (if the vendor is a verified national vendor)

bankAccountStatus'NO_ACCOUNT' | 'NO_NET_LINKED_ACCOUNT' | 'NET_LINKED_ACCOUNT' | 'UNDEFINED'

Vendor bank account status.

recurringPaymentsboolean

Set as true if the vendor has recurring payments enabled

billCurrency'AED' | 'AFN' | 'ALL' | 'AMD' | 'ANG' | 'AOA' | 'ARS' | 'AUD' | 'AWG' | 'AZN' | 'BAM' | 'BBD' | 'BDT' | 'BGN' | 'BHD' | 'BIF' | 'BMD' | 'BND' | 'BOB' | 'BRL' | 'BSD' | 'BTN' | 'BWP' | 'BYN' | 'BZD' | 'CAD' | 'CDF' | 'CHF' | 'CLP' | 'CNY' | 'COP' | 'CRC' | 'CUC' | 'CUP' | 'CVE' | 'CZK' | 'DJF' | 'DKK' | 'DOP' | 'DZD' | 'EGP' | 'ERN' | 'ETB' | 'EUR' | 'FJD' | 'FKP' | 'GBP' | 'GEL' | 'GGP' | 'GHS' | 'GIP' | 'GMD' | 'GNF' | 'GTQ' | 'GYD' | 'HKD' | 'HNL' | 'HRK' | 'HTG' | 'HUF' | 'IDR' | 'ILS' | 'IMP' | 'INR' | 'IQD' | 'IRR' | 'ISK' | 'JEP' | 'JMD' | 'JOD' | 'JPY' | 'KES' | 'KGS' | 'KHR' | 'KMF' | 'KPW' | 'KRW' | 'KWD' | 'KYD' | 'KZT' | 'LAK' | 'LBP' | 'LKR' | 'LRD' | 'LSL' | 'LYD' | 'MAD' | 'MDL' | 'MGA' | 'MKD' | 'MMK' | 'MNT' | 'MOP' | 'MRU' | 'MUR' | 'MVR' | 'MWK' | 'MXN' | 'MYR' | 'MZN' | 'NAD' | 'NGN' | 'NIO' | 'NOK' | 'NPR' | 'NZD' | 'OMR' | 'PAB' | 'PEN' | 'PGK' | 'PHP' | 'PKR' | 'PLN' | 'PYG' | 'QAR' | 'RON' | 'RSD' | 'RUB' | 'RWF' | 'SAR' | 'SBD' | 'SCR' | 'SDG' | 'SEK' | 'SGD' | 'SHP' | 'SLE' | 'SLL' | 'SOS' | 'SPL' | 'SRD' | 'STN' | 'SVC' | 'SYP' | 'SZL' | 'THB' | 'TJS' | 'TMT' | 'TND' | 'TOP' | 'TRY' | 'TTD' | 'TVD' | 'TWD' | 'TZS' | 'UAH' | 'UGX' | 'USD' | 'UYU' | 'UZS' | 'VEF' | 'VND' | 'VUV' | 'WST' | 'XAF' | 'XCD' | 'XDR' | 'XOF' | 'XPF' | 'YER' | 'ZAR' | 'ZMW' | 'ZWD'

Bill currency

createdTimestring date-time

Created date and time

updatedTimestring date-time

Updated date and time

networkStatus'NOT_CONNECTED' | 'PENDING' | 'CONNECTED' | 'CONNECTED_RPPS'

Network connection status. This field appears in the response only when a network connection status is available for the vendor.

paymentNetworkIdstring

Vendor Payment Network ID (PNI). Each vendor with a BILL account is assigned a unique PNI.

relevanceScorenumber double

Relevance score from the fuzzy name search that matched this vendor. This field appears in the response only for vendors matched by an fz filter on name.

Scores are comparable only among the results of a single search. Do not compare them across searches or against a fixed threshold.

Example response

{
  "paymentInformation": {
    "bankAccount": {
      "nameOnAccount": "Bill Vendorson",
      "accountNumber": "111222333",
      "routingNumber": "074000010",
      "type": "CHECKING",
      "ownerType": "BUSINESS",
      "paymentCurrency": "USD"
    }
  }
}

Changes

  • 54edddceb0a5Revision changes
    • breaking

      added subschema #2 to the ///// request property allOf list

    • breaking

      the request property ///// became required

    • breaking

      the request property ///// became required

    • breaking

      the request property ///// became required

    • breaking

      the request property ///// became required

    • breaking

      the ///// request property's minLength was increased from 0 to 1

    • breaking

      the ///// request property's minLength was increased from 0 to 1

    • breaking

      the ///// request property's minLength was increased from 0 to 1

    • breaking

      added the pattern ^.{0,1000}$ to the request property /////

    • breaking

      added the pattern ^.{0,100}$ to the request property /////

    • breaking

      added the pattern ^.{0,100}$ to the request property /////

    • breaking

      added the pattern ^.{0,100}$ to the request property /////

    • breaking

      added the pattern ^.{0,30}$ to the request property /////

    • breaking

      the ///// request property type changed from string to no type

    • breaking

      the /////////// response's property type changed from string to no type for status

    • breaking

      the /////////// response's property type changed from string to no type for status

    • info

      added the optional property to the response with the status

    • info

      added subschema #2 to the /////////// response property allOf list for the response status

    • info

      added subschema #2 to the /////////// response property allOf list for the response status