The Identity Model

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

Businesses & Account Ids

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

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 the business’s id for the id of the business_membership object itself.

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.

Access Requirements

For access to the /me endpoint.

Access	Requires Authorization
Scopes	`user:profile:read`

Acting on a Specific Account

For historical reasons, FreshBooks has shifted from an account concept to a business concept, but many resources still make use of accountIds.

Calls to /accounting endpoints require the accountId and take this form:

/accounting/account/{accountId}/invoices/invoices

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

/timetracking/business/{businessId}/time_entries

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.

Roles

Over time the logical role names that FreshBooks’ API utilizes have diverged slightly from the names they are given in the FreshBooks application. Below are the relationships.

API Role	FreshBooks UI Role Name	Details
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.
business_partner	Admin	An additional Identity with full access to the FreshBooks business.
business_manager	Manager	Identity without access to full financial reports and information.
business_employee	Employee	Identity with access limited to their own expenses, projects, and time tracking.
business_accountant	Accountant	Identity with access limited to accounting items such as report and expense categorization
contractor	Contractor	An Identity with their own Business that can track time and invoice this business.
client	Client	Identity that has received an invoice from this Business and saved it to their own.

Field Descriptions

The Identity endpoint is the source of truth for information about that user and the connections they have. It is comprised of many objects, and its contents may change in the future.

Identity Endpoint Fields
field	type	description
id	int	unique identity id
profile	object	user profile information
first_name	string	first name
last_name	string	last name
email	string	the email identity
confirmed_at	datetime	email confirmation time in YYYY-MM-DDTHH:MM:SSZ format
created_at	datetime	identity creation time in YYYY-MM-DDTHH:MM:SSZ format
unconfirmed_email	string	deprecated
setup_complete	boolean	whether identity has been populated with necessary data
phone_numbers	array	list of named phone numbers
addresses	array	list of addresses
profession	object	information about the user’s profession
links	object	list of related links to this resource
permissions	object	list of named permissions for each account
groups	object	see group table
subscription_statuses	object	descriptions of account statuses
integrations	object	list of integrations
business_memberships	object	contains role id and business information

Businesses are a key object in the Identity Model. Every Identity is an Owner of a Business, and a Business may or may not have an Accounting System attached.

Business Fields
field	type	description
id	int	unique business id
name	string	name of business
account_id	string	unique string identity of accounting system if applicable
address	object	object containing business address info
phone_number	array	list of named phone numbers
business_clients	array	list of business client info

Group Memberships associate Identities with other objects, like Businesses or Projects. Identities have roles in Groups, but these are just named strings, not Role objects like the one outlined below. Identities and Group Memberships are the best way in our system to express relationships between people and the businesses they work with.

Group Fields
field	type	description
id	int	unique id of group membership
group_id	int	unique id for group
role	string	named role identity holds in group
identity_id	int	unique id of identity
first_name	string	first name of identity
last_name	string	last name of identity
email	string	email of identity
company	string	name of business
business_id	int	id of business tied to group
active	boolean	whether business is active

Roles are a means of describing an Identity’s relationship to an Accounting System. FreshBooks is moving over the long term away from using Roles and Accounting Systems as primary objects in the Identity Model, so there is some overlap between this data and Business Memberships. Whenever possible, try to make use of Business Memberships rather than Roles.

Role Fields
field	type	description
id	int	unique role id
role	string	name of role
systemid	int	unique integer identity of accounting system
userid	int	unique id for user within context of accounting system
created_at	datetime	role creation time in YYYY-MM-DDTHH:MM:SSZ format
links	object	list of related links to this resource
accountid	string	unique string identity of accounting system

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": "staff",
        "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"
      }
    ]
  }
}