# Portal.io API

## Docs

- [Build a Proposal from an AI-Generated Outline](https://docs.portal.io/api-reference/ai-builder/build-proposal.md): POST /public/proposals/{ProposalId}/ai/build — Triggers an async AI proposal build from a completed outline. Returns proposalId and initial build status.
- [Delete AI Builder Content from a Proposal](https://docs.portal.io/api-reference/ai-builder/delete-content.md): DELETE /public/proposals/{ProposalId}/ai/content/{ContentId} — Removes an AI Builder content item from a proposal. Proposal must be in Draft status.
- [Generate an AI Outline for a Proposal](https://docs.portal.io/api-reference/ai-builder/generate-outline.md): POST .../ai/outline — Starts async AI outline generation from uploaded content. Returns proposalId and initial status. Requires transcribed content.
- [Get the AI-Generated Outline for a Proposal](https://docs.portal.io/api-reference/ai-builder/get-outline.md): GET .../ai/outline — Returns the AI-generated outline for a proposal. Status is Generating or Completed; the outline text is only present when Completed.
- [List AI Builder Content for a Proposal](https://docs.portal.io/api-reference/ai-builder/list-content.md): GET /public/proposals/{ProposalId}/ai/content — Returns all AI Builder content items attached to a proposal, including processing status and metadata.
- [Upload AI Builder Content to a Proposal](https://docs.portal.io/api-reference/ai-builder/upload-content.md): POST .../ai/content — Uploads files as AI source content for a proposal. Supports single and multi-chunk uploads. Returns the new content item record.
- [Exchange Credentials for a User API Key](https://docs.portal.io/api-reference/authentication/exchange-api-key.md): GET /authenticate/apikeyexchange — Trade your Portal.io username and password for a User API Key required for all subsequent HMAC-authenticated requests.
- [Get Catalog Item Details](https://docs.portal.io/api-reference/catalog/get-item.md): GET /public/catalog/{ItemId} — Returns a catalog item's details including pricing and supplier info. Pass ExtendedDetails=true for specs, PDFs, and videos.
- [List Catalog Categories](https://docs.portal.io/api-reference/catalog/list-categories.md): GET /public/catalog/categories — Returns the full catalog category hierarchy grouped by industry, including sub-categories and image URLs where available.
- [Search Catalog Items in Your Account](https://docs.portal.io/api-reference/catalog/search-items.md): GET /public/catalog — Search catalog items by text, category, brand, and stock status. Returns items with pricing, images, and category hierarchy.
- [Get Change Order Details](https://docs.portal.io/api-reference/change-orders/get-change-order.md): GET .../changeorders/{ChangeOrderId} — Returns full change order detail including financial summary, areas, line items, and customer info.
- [List Change Orders for a Proposal](https://docs.portal.io/api-reference/change-orders/list-change-orders.md): GET /public/proposals/{ProposalId}/changeorders — Returns all change orders for a proposal with status, totals, currency, and customer details.
- [Create a New Contact in Your Account](https://docs.portal.io/api-reference/people/create-contact.md): POST /public/people — Creates a contact. PartyType (Person/Company), ContactType (Client/Employee/Contractor/Other), and FirstName are required.
- [Add a Location to a Contact](https://docs.portal.io/api-reference/people/create-location.md): POST /public/people/{ContactId}/location — Adds an address to a contact. Street is required. When Country is provided, State is also required.
- [Get Contact Details by ID](https://docs.portal.io/api-reference/people/get-contact.md): GET /public/people/{PersonId} — Returns full contact details including primary/billing locations and optional proposal and payment counts.
- [Search and List Contacts in Your Account](https://docs.portal.io/api-reference/people/list-contacts.md): GET /public/people — Returns a paged list of contacts. Filter by search text or contact type; sort results; defaults to page 1, size 10.
- [List Locations for a Contact](https://docs.portal.io/api-reference/people/list-locations.md): GET /public/people/{ContactId}/location — Returns paged locations for a contact, ordered: primary first, then billing, then most recently modified.
- [Add an Area to a Proposal](https://docs.portal.io/api-reference/proposals/add-area.md): POST /public/proposals/{ProposalId}/area — Creates a named area (room) in a proposal. Auto-creates a default Draft option. Returns full proposal detail.
- [Add an Option to a Proposal Area](https://docs.portal.io/api-reference/proposals/add-area-option.md): POST .../area/{AreaId}/option — Adds a Draft option to a proposal area. Max 3 options per area. Accepts an optional client description and installer notes.
- [Assign a Contact to a Proposal](https://docs.portal.io/api-reference/proposals/assign-contact.md): POST /public/proposals/{ProposalId}/contact/{ContactId} — Links a contact to a proposal. May auto-assign location and trigger tax recalculations.
- [Assign a Location to a Proposal](https://docs.portal.io/api-reference/proposals/assign-location.md): POST /public/proposals/{ProposalId}/location/{LocationId} — Assigns a location to a proposal and triggers tax recalculation. Returns the updated proposal.
- [Create a New Proposal](https://docs.portal.io/api-reference/proposals/create-proposal.md): POST /public/proposals — Creates a new proposal. Requires a SalesPersonId; name is optional. Returns full proposal detail including the financial summary.
- [Get Proposal Details](https://docs.portal.io/api-reference/proposals/get-proposal.md): GET /public/proposals/{ProposalId} — Returns full proposal detail with areas, options, financial summary, and customer info. Sets the Last-Modified header.
- [List and Search Proposals](https://docs.portal.io/api-reference/proposals/list-proposals.md): GET /public/proposals — Returns all proposals for the account with filtering by status, contact, date, and text search. Supports sorting and pagination.
- [Update an Area Option's Client Description](https://docs.portal.io/api-reference/proposals/update-area-client-description.md): POST .../area-options/{AreaOptionId}/clientdescription — Sets the customer-facing description for an area option. Returns the full updated proposal detail.
- [Update an Area Option's Installer Notes](https://docs.portal.io/api-reference/proposals/update-area-installer-notes.md): POST /public/proposals/{ProposalId}/area-options/{AreaOptionId}/installernotes — Sets internal installer notes for an area option. Not shown to customers.
- [Update Proposal Client-Facing Description](https://docs.portal.io/api-reference/proposals/update-description.md): POST /public/proposals/{ProposalId}/description — Updates the client-facing project description shown on customer documents. Returns the updated proposal.
- [Update Proposal Internal Notes](https://docs.portal.io/api-reference/proposals/update-internal-notes.md): POST /public/proposals/{ProposalId}/internalnotes — Sets internal installer notes visible only to the dealer's team. Not shown on client-facing documents.
- [Update a Proposal's Name or Salesperson](https://docs.portal.io/api-reference/proposals/update-proposal.md): POST /public/proposals/{ProposalId} — Updates a proposal's name and/or salesperson. Omitted fields keep current values. Returns the full updated proposal.
- [List Users in Your Account](https://docs.portal.io/api-reference/users/list-users.md): GET /public/users — Returns all active users in your dealer account with id, name, email, and permission group. Use to look up SalesPersonId for proposals.
- [Create a Webhook Subscription](https://docs.portal.io/api-reference/webhooks/create-subscription.md): POST /public/webhook/subscribe — Registers a new webhook endpoint for one or more event types. Returns the subscription ID and signing secret key.
- [Delete a Webhook Subscription](https://docs.portal.io/api-reference/webhooks/delete-subscription.md): DELETE /public/webhook/unsubscribe/{SubscriptionId} — Permanently removes a webhook subscription and stops all future event deliveries to its endpoint.
- [Portal.io API Webhook Event Reference](https://docs.portal.io/api-reference/webhooks/events.md): Complete reference for Portal.io API webhook event types, including proposal status changes, AI build status updates, and AI outline generation events.
- [List Your Webhook Subscriptions](https://docs.portal.io/api-reference/webhooks/list-subscriptions.md): GET /public/webhook/subscriptions — Returns all active webhook subscriptions for your account, including URL, events, and enabled status.
- [Update a Webhook Subscription](https://docs.portal.io/api-reference/webhooks/update-subscription.md): POST .../webhook/subscription/{SubscriptionId} — Partially updates a webhook subscription. Only supplied fields change; omitted fields keep current values.
- [Zapier Trigger: Change Order Status Change](https://docs.portal.io/api-reference/zapier-triggers/change-order-status-change.md): Zapier trigger that fires when a change order's status changes in Portal.io.
- [Zapier Trigger: Order Status Change](https://docs.portal.io/api-reference/zapier-triggers/order-status-change.md): Zapier trigger that fires when an order's status changes in Portal.io.
- [Zapier Trigger: Payment Status Change](https://docs.portal.io/api-reference/zapier-triggers/payment-status-change.md): Zapier trigger that fires when a payment's status changes in Portal.io.
- [Zapier Trigger: Person Modification](https://docs.portal.io/api-reference/zapier-triggers/person-modification.md): Zapier trigger that fires when a contact record is created, updated, or deleted in Portal.io.
- [Zapier Trigger: Proposal Status Change](https://docs.portal.io/api-reference/zapier-triggers/proposal-status-change.md): Zapier trigger that fires when a proposal's status changes in Portal.io.
- [Authenticate with the Portal.io API](https://docs.portal.io/authentication/overview.md): Portal.io API uses HMAC-SHA256 request signing. Learn how to get your API credentials, exchange them for a User Key, and include auth headers on every request.
- [Sign Portal.io API Requests with HMAC-SHA256](https://docs.portal.io/authentication/signing-requests.md): Step-by-step guide to building the canonical message and computing the HMAC-SHA256 signature required on every Portal.io API request.
- [Changelog](https://docs.portal.io/changelog.md): A record of additions, changes, and fixes to the Portal.io API. Check here to see what's new and whether your integration needs updating.
- [Understanding the Portal.io Catalog](https://docs.portal.io/concepts/catalog.md): Learn how the Portal.io catalog is organized into industries, categories, and items, and how to use the API to search, browse, and retrieve product data.
- [Managing Contacts and Locations in Portal.io](https://docs.portal.io/concepts/contacts.md): Portal.io contacts represent the clients and companies in your account. Learn how to create, search, and assign contacts and locations to proposals.
- [Understanding Proposals in the Portal.io API](https://docs.portal.io/concepts/proposals.md): Learn how Portal.io proposals are structured with areas, options, and change orders, and how to use the API to build and manage them.
- [Portal.io API Webhooks: Real-Time Event Notifications](https://docs.portal.io/concepts/webhooks.md): Subscribe to Portal.io webhook events to receive real-time HTTP POST notifications when proposals, payments, and orders change status in your account.
- [Integration Field Matrix](https://docs.portal.io/field-matrix.md): Downloadable spreadsheet listing every field in the Portal.io API — use it to plan your integration mapping.
- [Explore with Postman](https://docs.portal.io/postman.md): Use the Portal.io API Postman collection to explore endpoints, test requests, and debug your integration without writing code.
- [Get Started with the Portal.io API](https://docs.portal.io/quickstart.md): Learn how to set up your sandbox account, obtain credentials, authenticate, and make your first Portal.io API request in five steps.
- [Error Handling & Troubleshooting](https://docs.portal.io/troubleshooting.md): Understand Portal.io API error codes, diagnose common authentication issues, and resolve the most frequent integration problems.