Business, Roles, and Identity
FreshBooks users are uniquely identified by their email across our entire product. One user may act on several Businesses in different ways, and our Identity model is how we keep track of it. Each unique User has an Identity, and each Identity has Roles and Business Memberships which define the permissions they have. You can use the Account Information endpoint on this page to look up that information.
The endpoints listed on this page are accessible under the /auth path in the FreshBooks API, and provides OAuth authentication, preferences, permissions, roles, and business information.
Access Requirements
| Access | Requires Authorization |
| Scopes | user:profile:read |
The FreshBooks Identity Model
For a more in-depth explanation, see our page on the Identity Model of FreshBooks.
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 |
| 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 |
| 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/meResponse:
{
"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": "[email protected]",
"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": "[email protected]",
"company": "BillSpring",
"business_id": 77128,
"active": true
},
{
"id": 168372,
"group_id": 96277,
"role": "owner",
"identity_id": 712052,
"first_name": "Bruce",
"last_name": "Wayne",
"email": "[email protected]",
"company": "BillSpring",
"business_id": 77128,
"active": true
},
{
"id": 1570108,
"group_id": 568705,
"role": "manager",
"identity_id": 712052,
"first_name": "bruce",
"last_name": "Wayne",
"email": "[email protected]",
"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"
}
]
}
}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": "[email protected]",
"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": "[email protected]",
"company": "BillSpring",
"business_id": 77128,
"active": true
},
{
"id": 168372,
"group_id": 96277,
"role": "owner",
"identity_id": 712052,
"first_name": "Bruce",
"last_name": "Wayne",
"email": "[email protected]",
"company": "BillSpring",
"business_id": 77128,
"active": true
},
{
"id": 1570108,
"group_id": 568705,
"role": "manager",
"identity_id": 712052,
"first_name": "bruce",
"last_name": "Wayne",
"email": "[email protected]",
"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"
}
]
}
}