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

Access	Requires Authorization
Scopes	`user:bill_vendors:read` `user:bill_vendors:write`

Field Descriptions

underlined fields are required on creation

Field	Type	Description
account_number	string	account number of the vendor
city	string	city of vendor
country	string	country of vendor
created_at	datetime	Read-only. time the vendor was created, YYYY-MM-DD HH:MM:SS format
currency_code	string	default three-letter currency code for vendor
is_1099	boolean	set true if vendor is a 1099 contractor
language	string	two-letter language code, e.g. "en"
note	string
outstanding_balance	object	Read-only. subfields: amount and code
- amount	string	the outstanding amount to be paid to the Vendor
- code	string	three-letter currency code
overdue_balance	object	Read-only. subfields: amount and code
- amount	string	overdue amount to be paid to the Vendor
- code	string	three-letter currency code
phone	string	phone number
postal_code	string	postal code
primary_contact_email	string	vendor primary email
primary_contact_first_name	string	vendor primary first name
primary_contact_last_name	string	vendor primary last name
province	string	province
street	string	street address
street2	string	street address 2nd part
tax_defaults	object	array of "bill_vendor_tax_defaults" object, see below
updated_at	datetime	Read-only. time of last modification to resource
vendor_name	string	vendor name
vendorid	integer	unique identifier for vendor
vis_state	string	visibility state, possible values are 0, 1, 2
website	string	vendor website address

Tax Defaults

vendorid	integer	Unique identifier for vendor
taxid	integer	Unique identifier for vendor tax default
system_taxid	integer	Tax id in your FreshBooks business, you can get the tax id using the get taxes api
enabled	boolean	If the tax is enabled for the vendor or not.
name	string	Read-only. Populated from related system tax
amount	string	Read-only. Populated from related system tax
tax_authorityid	string	Custom identifier for tax tax authority.
created_at	datetime	Read-only. Time the resource was created, YYYY-MM-DD HH:MM:SS format
updated_at	datetime	Read-only. Time the resource was updated, YYYY-MM-DD HH:MM:SS format

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"
            }
        }
    }
}