Exercise 3 of 3 — The Big One: Contractors Cloud Job Log Middleware

What is an API?

An API (Application Programming Interface) is a set of rules for how software talks to other software. When you log into your bank's website, you're using a user interface (UI) — buttons, forms, visual stuff. An API is like a UI for software. Your code sends a structured request ("add this note to the Elm Street job") and Contractors Cloud processes it, just as if someone had typed it in manually.

What is a bearer token?

A bearer token is how Contractors Cloud knows your app is allowed into the account. Think of it like a valet key — you give the valet a special key that starts the car but won't open the trunk. The token gives your app access without sharing your password, and it carries only the permissions of the user who created it. Your code sends it on every single request, in a header that reads Authorization: Bearer YOUR_TOKEN. That is the whole handshake.

There is no sandbox. Read that twice.

QuickBooks gives developers a fake company full of fake data to practice on. Contractors Cloud does not. There is one environment and it is the live one. Everything you do in this exercise happens in your real account, against your real jobs, and your team will see it.

That is not a reason to skip the exercise. It is a reason to work in a specific order, and this exercise is built in that order:

• Read first, and read a lot. Every GET request is harmless. You cannot break anything by asking questions. Spend your mistakes here.
• Write exactly once, and write something additive. The one write in this exercise adds a note to a project. It does not change a contract, a price, a milestone, or a customer record.
• Label the write so a human knows what it is. Your test note will start with the words API TEST, so if a project manager sees it, they know it isn't a real job instruction.
• Clean up after yourself, and expect that to be the hard part. Section 8 covers why deleting is not always allowed.

What a real build looks like:

We have built a full document processing middleware for a client. It ingests PDFs, parses line items, maps them to records in the client's system, learns vendor patterns over time, validates everything, then pushes finished records in. It handles delivery documents, freight calculations, pricing lookups, and drift detection.

Yours does one thing: push a job note. That's the seed. Everything else grows from it.

The middleware runs on Python using Flask (a lightweight web framework). The exercises so far were just HTML files — this one is a real application with a server.

To talk to Contractors Cloud through the API, you need an API access token. You create it inside the Contractors Cloud web app, on your own account. It is free and it takes about a minute, assuming your user has the permission to do it.

Create the token:

If you can't find that screen:

Creating API tokens is a permissioned action, so a limited user may not see it at all. If the menu isn't there, don't go hunting through settings. Ask your Contractors Cloud administrator, or Contractors Cloud support, for exactly this:

Find your company id:

Contractors Cloud organizes a lot of the API around companies. Several URLs you'll use have a numeric company id sitting in the middle of them, like /companies/YOUR_COMPANY_ID/leads. You need that number.

The good news is you do not have to go find it in the web app. Once your token works, the API will tell you: the record for the logged-in user carries a default company on it. Section 6 makes that call. For now, just know that the number exists and that you'll have it in a few minutes.

First, have Claude set up the project structure. Notice what this prompt does not contain: your token. It tells Claude to write a .env file with a placeholder in it, and you will replace the placeholder yourself, in Notepad, in a moment.

Now put your token in, by hand:

Now for the big build. This prompt tells Claude to create the entire Flask application. It's longer than previous prompts because there's more to build, but the pattern is the same — describe what you want, Claude builds it.

The server is running. Now let's connect it to your Contractors Cloud account. This happens in two calls, and it's worth understanding why there are two.

Now read some real data back.

Stop and look at that for a second. That table was not typed by anyone. Your code asked Contractors Cloud a question and Contractors Cloud answered it. That is the read half of middleware, and it is already useful on its own — every dashboard, every report, every export you ever build starts exactly here.

The moment of truth. You're going to create a record in Contractors Cloud through your middleware.

Now verify it actually made it in. Not in your app — in the CRM:

Now make a mistake on purpose.

You typed API TEST and whatever came after it. Suppose you got that wording wrong and want to fix it. The obvious move is to update the note. Try it, and watch what happens:

Clean up:

You've made a handful of calls and they mostly worked. Real integration work is the other days. Every item below is a thing that actually happens on this API, costs an afternoon the first time, and costs ten seconds once you've seen it. Read them now so you recognize them later.

1. A 404 does not always mean the thing is gone.

It can also mean you invented a path. The documentation talks about lead sources, so /lead-sources feels like an obvious guess. It returns 404. The real path hangs the collection off the company:

The lesson is not "memorize this path." It is that a 404 from an API you're new to means "check the URL" far more often than it means "no such record." Look up the actual endpoint before you assume the data isn't there.

2. A 200 does not always mean it saved.

You proved this one yourself in Section 7. A note body is immutable; the PUT returns 200 and drops the field. The general rule that comes out of it: after any write that matters, read it back and compare. Your app should verify against the server's copy, not against the value it sent. That one habit will save you more grief than any other thing on this page.

3. A 400 for a filter that looks perfectly reasonable.

Filters are per endpoint, not global. filter[company_id] works in plenty of places, and on /accounts it returns 400. Nothing about your syntax is wrong; that endpoint simply doesn't offer that filter. Check the endpoint's own list of supported filters rather than assuming a filter that worked next door works here.

4. A 422 because a field is longer than you thought.

Several fields have length caps that are easy to blow past with real-world data:

• address_street — 50 characters
• title — 50 characters
• phone_work — 14 characters, which a formatted number with an extension exceeds immediately

They're in the API's schema, and they are exactly the kind of detail nobody reads until a batch import dies on record 340. If you're pushing data in from a spreadsheet, validate lengths on your side first and decide deliberately what to do with the overflow, rather than letting the API decide by rejecting it.

5. Some things the API will not do at all.

Custom field values can be read and set through the API. Custom field definitions cannot be created through it — those are configured in the web app only. If your plan depends on your middleware standing up new fields automatically, the plan needs changing. Find the walls early; they're cheaper to discover in design than in the middle of a build.

6. Side effects you didn't ask for.

Creating a project does more than create a project. It writes a system note into the activity feed, it fires a webhook, it geocodes the address if you didn't supply coordinates, and in an account with CompanyCam connected it spawns a matching place over there too. None of that is a defect. It is what "create a project" means in this system. Before you automate a write, ask what else that write sets in motion — and remember there's no sandbox in which to find out gently.

7. There is a rate limit, and you should stay well under it.

The ceiling sits around 300 requests per minute. A loop over a few hundred jobs will hit that without trying. Put a small deliberate pause between requests (a quarter of a second is plenty), and cache what you've already fetched so a re-run doesn't re-ask. Your build prompt in Section 5 already asked Claude for both.

Update your memory log with everything you accomplished:

You've built three things of increasing complexity:

• A standalone tool (Eisenhower Matrix) — HTML only, no backend
• A connected form (Homework Email) — HTML + Google Apps Script backend
• A real middleware (Job Log Importer) — Python + Flask + a bearer token + the Contractors Cloud API

The pattern is always the same:

1. Create a project folder with CLAUDE.md and a context/ folder (PROJECT.md, JOURNAL.md)
2. Describe what you want to Claude
3. Review the plan, approve it, let Claude build it
4. Test, customize, iterate
5. Update context/JOURNAL.md before closing

Ideas for what to build next:

• Turn the projects page into a real dashboard — jobs by milestone, by rep, by month, with the numbers you actually manage to
• Pull material orders and contracts and put revenue and material cost side by side on one screen
• Push job updates in from wherever they start — a form your crews fill out on a phone, a shared spreadsheet, an email inbox
• Export a weekly report to a spreadsheet on a schedule, so nobody has to remember to run it
• Connect to other APIs — Google, a supplier portal, an accounting system, whatever else your business runs on

Every one of these follows the same pattern you just learned. The only difference is which API you're talking to and what the UI looks like. Claude handles the technical details. You handle the vision.