Skip to content
× FreshBooks App Logo
FreshBooks
Official App
Free - Google Play
Get it
You're currently on our US site. Select your regional site here:

The Identity Model

Access Requirements

For access to the /me endpoint.

AccessRequires Authorization
Scopesuser:profile:read

Businesses & Account Ids

Users may interact with more than one business in the new FreshBooks. Users are uniquely identified by their email across all of the new FreshBooks, 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!

That’s why calls to our API must state what Business or Account they want to work on. You can find ids for the Businesses and Accounts a user can interact with by making a call to the Identity Info endpoint. An example of its response is in the code pane on the right. The key we care about most is business_memberships.

All 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 those ids for the id in the business_membership object.

For example, in the Identity Info (/me) response:

"business_memberships": [
{
    "id": 111,
    "role": "owner",
    "business": {
        "id": 240340,
        "business_uuid": "046cc001-0002-e93e-1db1-1186b2983879",
        "name": "Awesome Business Inc.",
        "account_id": "ABC123",
        "date_format": "dd/mm/yyyy",
        "active": true
    }
}

You can see that the user is an owner on this business which has a business_id of 230340 and an account_id of ABC123.

Acting on a Specific Account

Calls to the /accounting endpoints take this form:

  1. /accounting/account/{accountId}/invoices/invoices

Calls to most non-accounting resources, such as the /timetracking/ and /projects/ endpoints usually require a businessId, for example:

  1. /timetracking/business/{businessId}/time_entries

All 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 Role on a Business, but they do not have an Account. 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.

Roles

Over 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.

API RoleFreshBooks UI Role NameDetails
owner or adminOwnerThe 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.
business_partnerAdminAn additional Identity with full access to the FreshBooks business.
business_managerManagerIdentity without access to full financial reports and information.
business_employeeEmployeeIdentity with access limited to their own expenses, projects, and time tracking.
business_accountantAccountantIdentity with access limited to accounting items such as report and expense categorization
contractorContractorAn Identity with their own Business that can track time and invoice this business.
clientClientIdentity that has received an invoice from this Business and saved it to their own.

Example Identity Info Call

Request:

curl -X GET
-H 'Authorization: Bearer <insert your bearer here>'
-H 'Api-Version: alpha'
-H 'Content-Type: application/json'
https://api.freshbooks.com/auth/api/v1/users/me

Response:

{
  "response": {
    "id": 712052,
    "profile": {
      "setup_complete": true,
      "first_name": "Bruce",
      "last_name": "Wayne",
      "phone_number": null,
      "address": null,
      "professions": [
        {
          "id": 17748,
          "title": "Accounting",
          "company": "BillSpring",
          "designation": null
        }
      ]
    },
    "first_name": "Bruce",
    "last_name": "Wayne",
    "email": "b@example.com",
    "confirmed_at": "2016-01-26T16:01:23Z",
    "created_at": "2016-01-26T16:00:41Z",
    "unconfirmed_email": null,
    "setup_complete": true,
    "phone_numbers": [
      {
        "title": "",
        "phone_number": null
      }
    ],
    "addresses": [
      null
    ],
    "profession": {
      "id": 17748,
      "title": "Accounting",
      "company": "BillSpring",
      "designation": null
    },
    "links": {
      "me": "/service/auth/api/v1/users?id=712052",
      "roles": "/service/auth/api/v1/users/role/712052"
    },
    "permissions": {
      "zDmNq": {
        "notifications.access": true,
        "beta.mobile.expenses": true,
        "client.event.search": true,
        "time_tracking.access": true,
        "invoice_discounts.access": true,
        "clienttypeahead.access": true,
        "invoice_line_item_typeahead.access": true,
        "client.limit": 2,
        "staff.limit": -1
      },
      "e6Wmk": {
        "notifications.access": true,
        "beta.mobile.expenses": true,
        "client.event.search": true,
        "time_tracking.access": true,
        "invoice_discounts.access": true,
        "clienttypeahead.access": true,
        "client.limit": -1,
        "staff.limit": -1
      }
    },
    "groups": [
      {
        "id": 90610,
        "group_id": 23738,
        "role": "owner",
        "identity_id": 712052,
        "first_name": "Bruce",
        "last_name": "Wayne",
        "email": "b@example.com",
        "company": "BillSpring",
        "business_id": 77128,
        "active": true
      },
      {
        "id": 168372,
        "group_id": 96277,
        "role": "owner",
        "identity_id": 712052,
        "first_name": "Bruce",
        "last_name": "Wayne",
        "email": "b@example.com",
        "company": "BillSpring",
        "business_id": 77128,
        "active": true
      },
      {
        "id": 1570108,
        "group_id": 568705,
        "role": "manager",
        "identity_id": 712052,
        "first_name": "bruce",
        "last_name": "Wayne",
        "email": "b@example.com",
        "company": "BillSpring",
        "business_id": 311394,
        "active": true
      }
    ],
    "subscription_statuses": {
      "zDmNq": "active",
      "e6Wmk": "trial_expired"
    },
    "integrations": {},
    "business_memberships": [
      {
        "id": 168372,
        "role": "owner",
        "business": {
          "id": 77128,
          "name": "BillSpring",
          "account_id": "zDmNq",
          "address": {
            "id": 74595,
            "street": "123",
            "city": "Toronto",
            "province": "Ontario",
            "country": "Canada",
            "postal_code": "A1B2C3"
          },
          "phone_number": null,
          "business_clients": [
            {
              "id": 22347,
              "business_id": 77128,
              "account_id": "Xr82w",
              "userid": 74353,
              "client_business": {
                "business_id": 77128
              },
              "account_business": {
                "account_business_id": 363103,
                "account_id": "Xr82w"
              }
            }
          ]
        }
      },
      {
        "id": 1570108,
        "role": "manager",
        "business": {
          "id": 311394,
          "name": "another_bruce",
          "account_id": "e6Wmk",
          "address": {
            "id": 114984,
            "street": "123 Fake St.",
            "city": "Toronto",
            "province": "Ontario",
            "country": "Canada",
            "postal_code": "A1B2D3"
          },
          "phone_number": null,
          "business_clients": []
        }
      }
    ],
    "roles": [
      {
        "id": 682608,
        "role": "admin",
        "systemid": 1953394,
        "userid": 1,
        "created_at": "2016-01-26T16:00:44Z",
        "links": {
          "destroy": "/service/auth/api/v1/users/role/682608"
        },
        "accountid": "zDmNq"
      },
      {
        "id": 938330,
        "role": "business_partner",
        "systemid": 2589025,
        "userid": 2307391,
        "created_at": "2016-09-02T15:41:59Z",
        "links": {
          "destroy": "/service/auth/api/v1/users/role/938330"
        },
        "accountid": "e6Wmk"
      },
      {
        "id": 994207,
        "role": "client",
        "systemid": 2699898,
        "userid": 74353,
        "created_at": "2016-09-30T15:42:56Z",
        "links": {
          "destroy": "/service/auth/api/v1/users/role/994207"
        },
        "accountid": "Xr82w"
      }
    ]
  }
}

Example Identity Info Call

Request: GET

https://api.freshbooks.com/auth/api/v1/users/me


url = "https://api.freshbooks.com/auth/api/v1/users/me"
headers = {'Authorization': 'Bearer <bearer token>', 'Api-Version': 'alpha', 'Content-Type': 'application/json'}
res = requests.get(url, data=None, headers=headers)
jsonData = res.json()

Response:


{
  "response": {
    "id": 712052,
    "profile": {
      "setup_complete": true,
      "first_name": "Bruce",
      "last_name": "Wayne",
      "phone_number": null,
      "address": null,
      "professions": [
        {
        "id": 17748,
          "title": "Accounting",
          "company": "BillSpring",
          "designation": null
        }
      ]
    },
    "first_name": "Bruce",
    "last_name": "Wayne",
    "email": "b@example.com",
    "confirmed_at": "2016-01-26T16:01:23Z",
    "created_at": "2016-01-26T16:00:41Z",
    "unconfirmed_email": null,
    "setup_complete": true,
    "phone_numbers": [
    {
        "title": "",
        "phone_number": null
      }
    ],
    "addresses": [
      null
    ],
    "profession": {
      "id": 17748,
      "title": "Accounting",
      "company": "BillSpring",
      "designation": null
    },
    "links": {
      "me": "/service/auth/api/v1/users?id=712052",
      "roles": "/service/auth/api/v1/users/role/712052"
    },
    "permissions": {
      "zDmNq": {
        "notifications.access": true,
        "beta.mobile.expenses": true,
        "client.event.search": true,
        "time_tracking.access": true,
        "invoice_discounts.access": true,
        "clienttypeahead.access": true,
        "invoice_line_item_typeahead.access": true,
        "client.limit": 2,
        "staff.limit": -1
      },
      "e6Wmk": {
        "notifications.access": true,
        "beta.mobile.expenses": true,
        "client.event.search": true,
        "time_tracking.access": true,
        "invoice_discounts.access": true,
        "clienttypeahead.access": true,
        "client.limit": -1,
        "staff.limit": -1
      }
    },
    "groups": [
      {
        "id": 90610,
        "group_id": 23738,
        "role": "owner",
        "identity_id": 712052,
        "first_name": "Bruce",
        "last_name": "Wayne",
        "email": "b@example.com",
        "company": "BillSpring",
        "business_id": 77128,
        "active": true
      },
      {
        "id": 168372,
        "group_id": 96277,
        "role": "owner",
        "identity_id": 712052,
        "first_name": "Bruce",
        "last_name": "Wayne",
        "email": "b@example.com",
        "company": "BillSpring",
        "business_id": 77128,
        "active": true
      },
      {
        "id": 1570108,
        "group_id": 568705,
        "role": "manager",
        "identity_id": 712052,
        "first_name": "bruce",
        "last_name": "Wayne",
        "email": "b@example.com",
        "company": "BillSpring",
        "business_id": 311394,
        "active": true
      }
    ],
    "subscription_statuses": {
      "zDmNq": "active",
      "e6Wmk": "trial_expired"
    },
    "integrations": {},
    "business_memberships": [
      {
        "id": 168372,
        "role": "owner",
        "business": {
          "id": 77128,
          "name": "BillSpring",
          "account_id": "zDmNq",
          "address": {
            "id": 74595,
            "street": "123",
            "city": "Toronto",
            "province": "Ontario",
            "country": "Canada",
            "postal_code": "A1B2C3"
          },
          "phone_number": null,
          "business_clients": [
            {
              "id": 22347,
              "business_id": 77128,
              "account_id": "Xr82w",
              "userid": 74353,
              "client_business": {
                "business_id": 77128
              },
                "account_business": {
                "account_business_id": 363103,
                "account_id": "Xr82w"
              }
            }
          ]
        }
      },
    {
        "id": 1570108,
        "role": "manager",
        "business": {
          "id": 311394,
          "name": "another_bruce",
          "account_id": "e6Wmk",
          "address": {
            "id": 114984,
            "street": "123 Fake St.",
            "city": "Toronto",
            "province": "Ontario",
            "country": "Canada",
            "postal_code": "A1B2D3"
          },
          "phone_number": null,
          "business_clients": []
        }
      }
    ],
    "roles": [
      {
        "id": 682608,
        "role": "admin",
        "systemid": 1953394,
        "userid": 1,
        "created_at": "2016-01-26T16:00:44Z",
        "links": {
          "destroy": "/service/auth/api/v1/users/role/682608"
        },
        "accountid": "zDmNq"
      },
      {
        "id": 938330,
        "role": "business_partner",
        "systemid": 2589025,
        "userid": 2307391,
        "created_at": "2016-09-02T15:41:59Z",
        "links": {
          "destroy": "/service/auth/api/v1/users/role/938330"
        },
        "accountid": "e6Wmk"
      },
      {
        "id": 994207,
        "role": "client",
        "systemid": 2699898,
        "userid": 74353,
        "created_at": "2016-09-30T15:42:56Z",
        "links": {
          "destroy": "/service/auth/api/v1/users/role/994207"
        },
        "accountid": "Xr82w"
      }
    ]
  }
}