{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"52737e2b-88b3-1754-66ae-f212fc19faae","name":"FreshBooks API","description":"# Quick Start\n\nThe column on the right hand side has a curl call that demonstrates the required Headers and general format of requests to the FreshBooks API.\n\nRequests are authenticated using OAuth2 Bearer tokens which you receive in exchange for a code we issue after a logged-in user performs an authorization grant request. You can create an OAuth application and get a `client_id` and `secret` at the [developer page](https://my.freshbooks.com/#/developer).\n\nThe FreshBooks API is an interface for accessing your FreshBooks data using JSON. The API makes it easy to create web and desktop applications that integrate with your account. Possible uses for it include automatically creating and sending invoices when users sign up on your website, pulling lists of client information, copying data to 3rd party services, and more...\n\nCheck out our Scenarios and API Reference sections to see what to expect, and when you're ready, sign up for a FreshBooks account if you don't have one, and proceed to the [developer page](https://my.freshbooks.com/#/developer) to create an application and start development.\n\nOh, and we're not trying to be secretive about the URL of the developer page, it's: [https://www.my.freshbooks.com/#/developer](https://www.my.freshbooks.com/#/developer)\n\n## Creating your application on FreshBooks\n\nCreate an account by visiting our [sign up page](https://www.freshbooks.com/pages/developer-signup?ref=13287&utm_source=Partners&utm_medium=DevCommunity&utm_campaign=Dev%20Signup%20-%20API%20docs&utm_term=Dev%20Signup%20-%20API%20docs). If you already have a FreshBooks account, log in by visiting our [log in page.](https://www.freshbooks.com/developers) You can reach out to our support team to have your account put on our partner plan.\n\n1. Now visit the [developer page](https://my.freshbooks.com/#/developer) and create a [new app](https://my.freshbooks.com/#/developer/new).\n2. Make sure to include the name of the application and redirect URI in the application form.  \n    The name of the application has to be unique as it will be used to display on the FreshBooks app store and on a FreshBooks user’s [integrations](https://my.freshbooks.com/#/integrations) page once they have connected with your application. The redirect URI should be an endpoint in your application that will receive the authorization code and will use it to retrieve the bearer token and refresh token. These will be necessary to make authenticated calls to the FreshBooks API. To get more information on our authentication process visit our [Oauth documentation](https://www.freshbooks.com/api/authentication).\n3. Save your application.\n    \n\n## Required Headers\n\nThere are two required headers:\n\n1. `Content-Type: application/json`\n2. `Authorization: Bearer`\n    \n\n# Getting Help\n\nIf there’s no one around to help, we’ve got your back. Shoot us an email at [api@freshbooks.com](mailto:api@freshbooks.com) and tell us what you’re aiming to accomplish, what you’ve done so far, and what went wrong. Maybe we can find the missing piece of the puzzle together.\n\n# Identity Model\n\nFreshBooks users are uniquely identified by their email across our entire product. One user may act on several Businesses in different ways, so if **leafy@example.com** is an Administrator of one account and gets added as a Client on another, they will have some access to both. They could then open a second business of their own, or be added as an employee of another person’s business—we live complicated lives! Our Identity model is how we keep track of it.\n\n## Account IDs & Business IDs\n\nYou can find ids for the Businesses and Accounts a user can interact with by making a call to the Identity Info endpoint (or `/me`). An example of its response is in the code pane on the right. The key we care about most is `business_memberships`.\n\nAll of the business objects listed in the `business_memberships` will have an `accountId` as well as a role on that business (see Roles below). Those business objects also each have an `id` which is the `business_id`. Be careful not to mistake the business’s id for the id of the `business_membership` object itself.\n\nFor example, in the Identity Info (`/me`) response:\n\n``` json\n\"business_memberships\": [\n{\n    \"id\": 111,\n    \"role\": \"owner\",\n    \"business\": {\n        \"id\": 240340,\n        \"business_uuid\": \"046cc001-0002-e93e-1db1-1186b2983879\",\n        \"name\": \"Awesome Business Inc.\",\n        \"account_id\": \"ABC123\",\n        \"date_format\": \"dd/mm/yyyy\",\n        \"active\": true\n    }\n}\n\n```\n\nYou can see that the user is an `owner` on this business which has a `business_id` of `230340` and an `account_id` of `ABC123`.\n\n## Acting on a Specific Account\n\nFor historical reasons, FreshBooks has shifted from an account concept to a business concept, but many resources still make use of accountIds.\n\nCalls to the `/accounting` endpoints take this form:\n\n- `/accounting/account/{accountId}/invoices/invoices`\n    \n\nCalls to most non-accounting resources, such as the `/timetracking/` and `/projects/` endpoints usually require a `business_id`, for example:\n\n- `/timetracking/business/{business_id}/time_entries`\n    \n\n_All FreshBooks users_ have an **Identity** and a **Business** resource and thus a **business_id**. _Most users_ have accounts, which represent their own FreshBooks account, but not all. For instance, when a Client receives an invoice, views it, and saves it, they will exist as an Identity in our system with a client Role on a **Business**, but they do not have an **Account** of their own. If you know your integration will never need to deal with someone who is just a Client and doesn’t have their own Account, you can ignore this. If you aren’t sure of that, you must gracefully handle the case where you cannot find an account for a user.\n\n## Roles\n\nOver time the logical role names that FreshBooks utilizes have diverged slightly from the names they are given in the FreshBooks application. Below are the relationships.\n\n| API Role | FreshBooks UI Role Name | Details |\n| --- | --- | --- |\n| owner **or** admin | Owner | The primary Identity of a FreshBooks business. This shows as `owner` in the `business_memberships` of the identity response, and `admin` in the older, deprecated `roles` array of the response. |\n| business_partner | Admin | An additional Identity with full access to the FreshBooks business. |\n| business_manager | Manager | Identity without access to full financial reports and information. |\n| business_employee | Employee | Identity with access limited to their own expenses, projects, and time tracking. |\n| business_accountant | Accountant | Identity with access limited to accounting items such as report and expense categorization |\n| contractor | Contractor | An Identity with their own Business that can track time and invoice this business. |\n| client | Client | Identity that has received an invoice from this Business and saved it to their own. |\n\n# CONCEPTS AND IDEAS\n\n## Adding a Logo to your Invoice\n\nIn order for you to add a logo to your FreshBooks invoice, you will need to do it in two steps.\n\n1. Upload your logo to your FreshBooks account using the Uploader endpoint\n2. Apply your logo to your invoice\n    \n\n## Uploading your Logo\n\nUsing the Uploader endpoint, add your .png or .jpg file. Your response will contain a `jwt` value. Take that value and add it to your GET call for your new invoice.\n\nYou can now use the POST Single Invoice (or Update Invoice) endpoint to apply your logo to an invoice. You will need to add your `jwt` token under presentation at `img_src_logo`.\n\n**Note: The presentation payload also allows you to set colours based on hex code, change the style of your invoice and a few other customizable options.**\n\n## Adding a Receipt to your Expense\n\nThis process is similar to adding a logo to an invoice. You will first need to upload the expense image via the uploader endpoint (See the Postman call for the Uploader). You will then receive back a response with the `jwt` key and it's associated value.\n\nYou will use then add this value in your POST body to add this newly uploaded receipt to an expense. For an example, check out the Expenses folder below.\n\n## Adding a Payment Gateway to your Invoice\n\nTo add a payment gateway to your invoice you will first need to make sure that you have gone through the \"Know Your Client\" process in FreshBooks. This will ensure that you comply to the Terms of Service with either/both of our payment processors, Stripe and FreshBooks Payments. This process will require you to sign up for an account, fill in your business and banking details, tell them what type of business you're managing and how often you would like to have funds deposited into your bank account.\n\nOnce you have gone through the KYC process, you can then toggle online payments on an invoice by making a POST call to the payment_options endpoint for the gateway of your choice. For an example of this, look under invoices and choose the POST call for \"Enable Payment Options On Invoice\".\n\n## Getting a Shareable Link to your Invoice\n\nTo create a shareable link for your invoice, you need to add an `share_link?share_method=share_link` parameter to the end of your GET call for the invoice you are looking to share. You will need to make sure the invoice has already been marked as sent. If you want to mark an invoice as sent you can simply follow the steps under invoices (Hint: adding `\"status\"` as `2` to the body of your PUT call should do the trick.)\n\n## Getting all the Includes Parameters\n\nOur Includes parameters allow for additional payloads to be added to your existing call, but are hidden unless explicitly called for.\n\nAll the Includes parameters associated with your calls can be found in one of the LIST examples posted below. For example, if you want to see the associated Includes parameters for an invoice, simply click on the `List Invoices`. You will see a list of available Includes a description related to each of them.\n\n# Error Codes\n\n| **Number** | **Error Code** | **Description** |\n| --- | --- | --- |\n| 409 | Conflict | The resource being modified is being modified by another request. |\n| 500 | FreshAlchemyUnexpected | The ORM encountered an unexpected error. |\n| 1001 | RequiredField | A required field is missing |\n| 1003 | AccessDenied | You do not have access to perform the action requested. |\n| 1004 | InvalidValue | A Value passed was not of the right type or range. |\n| 1005 | ParseError | The server was unable to parse your request, possibly due to a syntactical error in the request format. |\n| 1006 | MappingError |  |\n| 1039 | ValuesBackwardsError |  |\n| 1042 | InactiveAccountError | The account referred to in the request is inactive. |\n| 1007 | DateRangeBackwardsError | A supplied date range must have the earlier date first. |\n| 1008 | DateRangeRequiredError | A field in the request that requires a date range was not supplied one. |\n| 1009 | DuplicateGroupByClause | The request caused an attempt to group by a column that is already used for a group by in a query. |\n| 1010 | UnknownGroupByClause | The request caused an attempt to group by an unknown column in a query. |\n| 1011 | DeletedResource | The resource referred to in the request is deleted. |\n| 1012 | UnknownResource | The resource referred to in the request cannot be found. |\n| 1013 | InvalidPerPage | The 'per_page' argument in the request was not a positive integer. |\n| 1014 | InvalidPage | The 'page' argument in the request was not a positive integer. |\n| 1015 | MappingErrorNumber |  |\n| 1016 | MappingErrorDateTime |  |\n| 1033 | MappingErrorDate |  |\n| 1031 | MappingErrorBoolean |  |\n| 1017 | MaxLengthExceeded | The request, or a line in the request, was too long. |\n| 1018 | InvalidPercentValue | Percent values should be strings formatted as decimals. |\n| 1019 | ItemDuplicateTax | A tax being added to an item seems to already exist. |\n| 1020 | FileUploadFailed |  |\n| 1021 | FileDownloadFailed |  |\n| 1022 | FileDeleteFailed |  |\n| 1023 | FilterErrorDate |  |\n| 1024 | FilterErrorNumber |  |\n| 1032 | FilterErrorBoolean |  |\n| 1034 | FilterErrorList |  |\n| 1025 | InvalidNegativeValue | A value in the request that was negative should not be. |\n| 1026 | DuplicateTax | The tax in the request already exists. |\n| 1027 | InvalidCharacter |  |\n| 1028 | InvalidLessThanOneValue |  |\n| 1029 | InvalidDuplicateValue |  |\n| 1030 | InvalidRangeValue |  |\n| 1035 | InvalidMappingType |  |\n| 1036 | UnicodeOutOfRange |  |\n| 1037 | FilterErrorScalar |  |\n| 1038 | WriteAccessDenied |  |\n| 1040 | InvalidTotal |  |\n| 1100 | SystemVisitException |  |\n| 1101 | SystemAlreadyVisited |  |\n| 1102 | MaximumContractorChainLengthReached |  |\n| 1103 | LateReminderPositionNotSupported |  |\n| 1104 | OldVisStateAttributeCouldNotBeSet |  |\n| 1105 | CannotUpdateIpAddress |  |\n| 1106 | CannotUpdateLandingUrl |  |\n| 1107 | CannotUpdateReferringUrl |  |\n| 1108 | CannotUpdateReferralid |  |","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":true,"owner":"3322108","collectionId":"52737e2b-88b3-1754-66ae-f212fc19faae","publishedId":"S1ERwwza","public":true,"publicUrl":"https://documenter-api.postman.tech/view/3322108/S1ERwwza","privateUrl":"https://go.postman.co/documentation/3322108-52737e2b-88b3-1754-66ae-f212fc19faae","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"0075DD"},"documentationLayout":"classic-double-column","customisation":null,"version":"8.10.1","publishDate":"2023-03-21T21:27:23.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{},"logos":{}},"statusCode":200},"environments":[{"name":"Sandbox Env Public","id":"1cb6e03d-7c1e-40ea-b260-1e4d94bce26c","owner":"12158787","values":[{"key":"token","value":"","enabled":true},{"key":"categoryId","value":2003192,"enabled":true},{"key":"estimateId","value":2652,"enabled":true},{"key":"customerId","value":272435,"enabled":true},{"key":"invoiceId","value":574343,"enabled":true},{"key":"accountId","value":"G2MB3M","enabled":true},{"key":"businessId","value":"1966214","enabled":true},{"key":"projectId","value":"2976412","enabled":true},{"key":"clientId","value":272435,"enabled":true},{"key":"timeEntryId","value":"49229958","enabled":true},{"key":"taxId","value":"3264","enabled":true},{"key":"itemId","value":116098,"enabled":true},{"key":"incomeId","value":"1872","enabled":true},{"key":"invoiceProfileId","value":2602,"enabled":true},{"key":"paymentId","value":"7654","enabled":true},{"key":"staffId","value":"1","enabled":true},{"key":"imgSrc","value":"/service/api/uploads/images/eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhY2NvdW50Ijo0MjM2NDEwLCJvcmlnaW5hbF9maWxlbmFtZSI6ImNyYXBwcy5wbmciLCJidWNrZXQiOiJ1cGxvYWRzIiwiZmlsZW5hbWUiOiJ1cGxvYWQtOWM4NGZjMjIxZmY2OGYxZDhmYzM3ZDhhMGU2NzdmY2M3YmQ3MWM3MyIsImxlbmd0aCI6MjIzNTA2LCJrZXkiOiInZG9jcy0nLTQyMzY0MTAvdXBsb2FkLTljODRmYzIyMWZmNjhmMWQ4ZmMzN2Q4YTBlNjc3ZmNjN2JkNzFjNzMifQ.JKJhOAD4xudhv8uPpyVw6yFhvJC5ypYzYGRWvq0UTDA","enabled":true},{"key":"themeColor","value":"#4f697a","enabled":true},{"key":"uploadImg","value":"","enabled":true},{"key":"taskId","value":"","enabled":true},{"key":"verifier","value":"scADVVi5QuKuj5qTjVkbJNYQe7V7USpGd","enabled":true},{"key":"callbackId","value":"2001","enabled":true},{"key":"expenseId","value":4945110,"enabled":true},{"key":"identityId","value":37256,"enabled":true},{"key":"serviceId","value":"3595152","enabled":true},{"key":"parentCategoryId","value":"2003142","enabled":true},{"key":"gatewayId","value":"b5d4f07757ff444db095d4854b8f3bc6","enabled":true},{"key":"retainerId","value":"2248","enabled":true},{"key":"business_uuid","value":"046d9001-0002-671e-7776-190932b83856","enabled":true},{"key":"billId","value":"","enabled":true},{"key":"billPaymentId","value":"","enabled":true}],"published":true}],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/768118b36f06c94b0306958b980558e6915839447e859fe16906e29d683976f0","favicon":""},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"},{"label":"Sandbox Env Public","value":"12158787-1cb6e03d-7c1e-40ea-b260-1e4d94bce26c"}],"canonicalUrl":"https://documenter.gw.postman.com/view/metadata/S1ERwwza"}