SubSub Integrations & API

Overview

What you can connect

Will it work with mine?

Only the first tier is a claim about SubSub. The other two are a claim about the thing doing the sending, which is why they are separated: a system in the second or third tier works today and always has, and a system in the first needs somebody here to have had a real payload from it in front of them. That is the whole difference, and it is the difference that decides whether anything needs mapping.

Ways to start

Pick whichever matches who is setting it up. None of them needs anything installed from SubSub.

What happens next

The job lands on your Jobs screen with its trades unassigned, and it counts toward Unassigned trade slots on your dashboard. From there it is the ordinary SubSub flow: assign a contractor per trade, or ask several of yours to quote it, and SubSub checks their insurance and license before the work order goes out.

Get started with SubSub

Connect your CRM

When a job gets scheduled in your CRM, send it here. It arrives in SubSub as a job with its trades unassigned (the queue you open SubSub to clear), and you pick who does the work. There are two ways in, because most of the systems that would send you a job cannot set an HTTP header.

The endpoint

POST https://api.subsub.work/api/v1/jobs
Authorization: Bearer ssk_your_token_here
Content-Type: application/json

No header? Use the webhook address

Most CRMs and automation builders have a step that takes a URL and nothing else. There is no field for an Authorization header, so a token that can only arrive in a header cannot arrive at all. For those, the token travels in the path:

POST https://api.subsub.work/api/v1/hooks/generic/<your-webhook-token>
Content-Type: application/json

SubSub builds that address for you — it is on the same panel as the token, beside it, at the moment you create it. It is not a weaker door: every check the header endpoint makes, this one makes. But the token is in the address, so treat the whole URL like a password.

The segment before the token names which system is sending, and that is the only thing it changes: SubSub reads that system's field names instead of its own.

A system with no entry of its own is not unsupported. It uses generic, and whatever sends the request maps its fields onto SubSub's on the way out — in Zapier or Make that is the webhook step's own field mapping, and it takes a minute. An entry is added above when somebody has a real payload from that system in front of them: inventing plausible field names would produce an integration that looks supported and fails silently on first contact, which is worse for everybody than saying generic.

Trades arrive as your own words

No CRM has a concept of a trade. What yours sends is a job type, a status and tags — your own words, and nothing in them means roofing until somebody says so. So the webhook address does not ask for trades. It reads those words and looks them up against the rules on your account, under My account → Integrations → Job types and trades. Rules apply to every system you post from, so it is one list however many you connect.

A job whose words match nothing still arrives. It lands with no trades, the reply says so, and the word goes on a list on that same screen where one tap answers it. Refusing the job would be worse in the way that is hardest to notice: your CRM would not get a 200, so it would retry, so it would keep not getting one — and nobody would be told the work never reached SubSub.

HTTP/1.1 201 Created

{
  "ok": true,
  "source": "generic",
  "duplicate": false,
  "jobId": "5b0f…",
  "trades": [],
  "needsTrades": true,
  "unmapped": ["type:Roof Replacement"],
  "url": "https://app.subsub.work/?job=5b0f…"
}

Watch needsTrades while you are still setting up. It is the difference between a job that landed ready to assign and one waiting on a word nobody has translated yet.

A complete example

curl -X POST https://api.subsub.work/api/v1/jobs \
  -H "Authorization: Bearer $SUBSUB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "CRM-1041",
    "source": "generic",
    "title": "Reroof — 14 Alder Way",
    "trades": ["roofing", "gutters"],
    "date": "2026-10-14",
    "time": "08:00",
    "address": "14 Alder Way",
    "area": "Seattle",
    "zip": "98101",
    "client": "M. Okafor",
    "sqft": 2400,
    "stories": 2,
    "scope": "Tear off and replace, 30yr architectural."
  }'

HTTP/1.1 201 Created

{
  "ok": true,
  "duplicate": false,
  "jobId": "5b0f…",
  "trades": ["roofing", "gutters"],
  "url": "https://app.subsub.work/?job=5b0f…"
}

Required fields

Five things, and only five. Everything a job can carry is accepted, but requiring a square footage no CRM holds would make the integration fail over a number nobody needs — so required here means the job cannot do its work without it.

Optional fields

Retries will not duplicate

Webhooks retry. If your CRM does not get a 200 or 201 back, it sends again — and without something to recognize the second delivery by, one scheduled job becomes four jobs on your roster and four contractors asked to show up on a Tuesday.

That is what externalId is for. Send the same one twice and the second call returns 200 with "duplicate": true and the id of the job that already exists. Nothing is created. You can retry as many times as you like.

HTTP/1.1 200 OK

{
  "ok": true,
  "duplicate": true,
  "jobId": "5b0f…",
  "url": "https://app.subsub.work/?job=5b0f…"
}

Ids are scoped to your account and your source, so another SubSub customer using the same CRM with the same job number does not collide with you.

Trades

Use these exact ids in trades:

roofing siding windows_doors gutters soffit_fascia coping masonry solar framing concrete foundation excavation demolition electrical plumbing hvac insulation drywall painting flooring tile_stone cabinets_counters trim_carpentry deck_fence hardscaping landscaping garage_doors restoration cleaning

Send inspections

The same token posts move-in and move-out inspections, for an account that keeps buildings. Already walking units in an inspection app, a tablet form or a spreadsheet? Post the walk and it lands in SubSub as a draft inspection with its rooms and conditions on it — ready to read, finish, and raise the work from.

POST https://api.subsub.work/api/v1/inspections
Authorization: Bearer ssk_your_token_here
Content-Type: application/json

Or, where there is no field for a header, the same webhook address with the object on the end:

POST https://api.subsub.work/api/v1/hooks/generic/<your-webhook-token>/inspections
Content-Type: application/json

What to send

Photographs are not accepted here. A webhook carries JSON and a photograph is bytes; the rooms, the conditions and the notes arrive, and pictures are added on the inspection itself. Common field names are read as well as SubSub's own — external_id, items, condition, notes, completed_at and the rest — so most systems need no mapping.

Conditions arrive as your own words

Every inspection app has its own scale: pass and fail, good and fair and poor, 1 to 5, A to C. SubSub has four room statuses — not checked, OK, follow-up and fail — and reads the ordinary words for the last three without being told.

A word it does not know lands the room not checked, which is deliberate: anything else would assert that somebody walked the room and found nothing wrong. The walk still arrives — it is never refused over a word — and the reply says which words were not understood, in unmapped, with needsAnswers counting the rooms left without one. Say what those mean once under My account → Integrations → Inspections from your inspection app and every walk after that reads properly.

What comes back

{
  "ok": true,
  "source": "generic",
  "duplicate": false,
  "inspectionId": "9f2c…",
  "status": "draft",
  "rooms": 11,
  "needsAnswers": 2,
  "unmapped": ["Grade C"],
  "url": "https://app.subsub.work/?inspection=9f2c…"
}

It is always a draft, and nothing finishes it but a person. Finishing is what makes the inspection a document somebody can quote back, what writes its summary and what lets it be sent to the building's owner — so it is one tap on the screen rather than something a webhook does. The rooms, the notes and the photographs are all editable until then.

An account with no buildings answers no_buildings: there are no units to walk. That is a different gate from the jobs endpoint, which a general contractor can use.

Using Postman

The SubSub API collection holds every call on this page with a working example body: the three reads, posting a job, posting an inspection, and the webhook-address versions of both. In Postman, choose Import, then Link, and paste:

https://api.subsub.work/api/v1/postman.json

Or download the collection and import the file. Then open the collection's Variables, paste your API key into token, and send Who this token belongs to first: it is a read, so it tests the key without creating anything. Make the key in SubSub under My account → Integrations → API keys.

Zapier

Not a developer? This is the way in.

SubSub has a Zapier app, so a Zap can create a job without anybody pasting a URL: the token is a Zapier connection, and Trades and Property are dropdowns rather than text boxes. It uses this endpoint — Zapier can set a header, so it does not need the webhook address above.

It is a private app while it is new, which means you join it by invitation rather than finding it in Zapier's directory. Ask us for the link. If you would rather not wait, a Webhooks by Zapier step pointed at your generic webhook address does the same job today — the app is convenience and findability, not capability.

Make and n8n

Neither needs an app from SubSub. Add an HTTP step (Make) or an HTTP Request node (n8n), set it to POST to your generic webhook address, and map your fields onto SubSub's: externalId, title, trades, date and an address or propertyId are the five it needs. Both tools can set a header too, so the Authorization: Bearer endpoint works from either if you prefer it.

Reference

The reads, the errors and how to keep a key safe. These apply to every endpoint on this page.

Three reads, for building an integration

Both take the same Authorization: Bearer header, and both are checked the same way a POST is — same plan gate, same token lookup. A read endpoint that is a lighter door is a lighter door.

When something is wrong

Errors name the field, with a code your integration can branch on and a message for whoever ends up reading the log.

HTTP/1.1 400 Bad Request

{
  "error": "invalid_request",
  "message": "Some fields were missing or not understood. See `errors` for which.",
  "docs": "https://subsub.work/developers",
  "errors": [
    { "field": "trades", "code": "unknown_trade", "message": "\"juggling\" is not a trade SubSub knows." },
    { "field": "date", "code": "invalid", "message": "date must be a real calendar day, as YYYY-MM-DD." }
  ]
}

Keeping the token safe

• It is shown once. SubSub stores a SHA-256 of it, not the token, so it cannot be read back — by you or by us. Lost it? Revoke it and make another.
• It belongs to one account and can only create jobs on that account.
• Pause any integration with its switch under My account → Integrations: what it sends is refused with integration_paused until it is switched back on.
• Revoke it any time under My account → Integrations. Anything using it stops immediately; jobs it already created stay, because that work is real.
• Keep it server-side. Anyone holding it can create jobs on your account.