×
Freshbooks
Official App
Free – Google Play
Get it

The Identity Model

Account IDs & Businesses

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 endpoin. An example of its response is in the code pane on the right. The two keys we care about most are roles and business_memberships.

Most roles have an accountid, as do all of the business objects listed in the business_memberships. Those business objects also each have an id, which is their business_id. Be careful not to mistake those ids for the id in the business_membership object.

Acting on a Specific Account

Calls to the /accounting endpoints take this form:

  1. /accounting/account/<account_id>/<service>/<resource>

Calls to the /timetracking/ and /projects/ endpoints often require a <business_id>, for example:

  1. /timetracking/business/<business_id>/time_entries

All users have a business_id. Most users have accounts, but not all. 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 hasn’t got 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_id> for a user.

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
      }
    ]
  }
}