> **Warning:** This Epic's description is managed as documentation and mirrors a file in the > website repository. Do not edit it directly. See [how we manage the roadmap](https://selorahomes.com/handbook/departments/product/roadmap-management/) > and propose all content changes via a Merge Request. [📝 Source](https://gitlab.com/selorahomes/products/selorahomes.com/-/blob/main/content/docs/roadmap/portalio-integration.md) {{< gitlab-epic >}} ## 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](https://docs.portal.io/): - **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).