canonical: https://jentic.com/apis/fergus.com/fergus # Fergus API The Fergus API provides programmatic access to the Fergus job management platform used by trades businesses such as plumbers and electricians. It exposes 74 endpoints for jobs, quotes, customer invoices, sites, contacts, time entries, calendar events, pricebooks, and notes, with text-search query parameters across many list operations. Authentication supports both Personal Access Tokens and OAuth2, and the API enforces a rate limit of 100 requests per minute per company. ## For AI agents Manage trade-services jobs, quotes, invoices, time entries, and calendar events for plumbers and electricians using Fergus, with bearer token or OAuth2 auth. ## Scope Does not handle payroll, accounting ledgers, or payment processing - use for trades job management, quotes, invoices, and scheduling only. ## Capabilities - Create and update jobs with phases, statuses, and assigned tradespeople - Generate quotes against jobs and convert them into customer invoices - Track time entries logged by field staff against specific jobs - Schedule calendar events tied to jobs and assigned users - Search customers and sites with substring filters across name and section fields - Maintain a pricebook with tiered pricing for parts and labour ## Use cases ### Quote-to-Invoice Trade Workflow Automate the path from job creation through quote acceptance to invoice issue for trades businesses. The Fergus API exposes /jobs, `/jobs/{id}/quotes`, and /customer-invoices as related endpoints so an agent can move work through pipeline stages without manual data entry. Eliminates the typical 15-20 minute admin overhead per job common in plumbing and electrical contractors. Example prompt: Create a job, attach a quote with three line items, finalise it via PUT `/jobs/{jobId}/finalise`, then generate the customer invoice ### Field Staff Time Tracking Pull time entries logged by tradespeople against jobs to compute payroll hours and job profitability. The Fergus API surfaces time entries with job and user filters, so an agent can summarise hours per job, per person, or per period. This replaces spreadsheet-based timesheet collation common in small trades businesses. Example prompt: GET /time-entries filtered by user_id and date range for the last fortnight, sum hours per jobId, and return the top 5 jobs by labour cost ### Customer and Site Lookup Use Fergus's substring search parameters such as filterSearchText to find customers, sites, or jobs without exact-match requirements. This supports natural-language agent queries like 'find the Smith job on Queen Street' against a corpus of thousands of records. Lookup endpoints include /customers, /sites, and /jobs with consistent filtering semantics. Example prompt: GET /customers?filterSearchText=Smith and return the top 5 matches with their associated sites ### AI Agent Job Status Updates Through Jentic, an agent can answer end-of-day questions like which jobs were finalised today and which quotes are awaiting customer acceptance. Jentic exposes Fergus's job, quote, and invoice operations as discoverable tools, letting a Claude or GPT agent generate daily summaries from natural-language requests. This removes the need for custom dashboards in small trades businesses. Example prompt: Search Jentic for 'list jobs', filter by updatedAt for today, and return a markdown summary grouped by status ## Key endpoints | Method | Path | Description | | --- | --- | --- | | GET | `/jobs` | List jobs | | POST | `/jobs` | Create a job | | PUT | `/jobs/{jobId}/finalise` | Finalise a job | | GET | `/jobs/{jobId}/phases` | List job phases | | GET | `/favourites` | List favourites | ## Key resources - **Jobs** — Create, update, and finalise trade-services jobs with phases - **Quotes** — Generate and manage quotes against jobs - **Customer Invoices** — Issue and track invoices to customers - **Customers** — Manage customer records linked to jobs and sites - **Sites** — Track service locations associated with customers - **Contacts** — Manage contact people at customer sites - **Time Entries** — Log staff hours against specific jobs - **Calendar Events** — Schedule site visits and team activities - **Pricebooks** — Maintain parts and labour pricing with tiered rates ## Why Jentic - **Setup:** Wiring the Fergus API by hand means choosing between Personal Access Token and OAuth2 auth, sending the bearer header, and threading job ids through 74 trades endpoints yourself. Through Jentic you install once, import the Fergus API from the API Directory, store the token once, and your agent calls it. - **Permission scoping:** Fergus puts the job id in the URL path (`/jobs/{jobId}/phases`, `/jobs/{jobId}/finalise`), so a rule can pin your agent to the jobs you allow. You choose the operations it may call, so a state change like finalising a job is not included unless you add it. - **Credential handling:** Your Fergus Personal Access Token or OAuth2 credentials are stored once, encrypted, by your own Jentic One instance and injected at execution time. The raw bearer token never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'create a job' or 'list job phases', and Jentic returns the matching Fergus operation with its input schema, so the agent calls the right endpoint without reading the developer docs. ## Related APIs - **FieldAware API** — Field service management platform with similar jobs and customer surface - **Invoice Ninja API** — Standalone invoicing platform that complements Fergus for accounting handoff - **Asana API** — Task management to coordinate office work tied to Fergus jobs ## FAQ ### What authentication does the Fergus API use? The Fergus API supports two methods: a Personal Access Token sent as a bearer token, and OAuth2 for delegated access. Through Jentic both methods are stored encrypted in your Jentic One instance and never enter agent context. ### What are the rate limits for the Fergus API? Fergus enforces 100 requests per minute per company, shared across all endpoints regardless of which token is used. Responses include x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset, and a retry-after header on 429s. ### Can I finalise a job through the Fergus API? Yes. Fergus exposes a dedicated PUT `/jobs/{jobId}/finalise` endpoint, separate from the generic update job call, so closing out a job is an explicit action with its own audit trail. ### How do I create a quote for a job through Jentic? Search Jentic for 'create job quote', load the POST `/jobs/{jobId}/quotes` schema, and execute with the line items. Run pip install jentic and from jentic import Jentic to get started. ### Does the Fergus API support free-text search on lists? Yes. Many list endpoints accept filterSearchText and filterSectionName query parameters with substring matching across searchable fields, so agents can find records without exact-match IDs. ### Can the Fergus API track time logged against jobs? Yes. The /time-entries endpoints let you list, retrieve, and create entries linked to specific jobs and users, supporting payroll and job profitability workflows. ### Can I limit what my agent is allowed to do with the Fergus API? Yes. Because you run your own self-hosted Jentic One instance, your rules decide which Fergus operations and credentials the agent may use. Since Fergus puts the job id in the URL path, such as `/jobs/{jobId}/phases` and `/jobs/{jobId}/finalise`, you can pin the agent to the jobs you allow. You also choose the operations it may call, so a state change like finalising a job through PUT `/jobs/{jobId}/finalise` is excluded unless you add it.