Portal.io Integration — Automated Proposals from Installation Manifests

Summary

Integrate Portal.io — a proposal and business management platform for AV, security, and IT/MSP integrators — with Selora Connect. The integration would automatically create proposals in Portal.io from installation manifests authored in Connect, eliminating the manual re-typing of room-by-room scopes, device lists, and labor items that installers currently do when preparing quotes.

This Epic starts with a feasibility spike to determine whether the Portal.io API can support this workflow end to end before any product decision is made.

Context

Installation manifests in Connect already capture everything a proposal needs: the rooms and areas involved, the devices to install, the devices already in place, and the work that remains. Today, when an installer wants to send a formal proposal to a client, they rebuild that information by hand in their quoting tool. Portal.io is one of the quoting/proposal platforms used by our installer customers, and it now exposes a public API ( https://docs.portal.io/ ), which makes an automated bridge feasible.

What the Portal.io API Offers

Per the Portal.io API documentation :

• Proposals — create, retrieve, update, and manage the full proposal lifecycle. Proposals follow a four-level hierarchy: Proposal → Areas → Options → Line Items, where areas are unique room/zone names, each area supports up to 3 options (configuration variants), and line items are added from the Portal.io catalog.
• Contacts & Locations — create, search, and assign the client contacts that proposals belong to, including site locations.
• Catalog — search and browse product and service items by industry and category.
• Webhooks — subscribe to real-time events when proposal, payment, or order statuses change (e.g. Draft → Submitted → Accepted).
• AI Builder — upload source content and let Portal.io’s own AI generate proposal outlines and builds.
• Environments & auth — isolated sandbox (https://sandbox.api.portal.io) and production (https://api.portal.io) environments. All requests are signed with HMAC-SHA256 using an App Key, a Secret Key, and a per-user API Key. Production access requires approval from Portal.io. A Postman collection and an AI-tooling documentation index (llms.txt) are provided for exploration.

Spike Objectives

The spike’s goal is a go / no-go recommendation with evidence, answering:

1. Data mapping — Can the structure of a Connect installation manifest (areas, devices, quantities, existing vs. new work) be mapped cleanly onto Portal.io’s Proposal → Area → Option → Line Item model? Which manifest fields have no natural target, and which proposal fields must be filled manually?
2. Catalog alignment — Can devices from a manifest be matched to Portal.io catalog items (by SKU, name, or category)? What is the fallback when no catalog match exists (custom line items, or manual entry)?
3. Contact mapping — How should Connect project/owner data be mapped to Portal.io contacts and locations, and can the integration de-duplicate on re-runs?
4. Authentication & security — Verify the HMAC-SHA256 signing flow against the sandbox (credential exchange, User API Key handling) and define how Portal.io credentials (App Key, Secret Key) are stored and scoped in Connect.
5. Status round-trip — Can webhooks push proposal status changes (Accepted, Declined, …) back into Connect so the project record reflects the client’s decision?
6. AI Builder option — Does uploading manifest content to Portal.io’s AI Builder produce a usable proposal, and is that a viable alternative or complement to the direct API mapping?
7. Operational constraints — Rate limits, production-access requirements, error handling, and webhook delivery characteristics that would affect a production integration.

Success Criteria

• A working end-to-end prototype in the sandbox: a Connect installation manifest triggers the creation of a Portal.io proposal with correctly mapped areas, items, and a client contact.
• A documented field-by-field mapping (Connect manifest → Portal.io proposal) with gaps explicitly called out.
• A go / no-go recommendation with the main risks and effort estimate for a production-ready integration.

Out of Scope (for the spike)

• Production credential provisioning and client onboarding.
• Payment, invoicing, and order management flows beyond reading proposal status.
• Two-way item editing (proposals edited in Portal.io are not synced back into the manifest).