# Zwivio Network API

This document describes the public Zwivio Network API. It is not the contractor Dispatch Network. It does not book work.

Last updated: 2026-10-09

## Separate questions

1. **Serviceability** asks whether Zwivio can currently accept the specified request under publication, intake, geographic, and operational rules. Serviceability is intake, market, geographic, and operational eligibility. It does not mean supply exists, and it does not describe contractor capacity.
2. **Fulfillability** asks whether dispatch-eligible network supply appears to exist for the structured request at evaluation time. Fulfillability is a point-in-time dispatch-eligible-supply signal. It is not an appointment slot, reservation, contractor selection, ETA, or assignment guarantee.
3. **Network Handoff** stores convenience details and returns a Zwivio-built path into the existing homeowner intake. The homeowner reviews and submits. Handoff does not create a service request and does not reserve a contractor. An earlier Fulfillability result can change before submission.
4. **Transaction and assignment** are a separate homeowner lifecycle. Creating a request and officially assigning a service business are not these Network operations.

## Current public Network operations

- `GET /public/network/v1/serviceability`
- `GET /public/network/v1/market-presence`
- `POST /public/network/v1/fulfillability`
- `POST /public/network/v1/handoffs`
- `GET /public/network/v1/handoffs/{handoffId}`

Canonical OpenAPI 3.0.2 document, relative Nest path:

`/public/network/v1/openapi.json`

Do not invent an API hostname. The website does not publish a second copy of that document.

Human explanation:

`/network`

Homeowner ZIP intake check:

`/availability`

## Serviceability

- ZIP discovery returns lanes when `service` and `requestType` are both omitted.
- Lane-specific mode requires both `service` and `requestType`.
- `zip` is required and must be exactly 5 digits.
- `dispatchSpecialtySlug` is optional. An invalid specialty is HTTP 400 with code `INVALID_DISPATCH_SPECIALTY`.
- Semantics: `INTAKE_AND_OPERATIONAL_COVERAGE`.
- Lane statuses: `OPEN`, `LIMITED`, `CLOSED`, `UNRECOGNIZED_ZIP`, `INTAKE_DISABLED`, `LANE_NOT_PUBLISHED`.
- Request types: `EMERGENCY`, `URGENT`, `SCHEDULED`, `QUOTE`.
- Malformed input is HTTP 400. Excess traffic is HTTP 429.

## Market presence

`GET /public/network/v1/market-presence` returns `schemaVersion: 1` and `semantics: PLATFORM_MARKET_PRESENCE`.

Each market has `stateCode` and `counties`. Each county has `countySlug` and `countyName`.

Platform Market Presence is the public operating footprint. It is not operational coverage, contractor availability, fulfillability, or assignment capacity.

## Fulfillability

`POST /public/network/v1/fulfillability` requires `zip`, `service`, `requestType`, and `buildingType`.

Optional fields: `dispatchSpecialtySlug`, `quotePreference`, `propertyScope`, `requiresInsuredBusiness`, `requiresLicensedBusiness`, `serviceWindowStartAt`, `serviceWindowEndAt`.

`quotePreference` is `FREE_ONLY` or `ANY`, and only for `QUOTE`. Service-window timestamps must be paired. Malformed input is HTTP 400.

The response uses `schemaVersion: 1` and `semantics: POINT_IN_TIME_DISPATCH_ELIGIBLE_SUPPLY`. Results are `FULFILLABLE`, `NOT_CURRENTLY_FULFILLABLE`, and `UNSERVICEABLE`.

The response does not identify contractors or report how many are eligible.

## Network Handoff

`POST /public/network/v1/handoffs` creates a temporary prefill artifact. It does not create a Lead or Offer, and it does not evaluate Serviceability or Fulfillability.

The caller does not choose the destination. Zwivio returns `handoffId`, `expiresAt`, and a relative `path` that stays on the homeowner get-help intake. Semantics are `HOMEOWNER_REVIEW_REQUIRED`.

At least one intake field is required. Accepted fields: `zip`, `service`, `requestType`, `dispatchSpecialtySlug`, `buildingType`, `propertyScope`, `quotePreference`, `quoteSize`, `requiresInsuredBusiness`, `requiresLicensedBusiness`, `serviceWindowStartAt`, `serviceWindowEndAt`, `issueDescription`, and `address` (`line1`, `line2`, `city`, `state`, `postalCode`).

`quotePreference` and `quoteSize` are accepted only when `requestType` is `QUOTE`. Service-window timestamps must be paired. `issueDescription` is at most 1200 characters.

Rejected fields include phone, email, homeowner name, verification, consent, fee acknowledgment, media, and any return or redirect URL.

`GET /public/network/v1/handoffs/{handoffId}` returns that prefill. Possession of the id is not homeowner authentication. Missing and expired ids are not found. The artifact lasts 24 hours and may be opened again while it remains.

Opening the path hydrates the existing homeowner intake. The homeowner can edit every field. Phone verification, consent, and fee acknowledgment still happen in that intake. The homeowner submits through the existing lead path.

## Not live

Do not represent these as live Network capabilities:

- autonomous AI booking
- external agent keys
- delegated consent
- MCP
- A2A
- webhooks
- agent lifecycle APIs

`POST /leads` remains the existing homeowner transaction path. It is not part of the Network OpenAPI document.