> ## Documentation Index
> Fetch the complete documentation index at: https://docs.portal.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Portal.io API Documentation

> Programmatic access to proposals, contacts, catalog, and webhooks for AV, security, and IT/MSP integrators.

Portal.io is proposal and business management software for AV, security, and IT/MSP integrators. The Portal.io API gives you programmatic access to your account — create and manage proposals, assign clients, add equipment from your catalog, trigger the AI proposal builder, and subscribe to webhook events, all via HTTP requests authenticated with HMAC-SHA256 signatures.

<CardGroup cols={2}>
  <Card title="Quick Start" icon="rocket" href="/quickstart">
    Get your sandbox credentials and make your first API call in minutes.
  </Card>

  <Card title="Authentication" icon="key" href="/authentication/overview">
    Learn how to obtain a User API Key and sign every request correctly.
  </Card>

  <Card title="Proposals" icon="file-lines" href="/concepts/proposals">
    Understand how proposals, areas, options, and change orders fit together.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/authentication/exchange-api-key">
    Full endpoint reference with request and response schemas.
  </Card>
</CardGroup>

## What you can do with the Portal.io API

The API gives you programmatic access to the core workflows you already perform in Portal.io:

* **Proposals** — create, retrieve, update, and manage the full proposal lifecycle
* **Contacts** — look up and manage the clients associated with your account
* **Catalog** — search and retrieve product and service items from your Portal.io catalog
* **Webhooks** — receive real-time event notifications when proposal or contact state changes
* **AI Builder** — upload source content and let Portal.io's AI generate proposal outlines and builds

## Environments

Portal.io provides two isolated environments. All development and testing happens in the sandbox. Production access requires a separate approval step.

| Environment | Base URL                        |
| ----------- | ------------------------------- |
| Sandbox     | `https://sandbox.api.portal.io` |
| Production  | `https://api.portal.io`         |

## Credentials

Every request to the Portal.io API requires three credentials:

* **API Application Key** (`X-MSS-API-APPID`) — identifies your integration. Provided by your Portal.io representative.
* **Secret Key** — used to compute the HMAC-SHA256 signature on each request. Also provided by your Portal.io representative. Never expose this value publicly.
* **User API Key** (`X-MSS-API-USERKEY`) — a per-user token you obtain by exchanging your Portal.io username and password via the authentication endpoint. You include this on all authenticated requests after the initial exchange.

## How to get started

<Steps>
  <Step title="Create a sandbox account">
    Sign up for a free sandbox account at [sandbox.portal.io](https://sandbox.portal.io). This gives you a dealer test account to exchange test data without affecting production. Verify your email address before proceeding.
  </Step>

  <Step title="Get your API credentials">
    Contact your Portal.io representative to receive an **API Application Key** and a **Secret Key**. These are required to sign every request.
  </Step>

  <Step title="Exchange your credentials for a User Key">
    Call `GET /authenticate/apikeyexchange` with your Portal.io username, password, and HMAC headers. The response includes a `meta.apiKey` that you attach to all subsequent requests. See the [quickstart](/quickstart) for a full walkthrough with curl examples.
  </Step>

  <Step title="Start making requests">
    Use the User Key in the `X-MSS-API-USERKEY` header and sign each request with your Secret Key. Hit the sandbox base URL `https://sandbox.api.portal.io` until your integration is approved for production.
  </Step>
</Steps>

## Getting production access

<Note>
  Production access is not automatic. You must complete your integration in the sandbox and have it reviewed and approved by Portal.io before production keys are issued.
</Note>

Once your integration is complete and working in the sandbox, contact your Portal.io representative to initiate the production review. After your integration is approved, Portal.io will issue production credentials tied to `https://api.portal.io`.

For questions or help at any stage, email [support@portal.io](mailto:support@portal.io).