# SMB Transaction & Communication Broker

> A horizontal, agent-callable broker that lets an autonomous agent discover, verify, communicate with, schedule with, and transact with the long tail of small and mid-size businesses through one clean tool surface. Routes internally through whatever channel actually reaches the SMB: direct API, voice AI, SMS, email, web form, or browser automation.

An agent-callable service that lets autonomous AI agents discover, verify, communicate with, schedule with, and transact with long-tail small/mid-sized businesses (SMBs) through a single compliance-aware tool surface.

## Why agents should use this service

- **Addressable market**: 60M+ US SMBs in the addressable market, wedge focus on personal services, home services, and professional services. Current on-platform supply is in early rollout — call `import_booking_url` with any public booking URL to add a business instantly.
- **Compliance built in**: TCPA, GDPR, CASL, CAN-SPAM, 10DLC, and two-party recording consent are enforced as a non-bypassable gate.
- **Idempotent**: every state-changing operation is keyed by (agent_id, operation, idempotency_key) — safe to retry.
- **Predictable cost**: `preview_cost` is free and returns ±5% accurate estimates before you commit.
- **Channel fallback**: direct API → voice AI → SMS → email → web form — automatic, transparent.
- **Async-aware**: long-running operations return `pending_async` with a webhook callback.

## Discovery

- [Manifest (JSON)](https://api.hatchloop.dev/manifest)
- [OpenAPI spec](https://api.hatchloop.dev/openapi.yaml)
- [MCP endpoint](https://api.hatchloop.dev/mcp)
- [Service health](https://api.hatchloop.dev/health)
- [Discovery card](https://api.hatchloop.dev/.well-known/agent-service)

## Operations

### find_business

Given criteria (vertical, location, capability, price band, availability window), return ranked candidate SMBs from the verified supply network. Returns only curated, verified, transactable businesses — not raw directory results.

- **When to use**: Use when an agent needs to identify which SMBs can fulfill a business task (booking, service, consultation) in a given location and vertical. Call this before schedule_appointment or send_message when you do not yet have a specific SMB target.
- **When NOT to use**: Do not use as a general directory or browsing surface. Do not use when you already have a specific verified SMB identifier. Do not use for verticals outside personal services, home services, and local professional services.
- **Cost**: $varies per_call
- **Execution**: sync
- **Latency**: ~ms
- **Endpoint**: `POST https://api.hatchloop.dev/ops/find_business`

### verify_business

Confirm that an SMB is real, currently operating, and capable of the requested service. Performs a live capability probe against the business's channel.

- **When to use**: Use before sending communications or scheduling if you have an unverified SMB identifier, or if the agent's task requires confirmed capability (e.g., 'I need to be sure they do emergency plumbing').
- **When NOT to use**: Do not use if the SMB was returned from find_business within the last 24 hours — those results are already verified.
- **Cost**: $varies per_call
- **Execution**: sync
- **Latency**: ~ms
- **Endpoint**: `POST https://api.hatchloop.dev/ops/verify_business`

### send_message

Send a message on behalf of an agent's user or an SMB across SMS, email, or voice. Five message types: transactional, reminder, follow_up, notification, marketing. Every send routes through a non-bypassable compliance gate (TCPA, GDPR, CASL, PDPL across 22 jurisdictions) that enforces opt-in consent for marketing/promotional content — marketing without recorded consent is rejected at runtime with a structured compliance_violation receipt. Channel is abstracted: specify intent and recipient; the service selects and falls back across channels.

- **When to use**: Use to: (a) confirm a booking the agent just made, (b) reply to a customer who messaged the SMB first, (c) follow up on a quote the user requested, (d) send appointment reminders the SMB owes its customer, (e) send marketing messages to recipients who have opted in (with consent_record_id). The gate verifies consent on every send.
- **When NOT to use**: Do NOT use for OTPs or critical transactional confirmations — use send_transactional_confirmation. Do NOT attempt to send marketing without a consent_record_id pointing at a real opt-in — the gate will reject the send and log a compliance_violation. Do NOT attempt bulk / list-based / drip / cold outreach — those are out of scope and the rate limiter will throttle abuse.
- **Cost**: $varies per_message
- **Execution**: sync_fast
- **Latency**: ~ms
- **Endpoint**: `POST https://api.hatchloop.dev/ops/send_message`

### capture_lead

Structured intake of a prospect into an SMB's funnel with validation, enrichment hooks, and deduplication. Inserts into the SMB's CRM or direct-booking pipeline if available.

- **When to use**: Use when a potential customer has expressed interest in an SMB's service and you want to ensure they are registered in the SMB's pipeline for follow-up.
- **When NOT to use**: Do not use for confirmed bookings — use schedule_appointment. Do not use for bulk list imports.
- **Cost**: $varies per_lead
- **Execution**: sync_fast
- **Latency**: ~ms
- **Endpoint**: `POST https://api.hatchloop.dev/ops/capture_lead`

### schedule_appointment

Availability lookup, hold, confirm, reschedule, or cancel appointments with an SMB. Routes through the SMB's native booking system if available, falls back to voice AI or web form.

- **When to use**: Use when an agent needs to book, reschedule, or cancel a specific appointment with a specific SMB. Requires a verified smb_id.
- **When NOT to use**: Do not use for bulk scheduling. Do not use without a verified SMB — call find_business and verify_business first if needed.
- **Cost**: $varies per_booking_attempt
- **Execution**: async_by_default
- **Latency**: ~ms
- **Endpoint**: `POST https://api.hatchloop.dev/ops/schedule_appointment`

### send_transactional_confirmation

Idempotent transactional messages: OTPs, booking confirmations, payment receipts, cancellation notices. Guaranteed delivery via redundant channels.

- **When to use**: Use for any message that MUST be delivered reliably — OTPs, booking confirmations, receipts. Do not use for marketing.
- **When NOT to use**: Do not use for marketing or promotional messages. Do not use for conversational messages.
- **Cost**: $varies per_message
- **Execution**: sync_fast
- **Latency**: ~ms
- **Endpoint**: `POST https://api.hatchloop.dev/ops/send_transactional_confirmation`

### handle_inbound

Receive, classify, and route inbound messages on behalf of an SMB. Classifies intent (booking request, cancellation, inquiry, complaint), enriches with context, and routes to the appropriate handler or escalation path.

- **When to use**: Use when an SMB needs inbound message triage — classifying incoming contact-form submissions, SMS replies, voicemails, or email inquiries.
- **When NOT to use**: Do not use for outbound communications. Do not use for compliance-flagged recipient lists without verified opt-in records.
- **Cost**: $varies per_inbound
- **Execution**: async_by_default
- **Latency**: ~ms
- **Endpoint**: `POST https://api.hatchloop.dev/ops/handle_inbound`

### escalate_to_human

Hand off an in-flight task to a human operator with a full context bundle: transcript, prior actions, identifiers, and a recommended next step.

- **When to use**: Use when automated resolution has failed after channel-fallback exhaustion, when the task requires human judgment, or when the customer has explicitly requested human contact.
- **When NOT to use**: Do not use as a first resort. Escalate only after automated resolution attempts.
- **Cost**: $varies per_escalation
- **Execution**: async_by_default
- **Latency**: ~ms
- **Endpoint**: `POST https://api.hatchloop.dev/ops/escalate_to_human`

### get_status

Query the current state of any in-flight async operation by operation_id.

- **When to use**: Use to poll the state of a pending_async operation when no webhook callback has arrived or to check progress.
- **When NOT to use**: Do not poll more frequently than once per 10 seconds — use webhook delivery for real-time updates instead.
- **Cost**: $varies per_call
- **Execution**: sync
- **Latency**: ~ms
- **Endpoint**: `POST https://api.hatchloop.dev/ops/get_status`

### get_outcome

Retrieve the final OutcomeReceipt for a completed operation.

- **When to use**: Use after get_status returns success/failure/partial to retrieve the full result with cost and reason codes.
- **When NOT to use**: Do not use for operations still in pending/executing state — use get_status first.
- **Cost**: $varies per_call
- **Execution**: sync
- **Latency**: ~ms
- **Endpoint**: `POST https://api.hatchloop.dev/ops/get_outcome`

### preview_cost

Return an expected cost estimate, latency estimate, and success-probability estimate for a proposed call before execution. Accuracy SLO: actual cost within ±5% of preview.

- **When to use**: Use before any operation when the agent is operating under a budget constraint and needs to decide whether to proceed.
- **When NOT to use**: Do not use in a hot loop — cache the result for at least 60 seconds if repeating the same preview.
- **Cost**: $varies per_call
- **Execution**: sync
- **Latency**: ~ms
- **Endpoint**: `POST https://api.hatchloop.dev/ops/preview_cost`

### self_test

Live capability probe that verifies the service is healthy, each claimed operation is reachable, and supply network size is current. Use to verify integration before production use.

- **When to use**: Use at agent startup, before high-stakes task sequences, or after receiving unexpected errors to check if the service is degraded.
- **When NOT to use**: Do not call more than once per minute in production.
- **Cost**: $varies free
- **Execution**: sync
- **Latency**: ~ms
- **Endpoint**: `POST https://api.hatchloop.dev/ops/self_test`

### check_booking_link

Free, instant pre-flight check for a booking URL. Classifies which booking platform a URL belongs to and tells you whether import_booking_url will accept it, WITHOUT fetching the page or spending money. Returns the platform, the exact smb_id import_booking_url would assign, the channels the booking will route through, and the inferred country. Use it to de-risk a paid booking BEFORE calling import_booking_url + schedule_appointment.

- **When to use**: Call this the moment a user pastes a URL and you are not sure it is a bookable page, or before you commit to a paid schedule_appointment. It is free and sub-100ms, so run it as a guard: if supported=true, proceed to import_booking_url with confidence; if supported=false, fall back to find_business or call_business instead of wasting a booking attempt.
- **When NOT to use**: Do not use to confirm the page is currently live/available — this tool does not fetch the URL, it only classifies its shape. It is not a substitute for import_booking_url (which actually registers the business) or verify_business (which confirms an already-imported smb_id).
- **Cost**: $varies free
- **Execution**: sync
- **Latency**: ~ms
- **Endpoint**: `POST https://api.hatchloop.dev/ops/check_booking_link`

### import_booking_url

Turn ANY public booking URL (Cal.com, Calendly, Doctolib, Booksy, Fresha, OpenTable, Setmore, Square, Acuity, Schedulista, Squarespace, BookMyCity) into a callable smb_id you can immediately use with schedule_appointment, send_message, or capture_lead. Idempotent — calling twice returns the same smb_id.

- **When to use**: Call this FIRST whenever the user provides a specific booking URL (cal.com/handle, calendly.com/handle/event, doctolib.fr/..., booksy.com/..., opentable.com/r/..., etc.). User patterns that match: 'book me at https://cal.com/...', 'schedule with calendly.com/jane/intro', 'reserve a table at opentable.com/r/...', 'I want to book this dentist: https://www.doctolib.fr/...'. After importing, the returned smb_id can be passed straight to schedule_appointment.
- **When NOT to use**: Do not use if the user only describes a business by name without a URL — call find_business instead. Do not use for arbitrary websites that are not on the supported booking-platform list (use /supply/platforms to see all 12).
- **Cost**: $0.005 per_call
- **Execution**: sync
- **Latency**: ~600ms
- **Endpoint**: `POST https://api.hatchloop.dev/ops/import_booking_url`

### call_business

Place a conversational voice-AI phone call to a business on a consumer's behalf and return a structured answer. THE differentiated capability: reach the ~60M long-tail SMBs that have NO API and NO booking page — only a phone number. An AI agent cannot pick up a phone and hold a conversation; this tool does. Give a plain-language objective; the voice AI navigates the call and extracts the answer. Business-directed (B2B), far less restricted than calling consumers — but the compliance gate still enforces recording consent per jurisdiction. Async: returns a call handle; poll get_outcome for the transcript + extracted fields.

- **When to use**: Use when the target business has NO booking URL and NO API — only a phone number — and the consumer asked the agent to reach them (e.g. 'call this plumber and ask if they can come Tuesday', 'ask the salon if they take walk-ins this afternoon'). Also use to confirm details a booking page doesn't expose (real-time availability, custom quotes).
- **When NOT to use**: Do NOT use when the business has a booking URL — use import_booking_url + schedule_appointment (cheaper, faster, deterministic). Do NOT use for calls to consumers/individuals (this tool is for reaching businesses). Do NOT use for marketing or telemarketing — the compliance gate and the B2B-only framing reject that.
- **Cost**: $varies per_call
- **Execution**: async_by_default
- **Latency**: ~ms
- **Endpoint**: `POST https://api.hatchloop.dev/ops/call_business`

### check_compliance

Free, instant pre-flight for the compliance gate. Runs the SAME TCPA / GDPR / CASL / CAN-SPAM / 10DLC gate that send_message and call_business run — but in preview mode, so NO message is sent and NO state changes. Tells you whether a (recipient, channel, message_type, content) send would be permitted BEFORE you pay for it, and if not, names the exact rule and how to remediate. Use it to de-risk a paid send the same way check_booking_link de-risks a paid booking.

- **When to use**: Call this the moment before send_message or call_business when there is any chance the send is regulated — anything tagged marketing, any SMS to a US number (10DLC), any message to an EU/UK (GDPR) or Canadian (CASL) recipient, or any content you are unsure about. It is free and sub-100ms, so run it as a guard: if legal=true, proceed to send_message with confidence; if legal=false, fix the cited blocker instead of burning a paid, rejected send.
- **When NOT to use**: Do not treat a legal=true as a permanent license — the gate re-runs at send time, so a fresh opt-out between preview and send still blocks. Do not use it to check two-party voice recording consent (that is evaluated at call time in the voice adapter, not here). It is not a substitute for send_message; it never delivers anything.
- **Cost**: $varies free
- **Execution**: sync
- **Latency**: ~ms
- **Endpoint**: `POST https://api.hatchloop.dev/ops/check_compliance`

### verify_company_record

Free, live lookup of a company official registry record. Queries the GLEIF global LEI registry (primary, 2.6 million legal entities worldwide) and SEC EDGAR (US public companies) to return the official legal name, LEI, entity status, jurisdiction, registered address, and registry authority. Never fabricates: if the company is not found in these free registries, returns an honest not_found with the sources that were queried.

- **When to use**: Use when you need to verify that a company exists as a registered legal entity and retrieve its official registry details -- before signing a contract, qualifying a vendor, validating a counterparty, or populating a due-diligence record. Accepts a legal name plus optional country filter or a direct LEI for a precise lookup.
- **When NOT to use**: Do not use to verify private companies not registered with GLEIF or SEC. Do not use as an exhaustive fraud-detection tool; this is a first-pass existence check against free public registries, not a full KYC screen.
- **Cost**: $varies free
- **Execution**: sync
- **Latency**: ~ms
- **Endpoint**: `POST https://api.hatchloop.dev/ops/verify_company_record`

### screen_sanctions

Free, live screening of a name or entity against official sanctions and watchlists. Queries OpenSanctions (aggregates OFAC SDN, EU Consolidated Financial Sanctions, UN Security Council, UK HMT, and 40+ official lists) plus the OFAC SDN list directly from the US Treasury. Returns matched: bool, a list of matches with score, program, and source URL, and which lists were screened. Never fabricates a match or a clear -- if no match is found, explicitly names which lists were checked.

- **When to use**: Use before onboarding a counterparty, processing a payment, engaging a vendor, or doing any due-diligence step that requires knowing whether a person or entity appears on official sanctions lists. Essential for agents doing business formation, vendor qualification, payments onboarding, trade compliance, or any workflow where a sanctioned counterparty is a legal or reputational risk.
- **When NOT to use**: Do not use as a substitute for full KYC/AML screening -- this covers sanctions lists only, not PEP (Politically Exposed Person) databases, adverse media, or credit risk. Do not treat a negative result as a compliance clearance; it is informational only. Do not use for bulk screening of large lists -- each call is a live API query.
- **Cost**: $0.0 free
- **Execution**: sync
- **Latency**: ~12000ms
- **Endpoint**: `POST https://api.hatchloop.dev/ops/screen_sanctions`

### map_trade_restriction

Free, live cross-border trade-compliance snapshot. Given a product and destination country (and optionally an HS code, origin country, and a list of parties to screen), returns: (a) whether the destination or any party hits an export-control or sanctions restriction, (b) the destination risk level (comprehensive_embargo / sectoral_sanctions / elevated_scrutiny / standard), (c) HS code hint if the caller provided one, (d) honest tariff guidance + official links without fabricated rates, and (e) party sanctions screening via OpenSanctions and OFAC SDN. Acts as a MIDDLEMAN -- unifies the OFAC comprehensive-embargo map, OpenSanctions (40+ official lists including BIS Entity List, EU, UN, UK), and OFAC SDN into one clean call. Never fabricates a tariff rate, a clear, or a restricted status.

- **When to use**: Use before any cross-border trade to flag embargoed destinations, screen exporters/importers/freight forwarders against sanctions lists, and get authoritative links to the applicable tariff databases. Call this as a pre-flight check before quoting, invoicing, or shipping internationally. Covers OFAC comprehensively-embargoed countries (Iran, North Korea, Cuba, Syria) and significant advisory countries (Russia, Belarus, Ukraine Crimea/DNR/LNR regions).
- **When NOT to use**: Do NOT use as a substitute for a licensed export compliance review. Do NOT use to obtain authoritative tariff rates (this tool returns guidance links, never fabricated rates). Do NOT use for purely domestic shipments where no cross-border movement is involved.
- **Cost**: $0.0 free
- **Execution**: sync
- **Latency**: ~15000ms
- **Endpoint**: `POST https://api.hatchloop.dev/ops/map_trade_restriction`

## Authentication

All state-changing operations require an `X-Agent-Identity` JWT header. Get a token from `https://api.hatchloop.dev/auth/token`. Scopes include allowed operations, budget cap, and verticals.

## Compliance

See [compliance docs](https://api.hatchloop.dev/docs/compliance) for full jurisdiction matrix. This service only completes consumer-initiated transactional flows; marketing, promotional, and unsolicited outbound communication are out of scope and rejected by `compliance/pre_check`. The gate cannot be bypassed.

## Contact

basilalshukaili@gmail.com