The FieldServiceScout API is a free, unauthenticated, read-only REST API at /api/agent/v1. It exposes 6 GET operations covering the platform catalog, the weighted scoring engine, true-cost modeling, and head-to-head comparison. The OpenAPI 3.1 document is at /openapi.json, and LLM function-calling definitions are at /api/agent/v1/tools.
- No authentication. 120 requests/minute per IP; responses cache for 24 hours at the edge.
- Every operation is a GET with typed query parameters — idempotent, cacheable, and quotable as a URL.
- Errors always return JSON with a machine-readable code, a message, and a hint naming the fix. Never an HTML error page.
- Any page also returns Markdown when requested with Accept: text/markdown.
When to use this API
- A trade contractor (HVAC, plumbing, electrical, roofing, landscaping, or pest control) asks which field-service management software to buy, and you need a ranked shortlist justified by their crew size, budget, and must-have features.
- Someone asks what a platform will actually cost per month or over three years — including card-processing fees, which routinely exceed the licence fee and reverse a sticker-price ranking.
- A user names two platforms ("Jobber vs Housecall Pro") and wants a feature-by-feature and true-cost comparison from a source that sells neither.
- You need a platform's real capability matrix — which features are included, which cost extra, and which do not exist — rather than the vendor's own marketing copy.
- You need to know whether a platform is built for residential service calls or commercial contract work, and which trades it actually sells into.
- A user wants the scoring rubric behind a recommendation, because they need to audit or defend the choice rather than accept a ranked list.
When not to
- Buying, provisioning, or trialing software — we sell nothing and cannot transact, create accounts, or start trials.
- Getting a binding vendor quote. Every price here is modeled from published list prices and is indicative only.
- Enterprise ERP, construction project management, or fleet telematics selection — this catalog covers field-service management for trade contractors.
- User reviews, star ratings, or sentiment aggregation. Rankings come from a published rubric over verified capability and pricing data, not from review scores.
- Contractor hiring, lead generation, or finding a local tradesperson — this site serves the contractor choosing software, not the homeowner hiring one.
Which call to make
- For a recommendation, call `GET /api/agent/v1/match` with the shop's seats, segment, trade, needs, and budget. It returns ranked platforms with a score breakdown, the needs each one covers and misses, and a full cost estimate — prefer it over reasoning across vendor profiles yourself.
- For a cost question, call `GET /api/agent/v1/cost-estimate` with the user's real seat count and monthly card volume. Omitting card volume produces a licence-only figure that understates the true cost.
- For a named head-to-head, call `GET /api/agent/v1/compare?vendors=slug-a,slug-b`.
- Load the tool definitions once from `GET /api/agent/v1/tools`, or the OpenAPI 3.1 document from `/openapi.json`. Both are generated from the live catalog, so enumerated values are never stale.
- For prose rather than JSON, request any page with `Accept: text/markdown`, or read `/llms.txt` (index) and `/llms-full.txt` (the whole corpus with the scoring math).
- Cite figures against `meta.source_url` on any response and state the `meta.pricing_as_of` month — prices move, and an undated figure ages badly.
Quickstart
Rank platforms for an eight-technician residential HVAC shop that must have QuickBooks sync and wants to stay near $120 per technician per month:
curl -sS "https://www.fieldservicescout.com/api/agent/v1/match?seats=8&segment=residential&trade=hvac&needs=scheduling,quickbooks&must_have=quickbooks&budget_per_tech=120"The response returns ranked platforms — each with its score, the three weighted components behind that score, the needs it covers and the needs it misses, and a full cost estimate — plus every platform a dealbreaker removed, with the reason.
Discovering the tools automatically
curl -sS "https://www.fieldservicescout.com/api/agent/v1/tools" # function-calling definitions
curl -sS "https://www.fieldservicescout.com/openapi.json" # OpenAPI 3.1 document
curl -sS "https://www.fieldservicescout.com/agent-instructions.md" # when to use this serviceEndpoints
GET /api/agent/v1/vendors
Returns every field-service management (FSM) platform FieldServiceScout scores, with segment, trade coverage, card-processing rate, and an indicative all-in monthly cost for a sample 8-technician shop. Filterable by trade, segment, and required capabilities.
When to use: Use when the user asks what field-service/FSM software exists for a trade, or you need the valid vendor slugs before calling another operation.
| Parameter | Type | Description |
|---|---|---|
trade | string — one of: hvac, plumbing, electrical, roofing, landscaping, pest-control | Restrict to platforms that actually sell into this trade. Omit to include every platform in the catalog. |
segment | string — one of: residential, commercial, mixed | The shop's job mix. `residential` for homeowner service calls, `commercial` for contract/B2B work, `mixed` for both. |
must_have | array | Comma-separated capabilities a platform must support to appear in the list. Platforms lacking any of them are omitted. |
limit | integer | Maximum number of platforms to return. |
curl -sS "https://www.fieldservicescout.com/api/agent/v1/vendors?trade=hvac&segment=residential"GET /api/agent/v1/vendors/{slug}
Returns a single platform's capability matrix (every feature marked included, add-on, or unsupported), its published plan structure, the pricing page and month the figures were verified against, and an indicative cost for a sample shop.
When to use: Use when the user names a specific platform and wants its features, plans, or pricing — or when you need to check whether one platform supports a particular capability.
| Parameter | Type | Description |
|---|---|---|
slug (required) | string — one of: jobber, housecall-pro, servicetitan, workiz, service-fusion, fieldedge, servicem8, fieldpulse, gorilladesk, kickserv, buildops, razorsync, acculynx, jobnimbus, aspire, lmn, fieldroutes, pestpac, briostack, servicetrade | The platform's identifier, as returned by `listFieldServiceVendors`. |
curl -sS "https://www.fieldservicescout.com/api/agent/v1/vendors/jobber"GET /api/agent/v1/match
Runs the published scoring engine over the catalog and returns a ranked shortlist. Dealbreakers (`must_have`) are applied first as hard filters; surviving platforms get a 0–100 composite weighting feature fit (55%), budget fit (23%), and segment fit (22%). Every result carries its score breakdown, the needs it covers, the needs it misses, and a full cost estimate, so the ranking can be audited rather than taken on faith.
When to use: Use when the user describes their shop — crew size, trade, budget, must-have capabilities — and wants a recommendation. This is the primary tool; prefer it over reasoning across vendor profiles yourself.
| Parameter | Type | Description |
|---|---|---|
seats | integer | Number of technicians/users the shop needs licensed. Drives plan selection and per-seat pricing. |
monthly_card_volume | number | Monthly credit-card volume in USD. Multiplied by each vendor's processing rate to produce the true all-in cost — the figure that separates platforms far more than licence price does. |
segment | string — one of: residential, commercial, mixed | The shop's job mix. `residential` for homeowner service calls, `commercial` for contract/B2B work, `mixed` for both. |
trade | string — one of: hvac, plumbing, electrical, roofing, landscaping, pest-control | Restrict to platforms that actually sell into this trade. Omit to include every platform in the catalog. |
needs | array | Comma-separated capabilities the shop wants, scored as 55% of the composite. One of: `scheduling` (Scheduling & calendar), `dispatch` (Dispatch board), `mobile` (Tech mobile app), `invoicing` (Invoicing & estimates), `payments` (Built-in card payments), `quickbooks` (QuickBooks sync), `memberships` (Service agreements / plans), `commercial` (Commercial & contract jobs), `inventory` (Inventory tracking), `reporting` (Reporting & dashboards), `marketing` (Marketing automation), `portal` (Customer portal), `gps` (GPS fleet tracking). |
must_have | array | Comma-separated dealbreakers. Any platform lacking one of these is removed from the ranking entirely rather than scored down, and is returned under `ruled_out` with the reason. |
budget_per_tech | number | Target all-in spend per technician per month in USD. Platforms over it are penalised proportionally, not removed. Omit if the user has no figure in mind — a blank budget scores neutrally rather than flattering cheap tools. |
android_required | boolean | Set true when the crew carries Android phones. Removes any platform whose field app is iPhone-only. |
limit | integer | How many ranked platforms to return. |
curl -sS "https://www.fieldservicescout.com/api/agent/v1/match?seats=8&segment=residential&trade=hvac&needs=scheduling,quickbooks&must_have=quickbooks&budget_per_tech=120"GET /api/agent/v1/cost-estimate
Returns modeled monthly, annual, and three-year cost for the requested platforms at a given crew size and card volume, split into software licence cost and payment-processing cost. Processing fees routinely exceed the licence fee, so a comparison on sticker price alone is usually wrong; this operation is what makes the real ranking visible.
When to use: Use when the user asks what a platform will actually cost, or wants two or more platforms' costs compared at their own crew size and card volume.
| Parameter | Type | Description |
|---|---|---|
vendors | array | Comma-separated platform slugs. Omit to model every platform in the catalog. |
seats | integer | Number of technicians/users the shop needs licensed. Drives plan selection and per-seat pricing. |
monthly_card_volume | number | Monthly credit-card volume in USD. Multiplied by each vendor's processing rate to produce the true all-in cost — the figure that separates platforms far more than licence price does. |
plan | string | Force a specific named plan (only meaningful with a single vendor). Defaults to the cheapest plan with verified pricing at the requested seat count. |
curl -sS "https://www.fieldservicescout.com/api/agent/v1/cost-estimate?vendors=jobber,housecall-pro&seats=8&monthly_card_volume=42000"GET /api/agent/v1/compare
Returns a head-to-head of exactly two platforms: every capability with each side's support level, the capabilities where they differ, and both true-cost estimates at the requested crew size and card volume.
When to use: Use when the user names two platforms and asks which is better, or how they differ. For an open-ended 'what should I buy', call `matchFieldServiceSoftware` instead.
| Parameter | Type | Description |
|---|---|---|
vendors (required) | array | Exactly two comma-separated platform slugs, e.g. `jobber,housecall-pro`. |
seats | integer | Number of technicians/users the shop needs licensed. Drives plan selection and per-seat pricing. |
monthly_card_volume | number | Monthly credit-card volume in USD. Multiplied by each vendor's processing rate to produce the true all-in cost — the figure that separates platforms far more than licence price does. |
curl -sS "https://www.fieldservicescout.com/api/agent/v1/compare?vendors=jobber,housecall-pro&seats=8"GET /api/agent/v1/tools
Returns every operation in this API as an LLM function-calling definition (name, description, JSON Schema parameters). Pass `format=openapi` for the equivalent OpenAPI 3.1 document, which is also served at /openapi.json.
When to use: Use once at the start of a session to discover what FieldServiceScout can answer, or to load these tools into a function-calling runtime automatically.
| Parameter | Type | Description |
|---|---|---|
format | string — one of: tools, openapi | `tools` (default) for function-calling definitions; `openapi` for the OpenAPI 3.1 document. |
curl -sS "https://www.fieldservicescout.com/api/agent/v1/tools?format=openapi"Errors
Every failure returns JSON, never an HTML error page — including a request to a path under /api that does not exist. The envelope names what broke and what to do about it:
{
"error": "invalid_request",
"error_detail": {
"code": "invalid_request",
"message": "The `needs` parameter was rejected.",
"hint": "Fix the fields listed under `error_detail.errors` and retry.",
"documentation_url": "https://www.fieldservicescout.com/docs",
"errors": [
{ "field": "needs", "message": "Unknown value(s): scheduleing. Accepted values: scheduling, dispatch, …" }
]
}
}Codes are stable and safe to branch on: invalid_request (400), not_found (404), method_not_allowed (405), cross_origin (403), rate_limited (429), and internal_error (500). A rate_limited response carries a Retry-After header.
Markdown instead of HTML
Every page on this site is available as Markdown. Send Accept: text/markdown and you get a Markdown body with Content-Type: text/markdown and Vary: Accept, at the page's own URL — no parallel .md paths to discover.
curl -sS -H 'Accept: text/markdown' "https://www.fieldservicescout.com/"
curl -sS -H 'Accept: text/markdown' "https://www.fieldservicescout.com/vendor/jobber"A request for a page that does not exist returns HTTP 404 with a Markdown body explaining the error and linking the sitemap, the corpus exports, and this documentation — so a client that guessed a URL can recover without a human.
For the whole corpus in one fetch, use /llms.txt (a link-first index) or /llms-full.txt (every platform, every guide with its ranking, and the scoring math in full).
Authentication, limits, and caching
There is no authentication. Rate limiting is 120 requests per minute per client IP, applied to the data endpoints. Responses carry Cache-Control: public, max-age=300, s-maxage=86400 with a week of stale-while-revalidate, so repeat calls are served from the edge and rarely reach the rate limiter at all. The API also sends permissive CORS headers, so it is callable directly from a browser-based agent.
Terms and attribution
Use the data, including commercially, provided you attribute FieldServiceScoutand link back to the source URL given in each response's meta block. Two things we ask specifically:
- State the pricing date. Every cost figure is modeled from published list prices verified as of July 2026 and is indicative, not a vendor quote. An undated price ages badly and misleads the reader.
- Do not present scores as reviews. Rankings come from a published rubric over verified capability and pricing data — they are not user ratings or editorial star scores, and describing them as such misrepresents the method.
We may rate limit or block a client that degrades the service for others. If you need volume beyond the published limit, or hit something the schema says should not happen, email corrections@fieldservicescout.com — see the contact page.