×
Freshbooks
Official App
Free – Google Play
Get it

Business, Roles, and Identity

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.

The FreshBooks Identity Model

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.

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
fieldtypedescription
idintunique identity id
profileobjectuser profile information
first_namestringfirst name
last_namestringlast name
emailstringthe email identity
confirmed_atdatetimeemail confirmation time in YYYY-MM-DDTHH:MM:SSZ format
created_atdatetimeidentity creation time in YYYY-MM-DDTHH:MM:SSZ format
unconfirmed_emailstringdeprecated
setup_completebooleanwhether identity has been populated with necessary data
phone_numbersarraylist of named phone numbers
addressesarraylist of addresses
professionobjectinformation about the user's profession
linksobjectlist of related links to this resource
permissionsobjectlist of named permissions for each account
groupsobjectsee group table
subscription_statusesobjectdescriptions of account statuses
integrationsobjectlist of integrations
business_membershipsobjectcontains 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
fieldtypedescription
idintunique business id
namestringname of business
account_idstringunique string identity of accounting system if applicable
addressobjectobject containing business address info
phone_numberstringphone number
business_clientsarraylist 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
fieldtypedescription
idintunique id of group membership
group_idintunique id for group
rolestringnamed role identity holds in group
identity_idintunique id of identity
first_namestringfirst name of identity
last_namestringlast name of identity
emailstringemail of identity
companystringname of business
business_idintid of business tied to group
activebooleanwhether 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
fieldtypedescription
idintunique role id
rolestringname of role
systemidintunique integer identity of accounting system
useridintunique id for user within context of accounting system
created_atdatetimerole creation time in YYYY-MM-DDTHH:MM:SSZ format
linksobjectlist of related links to this resource
accountidstringunique string identity of accounting system
migrated_to_smux_atdatetimetime user migrated from FreshBooks Classic in YYYY-MM-DDTHH:MM:SSZ format, if applicable
modern_systembooleanwhether or not the user is using the new FreshBooks or FreshBooks Classic

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",
        "migrated_to_smux_at": null,
        "modern_system": true
      },
      {
        "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",
        "migrated_to_smux_at": null,
        "modern_system": true
      },
      {
        "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",
        "migrated_to_smux_at": null,
        "modern_system": true
      }
    ]
  }
}