There is a certain kind of frustration that only developers know. It is not the frustration of a hard problem. Hard problems are satisfying. It is the frustration of a problem that should be simple but has been made unnecessarily complicated by decisions that feel like they were made to protect a business model rather than serve the developer. Integrating with QuickBooks Online is that kind of frustration.

This is the story of building a QuickBooks integration for a .NET API, what we ran into, and what good API design should look like.

What We Were Trying to Do

The goal was straightforward. We have an internal licensing platform. QuickBooks is where the business manages its customers and invoices. We needed to pull customer data from QuickBooks and surface it through our own API. No user-facing OAuth dance, no multi-tenant complexity. Just one company, one QuickBooks account, background data sync. A task that should take an afternoon.

It did not take an afternoon.

The OAuth Problem

QuickBooks uses OAuth 2.0. That is fine. OAuth 2.0 is a well understood standard and using it makes sense for a platform that supports thousands of third party integrations. The problem is not OAuth itself. The problem is that Intuit has wrapped OAuth in layers of ceremony that make a simple internal integration feel like you are launching a product on the App Store.

To get an access token you need a developer account, an app registered on their developer portal, a redirect URI that Intuit approves, a sandbox company, and then you need to complete a browser based login flow just to get the initial tokens. For a single tenant internal integration where you own the QuickBooks account, this is absurd. There is no reason a developer should have to open a browser, log into a portal, and manually copy tokens out of a URL just to talk to an API they have full rights to access.

Compare this to something like Stripe. You go to your dashboard, copy your secret key, put it in your environment variables, and make API calls. That is it. QuickBooks could offer the same for single tenant use cases. A long lived API key or a simple client credentials flow would solve this entirely. They do not offer it.

The workaround we landed on was doing the OAuth flow once manually using Postman, storing the resulting access token and refresh token in environment variables, and having the application bootstrap those tokens at startup. The refresh token lasts 100 days and gets automatically rotated. It works, but it is a workaround for a problem that should not exist.

The Response Problem

Once you get past authentication the next frustration is the API responses themselves. QuickBooks returns deeply nested JSON that feels like it was designed for a SOAP era XML schema and then converted to JSON without rethinking the structure.

A simple customer query returns something like this:

{
  "QueryResponse": {
    "Customer": [
      {
        "Id": "1",
        "DisplayName": "John Doe",
        "PrimaryEmailAddr": {
          "Address": "john@example.com"
        },
        "PrimaryPhone": {
          "FreeFormNumber": "0700 000 000"
        },
        "BillAddr": {
          "Line1": "123 Main St",
          "City": "Nairobi"
        },
        "MetaData": {
          "CreateTime": "2023-01-01T00:00:00",
          "LastUpdatedTime": "2024-01-01T00:00:00"
        }
      }
    ],
    "startPosition": 1,
    "maxResults": 100,
    "totalCount": 1
  },
  "time": "2024-01-01T00:00:00"
}

You asked for customers. You got customers wrapped in a QueryResponse wrapper, with email nested inside a PrimaryEmailAddr object with an Address field, and phone inside a PrimaryPhone object with a FreeFormNumber field. Every field name is PascalCase. The structure is inconsistent across entity types. And if there are no customers matching your query, the Customer array is simply absent from the response entirely rather than returning an empty array.

That last point is particularly annoying. It means every consumer of this API has to defensively check whether the property exists before trying to read it:

var customers = root.TryGetProperty("Customer", out var ca)
    ? JsonSerializer.Deserialize<List<CustomerDTO>>(ca.GetRawText(), JsonOptions)!
    : new List<CustomerDTO>();

This is not difficult code to write but it is code that exists entirely because of a poor design decision. A well designed API returns an empty array, not a missing field.

What Good API Design Looks Like

The contrast with well designed APIs is stark. When you call a modern API you get back a flat, predictable response. Fields are always present even if empty. Naming is consistent. Pagination is standard. Errors are structured and meaningful.

A customer endpoint on a well designed API returns something like:

{
  "data": [
    {
      "id": "1",
      "name": "John Doe",
      "email": "john@example.com",
      "phone": "0700 000 000",
      "address": {
        "line1": "123 Main St",
        "city": "Nairobi"
      },
      "createdAt": "2023-01-01T00:00:00Z",
      "updatedAt": "2024-01-01T00:00:00Z"
    }
  ],
  "pagination": {
    "total": 1,
    "page": 1,
    "perPage": 100
  }
}

Flat where it can be flat. Nested only where nesting adds genuine meaning. Empty arrays instead of missing fields. ISO 8601 timestamps. Lowercase snake case or camelCase, pick one and stick to it. Authentication that does not require a browser and a Postman collection just to get started.

This is not a high bar. Most well resourced API teams clear it easily. QuickBooks is a product used by millions of businesses and thousands of developers. The developer experience should be a first class concern, not an afterthought.

The Integration We Built

In the end we built a clean abstraction over the QuickBooks API that shields the rest of our application from its quirks. The QuickBooksService owns the token management, the company ID, and the response mapping. Controllers just call GetCustomersAsync() and get back clean DTOs. Nobody else in the codebase has to know that somewhere underneath there is a QueryResponse wrapper with conditionally present arrays and FreeFormNumber fields.

This is the right approach when you are stuck with a third party API you cannot change. You build a clean seam, you absorb the ugliness in one place, and you expose something simple to the rest of your system.

But you should not have to. An API that requires this much defensive wrapping is an API that has externalised its own design debt onto every developer who integrates with it. The time we spent figuring out OAuth workarounds and defensive JSON parsing is time we could have spent building actual features.

The Broader Point

QuickBooks is not unique in this. There is a whole category of enterprise and legacy adjacent APIs that treat developer experience as optional. They were built when APIs were primarily consumed by big system integrators who had teams to absorb the complexity, and they have never been rethought for a world where a two person startup might need to integrate in a weekend.

The standard has moved. Developers now expect authentication that takes minutes not days. They expect responses that are clean and predictable. They expect documentation that shows real examples and acknowledges real edge cases. They expect SDKs that actually work.

If you are building an API today, make it boring to integrate with. Boring means it works the first time. Boring means the response shape is obvious. Boring means authentication is a key in an environment variable, not a Postman collection and a blog post.

Your users will not write about you. That is the highest compliment an API can receive.

Happy Coding!