canonical: https://jentic.com/apis/jobbooker.ai/jobbooker

# JobBooker API

The JobBooker API hands JobBooker the leads and messages that arrive at a home-service business's lead sources and returns the replies it writes in the owner's voice. A lead event can be a new lead, a customer message, a message the business sent itself, or a shared phone number; JobBooker classifies it and either returns the reply directly or pushes it through a Reply Ready subscription. Automation tools subscribe REST hooks for the reply_ready and owner_alert events, list and remove those subscriptions, and pull sample payloads to build a flow before any real lead arrives. Yelp through Zapier is the first supported lead source.

## For AI agents

Send a home-service lead or customer message to JobBooker and get back the reply it writes, or subscribe a hook to receive replies and owner alerts. Covers lead events, REST hook subscriptions, and sample payloads.

## Scope

Does not handle calendar booking calls, payment collection, or contact record editing through this API. Use for handing lead events to JobBooker and receiving its replies and alerts only.

## Capabilities

- Hand JobBooker a lead event such as a new Yelp lead or a customer message, with fields like consumer_name, job_names, postal_code, and availability_dates, and receive the drafted reply
- Detect replayed new-lead events: JobBooker returns the earlier reply flagged with duplicate: true instead of answering twice
- Subscribe a REST hook to a hooks.zapier.com target_url for the reply_ready or owner_alert event
- List the business's hook subscriptions and unsubscribe one by its id or target_url
- Fetch sample reply or owner-alert payloads shaped like live hook deliveries to test a flow
- Confirm an API key works and read which business it belongs to

## Use cases

### Agent-Driven Lead Response via Jentic

An AI agent watching a home-service business's lead inbox forwards each new lead to the JobBooker lead event operation with the customer's name, requested job, postal code, and availability. Through Jentic the agent finds the operation by intent and calls it with the stored business key, then relays the reply JobBooker writes back to the lead source, so the lead gets an answer in the owner's voice without the agent drafting it.

Example prompt: Send a new-lead event with id, consumer_name 'Dana Ruiz', job_names ['Water heater repair'], and postal_code '94110' to JobBooker, then return the reply text it drafts

### Zapier Instant Triggers for Replies and Alerts

A Zapier integration subscribes a hooks.zapier.com target_url to the reply_ready event so drafted replies are pushed out as soon as they are ready, and to owner_alert so the business owner hears about leads that need attention. When the Zap is turned off, the hook is removed by its subscription id or target URL.

Example prompt: Subscribe a hooks.zapier.com target_url to the owner_alert event, list subscriptions to confirm it is active, and later unsubscribe it by its id

### Building and Testing a Lead Flow Before Go-Live

Before any real lead has arrived, an automation builder pulls sample payloads for reply_ready, or for owner_alert with the event query parameter, shaped exactly like live hook deliveries. That lets the downstream steps be mapped and tested, and a quick key check confirms which business the connection is for.

Example prompt: Verify the API key returns the expected business, then fetch the sample owner_alert payload and list the fields a downstream step should map

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/api/webhooks/zapier` | Process a lead event and get the reply |
| POST | `/api/zapier/hooks` | Subscribe a REST hook |
| GET | `/api/zapier/hooks` | List subscriptions |
| DELETE | `/api/zapier/hooks` | Unsubscribe a REST hook |
| GET | `/api/zapier/hooks/sample` | Get sample hook payloads |
| GET | `/api/zapier/me` | Test the API key |

## Key resources

- **Lead events** — New leads, customer messages, business-sent messages, and shared phone numbers handed to JobBooker for a reply.
- **Hook subscriptions** — REST hook subscriptions for the reply_ready and owner_alert events.
- **Sample payloads** — Representative hook payloads for building and testing a flow.

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 60 / 100
- **Maturity:** Foundational
- **Dimensions:**
  - Foundational Compliance: 64 / 100
  - Developer Experience & Jentic Compatibility: 62 / 100
  - AI-Readiness & Agent Experience: 45 / 100
  - Agent Usability: 94 / 100
  - Security: 50 / 100
  - AI Discoverability: 68 / 100
- **View full report:** https://jentic.com/apis/jobbooker.ai/jobbooker/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring JobBooker by hand means sending its `x-jobbooker-key` header, shaping lead events in the Yelp-through-Zapier format, and handling the two response paths: a reply in the body or a 202 when a Reply Ready hook takes over. Through Jentic you install once, import JobBooker from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** JobBooker carries the business, lead, and subscription details inside the request body, so rules bound which operations your agent may call, such as sending lead events or listing subscriptions, not which lead or hook. You choose the operations it may call, so changes like subscribing or unsubscribing hooks are not included unless you add them.
- **Credential handling:** Your JobBooker business key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'reply to a new lead' or 'subscribe to owner alerts', and Jentic returns the matching JobBooker operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Podium API** — Podium handles customer messaging and reviews for local businesses; JobBooker focuses on answering home-service leads in the owner's voice.
- **Yelp Business Search and Reviews API** — Yelp is JobBooker's first lead source; the Yelp API exposes business search and review data.
- **Zapier AI Actions API** — Zapier carries leads into JobBooker and receives its REST hook deliveries.
- **Calendly** — Calendly schedules appointments; JobBooker drafts the lead replies that lead up to a booking.

## FAQ

### What authentication does the JobBooker API use?

The JobBooker API authenticates with the business's API key sent in the `x-jobbooker-key` header, per its OpenAPI spec; the key is shown in the JobBooker dashboard under Settings, Connect, and the spec notes a ?key= query parameter is also accepted. The describe-endpoint call (GET `/api/webhooks/zapier`) is open and needs no key. Through Jentic the key is stored encrypted by your own Jentic One instance and injected at call time.

### Is there a JobBooker MCP server?

You don't need an MCP server to give your agent JobBooker. Jentic connects it directly from the API Directory: import it, store your business key once, and your agent can hand off leads and manage hook subscriptions. Operations are discovered on demand, so no extra server's tool definitions are loaded into your agent's context.

### Can I limit what my agent is allowed to do with the JobBooker API?

Yes. For example, write a rule that allows only the lead event operation and the subscription list, so an agent can forward leads and see which hooks exist but cannot subscribe or remove hooks. JobBooker carries the business and subscription details in the request body, so the rule bounds which operations the agent may call rather than which subscription, and every call is logged.

### What happens if the same lead is sent to JobBooker twice?

A new-lead event replayed for a lead that was already answered returns the earlier reply with duplicate: true, so the customer is not answered twice. If a Reply Ready subscription exists, the lead event call returns 202 with accepted: true and the reply arrives through the hook instead of in the response.

### What are the rate limits for the JobBooker API?

Per the JobBooker OpenAPI spec, the lead event operation is limited to 60 requests per minute per business, and subscribing a REST hook is limited to 30 per minute. The spec does not list limits for the other operations.

### How do I send a lead to JobBooker through Jentic?

Search Jentic for an intent like 'reply to a new home service lead', import JobBooker from the API Directory, and store your business key once. Your agent then calls POST `/api/webhooks/zapier` with the lead's id and details such as consumer_name and job_names, and reads the drafted reply from the response. To run it on your own infrastructure, install Jentic One from its GitHub repo.