The FieldEdge Open API for Contractors: Marketplace Credentials, Leads, Work Orders and Signed Webhooks

Member or partner: the first fork in FieldEdge's road

FieldEdge's developer portal recognizes two kinds of API user. Members are "Tenants that actively use FieldEdge to operate their business"; they build private, internal integrations, usually with their own technical help. Partners are companies that build public apps for many FieldEdge customers. A contractor connecting its own website is a member, and so is the developer it hires to do the work on its behalf.

The two paths differ in ways that matter to a budget. Partners create an OAuth app in the FieldEdge Marketplace, submit it for review and approval, and receive a sandbox tenant from FieldEdge's team. Members retrieve app credentials from the same Marketplace, and a member without a Marketplace account requests access through FieldEdge's onboarding form. The member guide describes no sandbox, so we do not promise one. FieldEdge's other API landing page, at docs.api.fieldedge.com, puts the emphasis on partners: "Providing API access to our integrated partners."

• Price. No FieldEdge page we read, including the pricing page, names a price or a plan requirement for API access, as of November 2026. Ask before you budget.
• Approval. Do not assume self-service. If your company has no Marketplace account yet, the onboarding form is the first step, and its timing is FieldEdge's.
• Help. API questions go to feintegrations@xplortechnologies.com, the address on FieldEdge's API Support and Rate Limits pages.

A token that lasts a working day, and secrets that stay on the server

Authentication is the OAuth client credentials flow. The server posts client_id, client_secret, target_id and grant_type=client_credentials to https://fieldedge.withgobo.com/oauth/token as a form-encoded body; the docs warn that "JSON request bodies are not supported," which is the first thing a developer gets wrong. The target_id is your tenant ID, visible in the FieldEdge web portal. The example response returns a Bearer token with expires_in of 28800 seconds, eight hours, sent on every call through FieldEdge's Azure API Management gateway.

Each operation names a scope, such as leads:write, customers:read, workorders:write and webhooks:write, so an app can be granted only what the website needs. The client secret is a password in all but name. On the sites we build it sits in the server's environment, the browser talks only to our server, and the token is cached and refreshed before it expires rather than fetched for every booking.

Thirteen things a website might ask, answered from the reference

FieldEdge's reference groups its operations as Lead, Customer (with attachments, notes and tags), WorkOrder, Assignments, Agreement, Invoice, Quote, Task, inventory items and warehouses, Employee, Company and Webhook. The production base URL is https://api.fieldedge.com/open-api. The table answers the questions contractors and their developers ask, as of November 2026.

Lead or work order: picking the door the website knocks on

FieldEdge offers a website two ways in, and choosing between them is the main design decision. A lead is light: one call, a free-text source (FieldEdge's examples are "trane, dispatch, customerportal"), the homeowner's preferred date, time and time zone, a service type and urgency, and a metaData object of key-value pairs, which is the natural home for a Google click ID and UTM tags captured by conversion tracking. A trackingId field exists "for idempotency or traceability," so a retried request can carry the same ID. The response gives a lead ID and a numeric status from 0 to 19 whose meanings the reference does not define.

A work order is heavy and exact. It requires a customer ID, a business unit ID, a lead source ID and a task ID, all looked up from your own FieldEdge lists, accepts notes that appear as the Work Summary, and leaves scheduling to a separate assignment call. The online booking page explains when a held slot is worth that weight. Note the gap: the lead's source is text while the work order's lead source is an ID, and FieldEdge does not say whether one maps to the other, so we confirm it with your office before reports depend on it.

Webhooks that sign every envelope

FieldEdge registers a webhook with POST /v1/webhook, an HTTPS callbackUrl and optional custom headers. Events cover work orders (created, scheduled, unscheduled, traveling, complete, canceled, backorder, finalized), invoices, customers, item categories, quote.pending, and a lead family running from lead.offered and lead.accepted through job.scheduled, job.completed and quote.accepted. The delete operation refers to "the registered webhook for the authenticated account," so plan on one endpoint that sorts events by type.

Two rules shape the listener. "Webhook events are notification-only": an event carries an identifier and a change type, and the server calls the matching GET operation for the details. And every delivery carries X-FieldEdge-Signature: sha256=<hex>, an HMAC-SHA256 of the body; FieldEdge's instruction is to "Validate this header to confirm the request originated from FieldEdge." The signing secret is returned once, at registration, and a separate operation rotates it. FieldEdge does not publish a retry schedule or an ordering guarantee, so our listeners answer fast, queue the event, and ignore an id they have already handled.

One thousand calls an hour, shared

FieldEdge's rate limit guide is short and unusually frank. It "limits each partner to 100 requests per minute and 1,000 requests per hour," and "Both limits apply at the same time." Going over the minute limit returns HTTP 429 with a Retry-After header. Going over the hour returns HTTP 403 with the reset time in the message and no Retry-After; "Do not retry in a loop: every attempt is rejected until the hour resets," which happens on the hour, UTC. The guide suggests one shared throttle and says about 15 requests a minute stays inside the hourly quota.

Do the arithmetic for a busy Saturday. A held-slot booking can take five calls: search the customer, create one if needed, create the work order, assign the technician, read it back. A nightly sync of work orders for a custom dashboard adds more. So we cache the lists that rarely change (lead sources, business units, tasks, employees), batch reporting reads overnight, give live bookings priority in the queue, and log every 429 and 403 in plain words. "A rejected request is not processed," FieldEdge notes, so a queued retry is safe.

Scoping a FieldEdge build in seven steps

This is the order we follow with a FieldEdge shop. It works as well if you hire someone else.

1. 1

   Ask FieldEdge about access

   Confirm whether your company has a Marketplace account, what API access costs on your plan, and how long onboarding takes. FieldEdge publishes none of these.

2. 2

   Create the member app and find the tenant ID

   An owner or admin sets up the internal app in the Marketplace, copies the client ID and secret, and reads the tenant ID from the FieldEdge web portal.

3. 3

   Choose lead, work order or both

   Decide per form and per service which door the website uses. Emergencies stay calls; planned work may hold slots.

4. 4

   Clean up the lists

   Make sure the lead sources, business units and tasks the site will use exist and are active in FieldEdge, since the API cannot add a lead source.

5. 5

   Write the field map

   Agree where each form answer goes, what goes in metaData, and how click IDs and tracked numbers are kept.

6. 6

   Plan the call budget

   Estimate calls per booking and per sync, and set the throttle below FieldEdge's hourly quota with room for the busiest day.

7. 7

   Register the webhook and test with labeled records

   Store the signing secret on the server, verify signatures from the first event, and agree test record names with the office.

The studio on the other end of the key, and its rates

We are a San Antonio web studio that builds custom Next.js sites and connects them to the systems contractors run. Our API integrations work follows the same habits everywhere: field map before code, server-side validation, idempotent writes, queues and retries, logs in sentences. The closest proof sits outside FieldEdge: HomeService WebApp pulls open estimates, customers and follow-ups onto one screen, and Bleuwave Electrical shows the page depth a trade site can carry. Neither is a FieldEdge integration.

A connection on your existing site starts at $575, depending on complexity, quoted after a free review; two systems typically go live the same day. New sites start at $1,500 and include one custom API integration; see web design pricing and 0% website financing, or start with a free site audit. The FieldEdge integration hub covers the whole connection, and contractors comparing platforms can read the ServiceTitan API guide, the Housecall Pro API or the Jobber API. For the site around the connection, see HVAC website design.