Quickstart

1. Create an API key

Go to Settings > API Keys in your Propal dashboard and click Create API Key.

Give it a descriptive name (e.g., “My CRM Integration”)
Select the permissions (scopes) it needs
Click Create Key

Copy your API key immediately. It is only shown once. Store it in environment variables or a secrets manager.

2. List your proposals

Test your key by listing your proposals:

curl https://api.propal.io/v1/proposals \
  -H "Authorization: Bearer pp_live_YOUR_API_KEY"

const response = await fetch("https://api.propal.io/v1/proposals", {
  headers: {
    Authorization: "Bearer pp_live_YOUR_API_KEY",
  },
});

const { data, pagination } = await response.json();
console.log(`Found ${pagination.total_count} proposals`);

import requests

response = requests.get(
    "https://api.propal.io/v1/proposals",
    headers={"Authorization": "Bearer pp_live_YOUR_API_KEY"},
)

data = response.json()
print(f"Found {data['pagination']['total_count']} proposals")

Expected response:

{
  "data": [
    {
      "proposal_id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "Website Redesign Proposal",
      "deal_status": "pending",
      "page_status": "draft",
      "lead_name": "Acme Corp",
      "proposal_created_at": "2026-04-01T10:30:00.000Z"
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": null,
    "total_count": 1
  }
}

3. Create a proposal

Create a proposal from one of your templates:

curl -X POST https://api.propal.io/v1/proposals \
  -H "Authorization: Bearer pp_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "YOUR_TEMPLATE_ID",
    "title": "Q2 Partnership Proposal",
    "slug": "q2-partnership-2026",
    "lead_id": "YOUR_LEAD_ID",
    "language": "en",
    "settings": {
      "allow_client_to_sign": true,
      "allow_payment": true
    }
  }'

const response = await fetch("https://api.propal.io/v1/proposals", {
  method: "POST",
  headers: {
    Authorization: "Bearer pp_live_YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    template_id: "YOUR_TEMPLATE_ID",
    title: "Q2 Partnership Proposal",
    slug: "q2-partnership-2026",
    lead_id: "YOUR_LEAD_ID",
    language: "en",
    settings: {
      allow_client_to_sign: true,
      allow_payment: true,
    },
  }),
});

const proposal = await response.json();
console.log(`Created proposal: ${proposal.id}`);

Omit template_id to create a blank proposal with an empty editor.

4. Publish the proposal

Once your proposal is ready, publish it to make it accessible to your client:

curl -X POST https://api.propal.io/v1/proposals/PROPOSAL_ID/publish \
  -H "Authorization: Bearer pp_live_YOUR_API_KEY"

Your proposal is now live and accessible to your client.

5. Upload a file (optional)

File uploads use a two-step signed URL flow — the file never transits through the API server, so there’s no size limit.

# Step 1: Request a signed upload URL
curl -X POST https://api.propal.io/v1/media/files \
  -H "Authorization: Bearer pp_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "hero.png", "content_type": "image/png"}'

The response includes an uploadUrl:

{
  "id": "a1b2c3d4-...",
  "name": "hero.png",
  "path": "org_id/uuid.png",
  "uploadUrl": "https://xxx.supabase.co/storage/v1/object/upload/sign/..."
}

# Step 2: Upload the file directly to the signed URL
curl -X PUT "UPLOAD_URL_FROM_STEP_1" \
  -H "Content-Type: image/png" \
  --data-binary @hero.png

The signed URL is valid for 1 hour. The file record is created in Propal immediately in step 1 — step 2 uploads the actual binary to storage.

Next steps

Authentication

API key scopes and security best practices.

Pagination

Cursor-based pagination for listing resources.

Error handling

Handle errors gracefully in your integration.

Create from CRM

Full guide: create proposals from your CRM pipeline.

Overview

Guides

Endpoints

1. Create an API key

2. List your proposals

3. Create a proposal

4. Publish the proposal

5. Upload a file (optional)

Next steps

Authentication

Pagination

Error handling

Create from CRM

​1. Create an API key

​2. List your proposals

​3. Create a proposal

​4. Publish the proposal

​5. Upload a file (optional)

​Next steps

Authentication

Pagination

Error handling

Create from CRM

1. Create an API key

2. List your proposals

3. Create a proposal

4. Publish the proposal

5. Upload a file (optional)

Next steps