× FreshBooks App Logo
FreshBooks
Official App
Free - Google Play
Get it
You're currently on our US site. Select your regional site here:
Buy Now & Save Login
Buy Now & Save Try It Free Login
Login Buy Now & Save Try It Free Login
Introduction Postman Collection Tools and Libraries Social Login
Authentication Scopes Identity Model
Search, Paging and Includes Active, Archived, and Deleted Errors Request Limits How to create your FreshBooks app listing
Get Authenticated On The FreshBooks API How To Find The Right Scopes For Your App Getting Started with FreshBooks NodeJS SDK Receive Online Payments with Checkout API Enabling Online Payments On An Invoice
Bearer tokens replaced with JWT tokens
Clients Update Secondary Contacts Credits
Invoices Invoice Profiles Invoice Presentation and Attachments Payments Online Payments Other Income Taxes
Expenses Path 413 Created with Sketch.
Expenses Expense Categories Expense Attachments Bill Vendors (beta) Bills (beta) Bill Payments (beta)
Estimates
Time Entries
Services Projects
Team Members Staff
Reports
Journal Entries
Webhook Callbacks
Gateways Items Systems Tasks

Bill Vendors (beta)

A Vendor will work with your business to provide goods or services with a Bill to be paid at a later date. If you’ve already paid for an item or service in full, this would be an Expense instead. The Vendors API can be used to create, edit or delete Vendors in your FreshBooks account. As you track your Bills (part of Accounts Payable), you can add, manage and delete your Vendors as your business’ relationships with other Vendors grow directly using the Vendor API.

Access Requirements

AccessRequires Authorization
Scopesuser:bill_vendors:read
user:bill_vendors:write

Field Descriptions

underlined fields are required on creation

FieldTypeDescription
account_numberstringaccount number of the vendor
citystringcity of vendor
countrystringcountry of vendor
created_atdatetimeRead-only. time the vendor was created, YYYY-MM-DD HH:MM:SS format
currency_codestringdefault three-letter currency code for vendor
is_1099boolean set true if vendor is a 1099 contractor
languagestringtwo-letter language code, e.g. “en”
notestring 
outstanding_balanceobjectRead-only. subfields: amount and code
– amountstringthe outstanding amount to be paid to the Vendor
– codestringthree-letter currency code
overdue_balanceobjectRead-only. subfields: amount and code
– amountstringoverdue amount to be paid to the Vendor
– codestringthree-letter currency code
phonestringphone number
postal_codestringpostal code
primary_contact_emailstringvendor primary email
primary_contact_first_namestringvendor primary first name
primary_contact_last_namestringvendor primary last name
provincestringprovince
streetstringstreet address
street2stringstreet address 2nd part
tax_defaultsobjectarray of “bill_vendor_tax_defaults” object, see below
updated_atdatetimeRead-only. time of last modification to resource
vendor_namestringvendor name
vendoridintegerunique identifier for vendor
vis_statestringvisibility state, possible values are 0, 1, 2
websitestringvendor website address

Tax Defaults

vendoridintegerUnique identifier for vendor
taxidintegerUnique identifier for vendor tax default
system_taxidintegerTax id in your FreshBooks business, you can get the tax id using the get taxes api
enabledbooleanIf the tax is enabled for the vendor or not.
namestringRead-only. Populated from related system tax
amountstringRead-only. Populated from related system tax
tax_authorityidstringCustom identifier for tax tax authority.
created_atdatetimeRead-only. Time the resource was created, YYYY-MM-DD HH:MM:SS format
updated_atdatetimeRead-only. Time the resource was updated, YYYY-MM-DD HH:MM:SS format
curl Python

Get Vendors

curl -L -X GET 'https://api.freshbooks.com/accounting/account/<accountId>/bill_vendors/bill_vendors' \
-H 'Authorization: Bearer <insert-bearer-token>'
 

#Response:
{
    "response": {
        "result": {
            "bill_vendors": [
                {
                    "account_number": "45454545",
                    "city": "San Francisco",
                    "country": "United States",
                    "created_at": "2021-06-17 12:08:25",
                    "currency_code": "USD",
                    "is_1099": false,
                    "language": "en",
                    "note": null,
                    "outstanding_balance": [],
                    "overdue_balance": [],
                    "phone": "4158859378",
                    "postal_code": null,
                    "primary_contact_email": "someone@ikea.com",
                    "primary_contact_first_name": "Jimmy",
                    "primary_contact_last_name": "McNamara",
                    "province": "California",
                    "street": "332 Carlton Ave.",
                    "street2": null,
                    "tax_defaults": [],
                    "updated_at": "2021-06-17 12:08:25",
                    "vendor_name": "IKEA",
                    "vendorid": 1563,
                    "vis_state": 0,
                    "website": "ikea.com"
                },
                {
                    "account_number": "",
                    "city": null,
                    "country": null,
                    "created_at": "2021-06-16 09:49:46",
                    "currency_code": "USD",
                    "is_1099": false,
                    "language": "en",
                    "note": null,
                    "outstanding_balance": [
                        {
                            "amount": {
                                "amount": "53885.00",
                                "code": "USD"
                            }
                        }
                    ],
                    "overdue_balance": [],
                    "phone": null,
                    "postal_code": null,
                    "primary_contact_email": "someone@freshbooks.com",
                    "primary_contact_first_name": "Rahul",
                    "primary_contact_last_name": "Varma",
                    "province": null,
                    "street": null,
                    "street2": null,
                    "tax_defaults": [
                        {
                            "amount": "6",
                            "created_at": "2021-06-16 09:49:46",
                            "enabled": true,
                            "name": "GST1",
                            "system_taxid": 5307,
                            "tax_authorityid": null,
                            "taxid": 95,
                            "updated_at": "2021-06-16 09:49:46",
                            "vendorid": 1562
                        },
                        {
                            "amount": "7",
                            "created_at": "2021-06-16 09:49:46",
                            "enabled": true,
                            "name": "PST",
                            "system_taxid": 6047,
                            "tax_authorityid": null,
                            "taxid": 96,
                            "updated_at": "2021-06-16 09:49:46",
                            "vendorid": 1562
                        }
                    ],
                    "updated_at": "2021-06-16 09:49:46",
                    "vendor_name": "Bread Supplier",
                    "vendorid": 1562,
                    "vis_state": 0,
                    "website": ""
                },
                {
                    "account_number": "",
                    "city": "",
                    "country": null,
                    "created_at": "2021-01-18 13:28:30",
                    "currency_code": "EUR",
                    "is_1099": false,
                    "language": "en",
                    "note": null,
                    "outstanding_balance": [
                        {
                            "amount": {
                                "amount": "50113.00",
                                "code": "EUR"
                            }
                        }
                    ],
                    "overdue_balance": [
                        {
                            "amount": {
                                "amount": "50113.00",
                                "code": "EUR"
                            }
                        }
                    ],
                    "phone": "+",
                    "postal_code": "",
                    "primary_contact_email": "apiteam@gmail.com",
                    "primary_contact_first_name": "teak",
                    "primary_contact_last_name": "Wood",
                    "province": "",
                    "street": "",
                    "street2": null,
                    "tax_defaults": [],
                    "updated_at": "2021-01-18 13:35:39",
                    "vendor_name": "Teak Provider",
                    "vendorid": 817,
                    "vis_state": 0,
                    "website": null
                }
            ],
            "page": 1,
            "pages": 1,
            "per_page": 15,
            "total": 3
        }
    }
}

Add Vendor

curl -L -X POST 'https://api.freshbooks.com/accounting/account/<accountId>/bill_vendors/bill_vendors' \
-H 'Authorization: Bearer <insert-bearer-token>' \
-H 'Content-Type: application/json' \
--data-raw '{
    "bill_vendor": {
        "vendor_name": "IKEA",
        "primary_contact_first_name": "Jimmy",
        "primary_contact_last_name": "McNamara",
        "primary_contact_email": "someone@ikea.com",
        "primary_contact": null,
        "street": "332 Carlton Ave.",
        "street2": null,
        "city": "San Francisco",
        "province": "California",
        "postal_code": null,
        "country": "United States",
        "account_number": "45454545",
        "phone": "4158859378",
        "website": "ikea.com",
        "currency_code": "USD",
        "language": "en",
        "is_1099": false,
        "tax_defaults": []
    }
}'
 

#Response:
{
    "response": {
        "result": {
            "bill_vendor": {
                "account_number": "45454545",
                "city": "San Francisco",
                "country": "United States",
                "created_at": "2021-06-17 12:08:25",
                "currency_code": "USD",
                "is_1099": false,
                "language": "en",
                "note": null,
                "outstanding_balance": [],
                "overdue_balance": [],
                "phone": "4158859378",
                "postal_code": null,
                "primary_contact_email": "someone@ikea.com",
                "primary_contact_first_name": "Jimmy",
                "primary_contact_last_name": "McNamara",
                "province": "California",
                "street": "332 Carlton Ave.",
                "street2": null,
                "tax_defaults": [],
                "updated_at": "2021-06-17 12:08:25",
                "vendor_name": "IKEA",
                "vendorid": 1563,
                "vis_state": 0,
                "website": "ikea.com"
            }
        }
    }
}

Edit Vendor Details

curl -L -X PUT 'https://api.freshbooks.com/accounting/account/<accountId>/bill_vendors/bill_vendors/<vendorId>' \
-H 'Authorization: Bearer <insert-bearer-token>' \
-H 'Content-Type: application/json' \
--data-raw '{
    "bill_vendor": {
        "vendor_name": "IKEA",
        "primary_contact_first_name": "Jimmy",
        "primary_contact_last_name": "McNamara",
        "primary_contact_email": "someone2@ikea.com",
        "primary_contact": null,
        "street": "332 Carlton Ave.",
        "street2": null,
        "city": "San Francisco",
        "province": "California",
        "postal_code": null,
        "country": "United States",
        "account_number": "45454545",
        "phone": "4158859378",
        "website": "ikea.com",
        "currency_code": "USD",
        "language": "en",
        "is_1099": false,
        "tax_defaults": []
    }
}' 


#Response:
{
    "response": {
        "result": {
            "bill_vendor": {
                "account_number": "45454545",
                "city": "San Francisco",
                "country": "United States",
                "created_at": "2021-06-17 12:08:25",
                "currency_code": "USD",
                "is_1099": false,
                "language": "en",
                "note": null,
                "outstanding_balance": [],
                "overdue_balance": [],
                "phone": "4158859378",
                "postal_code": null,
                "primary_contact_email": "someone2@ikea.com",
                "primary_contact_first_name": "Jimmy",
                "primary_contact_last_name": "McNamara",
                "province": "California",
                "street": "332 Carlton Ave.",
                "street2": null,
                "tax_defaults": [],
                "updated_at": "2021-06-17 12:18:16",
                "vendor_name": "IKEA",
                "vendorid": 1563,
                "vis_state": 0,
                "website": "ikea.com"
            }
        }
    }
}

Delete Vendor

curl -L -X PUT 'https://api.freshbooks.com/accounting/account/<accountId>/bill_vendors/bill_vendors/<vendorId>' \
-H 'Authorization: Bearer <insert-bearer-token>' \
-H 'Content-Type: application/json' \
--data-raw '{
    "bill_vendor": {
        "vis_state": 1
    }
}'
 

#Response:
{
    "response": {
        "result": {
            "bill_vendor": {
                "account_number": "45454545",
                "city": "San Francisco",
                "country": "United States",
                "created_at": "2021-06-17 12:08:25",
                "currency_code": "USD",
                "is_1099": false,
                "language": "en",
                "note": null,
                "outstanding_balance": [],
                "overdue_balance": [],
                "phone": "4158859378",
                "postal_code": null,
                "primary_contact_email": "someone2@ikea.com",
                "primary_contact_first_name": "Jimmy",
                "primary_contact_last_name": "McNamara",
                "province": "California",
                "street": "332 Carlton Ave.",
                "street2": null,
                "tax_defaults": [],
                "updated_at": "2021-06-17 12:31:24",
                "vendor_name": "IKEA",
                "vendorid": 1563,
                "vis_state": 1,
                "website": "ikea.com"
            }
        }
    }
}

Get Vendors

import http.client

conn = http.client.HTTPSConnection("api.freshbooks.com")
payload = ''
headers = {
  'Authorization': 'Bearer <insert-bearer-token>'
}
conn.request("GET", "/accounting/account/<accountId>/bill_vendors/bill_vendors", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
 

 
#Response:
{
    "response": {
        "result": {
            "bill_vendors": [
                {
                    "account_number": "45454545",
                    "city": "San Francisco",
                    "country": "United States",
                    "created_at": "2021-06-17 12:08:25",
                    "currency_code": "USD",
                    "is_1099": false,
                    "language": "en",
                    "note": null,
                    "outstanding_balance": [],
                    "overdue_balance": [],
                    "phone": "4158859378",
                    "postal_code": null,
                    "primary_contact_email": "someone@ikea.com",
                    "primary_contact_first_name": "Jimmy",
                    "primary_contact_last_name": "McNamara",
                    "province": "California",
                    "street": "332 Carlton Ave.",
                    "street2": null,
                    "tax_defaults": [],
                    "updated_at": "2021-06-17 12:08:25",
                    "vendor_name": "IKEA",
                    "vendorid": 1563,
                    "vis_state": 0,
                    "website": "ikea.com"
                },
                {
                    "account_number": "",
                    "city": null,
                    "country": null,
                    "created_at": "2021-06-16 09:49:46",
                    "currency_code": "USD",
                    "is_1099": false,
                    "language": "en",
                    "note": null,
                    "outstanding_balance": [
                        {
                            "amount": {
                                "amount": "53885.00",
                                "code": "USD"
                            }
                        }
                    ],
                    "overdue_balance": [],
                    "phone": null,
                    "postal_code": null,
                    "primary_contact_email": "someone@freshbooks.com",
                    "primary_contact_first_name": "Rahul",
                    "primary_contact_last_name": "Varma",
                    "province": null,
                    "street": null,
                    "street2": null,
                    "tax_defaults": [
                        {
                            "amount": "6",
                            "created_at": "2021-06-16 09:49:46",
                            "enabled": true,
                            "name": "GST1",
                            "system_taxid": 5307,
                            "tax_authorityid": null,
                            "taxid": 95,
                            "updated_at": "2021-06-16 09:49:46",
                            "vendorid": 1562
                        },
                        {
                            "amount": "7",
                            "created_at": "2021-06-16 09:49:46",
                            "enabled": true,
                            "name": "PST",
                            "system_taxid": 6047,
                            "tax_authorityid": null,
                            "taxid": 96,
                            "updated_at": "2021-06-16 09:49:46",
                            "vendorid": 1562
                        }
                    ],
                    "updated_at": "2021-06-16 09:49:46",
                    "vendor_name": "Bread Supplier",
                    "vendorid": 1562,
                    "vis_state": 0,
                    "website": ""
                },
                {
                    "account_number": "",
                    "city": "",
                    "country": null,
                    "created_at": "2021-01-18 13:28:30",
                    "currency_code": "EUR",
                    "is_1099": false,
                    "language": "en",
                    "note": null,
                    "outstanding_balance": [
                        {
                            "amount": {
                                "amount": "50113.00",
                                "code": "EUR"
                            }
                        }
                    ],
                    "overdue_balance": [
                        {
                            "amount": {
                                "amount": "50113.00",
                                "code": "EUR"
                            }
                        }
                    ],
                    "phone": "+",
                    "postal_code": "",
                    "primary_contact_email": "apiteam@gmail.com",
                    "primary_contact_first_name": "teak",
                    "primary_contact_last_name": "Wood",
                    "province": "",
                    "street": "",
                    "street2": null,
                    "tax_defaults": [],
                    "updated_at": "2021-01-18 13:35:39",
                    "vendor_name": "Teak Provider",
                    "vendorid": 817,
                    "vis_state": 0,
                    "website": null
                }
            ],
            "page": 1,
            "pages": 1,
            "per_page": 15,
            "total": 3
        }
    }
}

Add Vendor

import http.client
import json

conn = http.client.HTTPSConnection("api.freshbooks.com")
payload = json.dumps({
  "bill_vendor": {
    "vendor_name": "IKEA2",
    "primary_contact_first_name": "Jimmy",
    "primary_contact_last_name": "McNamara",
    "primary_contact_email": "jmcnamarae@ikea.com",
    "primary_contact": None,
    "street": "332 Carlton Ave.",
    "street2": None,
    "city": "San Francisco",
    "province": "California",
    "postal_code": None,
    "country": "United States",
    "account_number": "45454545",
    "phone": "4158859378",
    "website": "ikea.com",
    "currency_code": "USD",
    "language": "en",
    "is_1099": False,
    "tax_defaults": []
  }
})
headers = {
  'Authorization': 'Bearer <insert-bearer-token>',
  'Content-Type': 'application/json'
}
conn.request("POST", "/accounting/account/<accountId>/bill_vendors/bill_vendors", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
 

#Response:
{
    "response": {
        "result": {
            "bill_vendor": {
                "account_number": "45454545",
                "city": "San Francisco",
                "country": "United States",
                "created_at": "2021-06-17 12:08:25",
                "currency_code": "USD",
                "is_1099": false,
                "language": "en",
                "note": null,
                "outstanding_balance": [],
                "overdue_balance": [],
                "phone": "4158859378",
                "postal_code": null,
                "primary_contact_email": "someone@ikea.com",
                "primary_contact_first_name": "Jimmy",
                "primary_contact_last_name": "McNamara",
                "province": "California",
                "street": "332 Carlton Ave.",
                "street2": null,
                "tax_defaults": [],
                "updated_at": "2021-06-17 12:08:25",
                "vendor_name": "IKEA",
                "vendorid": 1563,
                "vis_state": 0,
                "website": "ikea.com"
            }
        }
    }
}

Edit Vendor Details

import http.client
import json

conn = http.client.HTTPSConnection("api.freshbooks.com")
payload = json.dumps({
    "bill_vendor": {
        "vendor_name": "IKEA",
        "primary_contact_first_name": "Jimmy",
        "primary_contact_last_name": "McNamara",
        "primary_contact_email": "someone2@ikea.com",
        "primary_contact": None,
        "street": "332 Carlton Ave.",
        "street2": None,
        "city": "San Francisco",
        "province": "California",
        "postal_code": None,
        "country": "United States",
        "account_number": "45454545",
        "phone": "4158859378",
        "website": "ikea.com",
        "currency_code": "USD",
        "language": "en",
        "is_1099": False,
        "tax_defaults": []
    }
})
headers = {
  'Authorization': 'Bearer <insert-bearer-token>',
  'Content-Type': 'application/json'
}
conn.request("PUT", "/accounting/account/<accountId>/bill_vendors/bill_vendors/<vendorId>", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

#Response:
{
    "response": {
        "result": {
            "bill_vendor": {
                "account_number": "45454545",
                "city": "San Francisco",
                "country": "United States",
                "created_at": "2021-06-17 12:08:25",
                "currency_code": "USD",
                "is_1099": false,
                "language": "en",
                "note": null,
                "outstanding_balance": [],
                "overdue_balance": [],
                "phone": "4158859378",
                "postal_code": null,
                "primary_contact_email": "someone2@ikea.com",
                "primary_contact_first_name": "Jimmy",
                "primary_contact_last_name": "McNamara",
                "province": "California",
                "street": "332 Carlton Ave.",
                "street2": null,
                "tax_defaults": [],
                "updated_at": "2021-06-17 12:18:16",
                "vendor_name": "IKEA",
                "vendorid": 1563,
                "vis_state": 0,
                "website": "ikea.com"
            }
        }
    }
}