What we do
Tools
Industries
Department
How we workLet's talk →
Home/FreshBooks/Building on the FreshBooks API Without Surprises
FreshBooks

Before You Build on the FreshBooks API: Two IDs, One-Use Refresh Tokens, Verified Webhooks

Your token works and the test call returns your name. Then the clients endpoint wants one ID and the projects endpoint wants another. FreshBooks' REST API splits accounting from everything else, its refresh tokens only work once, and webhooks stay silent until you hand back a verifier. Get those three right and the rest is ordinary API work.

accountId for accounting, businessId for projects and time

Both come from the identity call, /auth/api/v1/users/me, which needs the user:profile:read scope. Read business_memberships and take the IDs from the nested business object.

business.account_id

Accounting paths

  • Paths look like /accounting/account/{accountId}/users/clients.
  • Clients, invoices and expenses live here.
  • Webhook callbacks are registered under the account too.
  • Some users, clients for example, have no account_id at all.
business.id

Projects and time tracking

  • Paths start /projects/ or /timetracking/.
  • They generally take the businessId instead.
  • Don't mix up the business's id with the id of the business_membership around it.
  • FreshBooks' identity docs show a business_uuid as well, without saying what it's for.

Call the identity endpoint once after authorization and store both IDs next to the tokens. Most "not found" surprises early on trace back to the wrong one.

Authorizing a FreshBooks app and getting a first answer

  1. 1

    Register the app

    Use the new app form on the FreshBooks developer page. The name has to be unique because users see it in the app store and on their integrations page. The redirect URI is the endpoint in your code that receives the authorization code.

  2. 2

    Point the user at the authorize screen

    Redirect to auth.freshbooks.com/oauth/authorize/ with response_type=code, your client ID and redirect URI. The user sees the scopes you ask for on that screen, so ask for what the job needs.

  3. 3

    Exchange the code

    Post it to api.freshbooks.com/auth/oauth/token for a bearer token and a refresh token.

    Watch for: the expiry inside the bearer token. FreshBooks only says they're short-lived, so read it rather than hardcoding a lifetime.

  4. 4

    Make a test call

    Send Authorization: Bearer and Content-Type: application/json to api.freshbooks.com/test. It returns a user object with name and email, which proves the token works.

  5. 5

    Fetch identity and save the IDs

    Call /auth/api/v1/users/me, then store the account_id and business id for each business the user belongs to.

FreshBooks integrations that pass testing and fail in week three

Two processes refreshing the same user

How you'll know: One worker succeeds, the other gets an invalid-token error, and soon nothing can refresh.

Fix: Refresh tokens are one-time-use, only one is valid per user per app, and every new bearer token voids the old refresh token. Let one job refresh, and save the new refresh token before anything else uses it.

A webhook that was registered but never verified

How you'll know: The callback exists, and no events ever arrive.

Fix: After you POST to the callbacks endpoint, FreshBooks posts a verification code to your URI. PUT it back to /events/callbacks/{callback_id} as the verifier. A PUT with resend: true asks for a fresh one.

Signatures that never match

How you'll know: Every delivery fails your check against X-FreshBooks-Hmac-SHA256.

Fix: The verifier is the signing secret. The signature is base64, over the parameters as a JSON string with values cast to strings, and spacing matters: Python's json.dumps adds spaces after colons and commas, and dropping them changes the result.

A handler that does the work before it answers

How you'll know: Deliveries retry, some vanish, and eventually the webhook is switched off.

Fix: FreshBooks waits ten seconds and treats anything but a 2xx as failure. It retries, then drops the message, and can disable a webhook that keeps failing. Reply at once, process afterwards, and resend verification to switch it back on.

Treating the payload as the record

How you'll know: Your code expects invoice details and gets a handful of IDs.

Fix: Deliveries carry the event name, object_id, account_id and business_id as form fields. Fetch the object from the API with that ID.

Zapier, the app marketplace, or your own code

Not every FreshBooks connection needs the API. Zapier handles one-way triggers, such as creating a client when a form comes in, and our Zapier webhooks page covers its edges. FreshBooks' app marketplace lists ready-made connectors, and payroll is now a FreshBooks add-on, covered on our FreshBooks payroll page.

The API earns its keep when data has to move both ways, carry your own matching rules, or reach a CRM, processor or project tool nobody's built a connector for. That's where n-frames does the build: a two-way client and deal sync, payments matched back to invoices, or time entries pulled into job costing. For the wider product, start at our FreshBooks page.

Questions people ask

Does FreshBooks have a public API developers can use?

Yes. It's a documented REST API with OAuth 2.0, open to anyone who registers an app on the developer page, not just marketplace partners. Accounting records sit under account-ID paths, projects and time tracking under business-ID paths, and webhooks cover events like invoice.create and time_entry.update.

Can FreshBooks integrate with Salesforce directly?

Through third parties. FreshBooks doesn't ship its own Salesforce connector, but there are Zapier-style automations and a few sync products built for the pair. When those can't map your objects or rules, the job is a custom integration against both APIs.

Does FreshBooks connect to Shopify for invoicing?

Yes, through Shopify connectors listed in FreshBooks' app marketplace, which bring orders into FreshBooks without custom development. Check what the current listing syncs before relying on it for payouts or fees.

Can I use Zapier with FreshBooks instead of the API?

Often, yes. FreshBooks is a Zapier app, and that's fine for one-direction triggers. Two-way sync, deduplication and custom matching rules are where you move to the API.

Who builds FreshBooks API integrations?

n-frames does, for businesses whose FreshBooks needs to agree with a CRM, a processor or a project tool. We handle the app registration, token storage, webhook verification and the matching logic, then keep it running.

Let's talk

Tell us the one thing your team does manually that eats up time. We read every message and reply within a day.