API Quickstart

This guide walks through the same flow as the Quickstart — build a template, generate narrated slides, and send a homeowner their personalized presentation link — but entirely over the REST API. Use it as the starting point for integrating AI Presentations into your own CRM, lead platform, or backend.

The dashboard calls them Templates, but the API uses the original term deck. A deck in the API is the same thing as a template in the UI. A presentation is a personalized instance of a deck, created for one homeowner.

Before you start

Your organization must be provisioned in AI Presentations. If you’re not sure, contact your Demand IQ account manager.
You’ll need dashboard login credentials — the API authenticates with a session cookie.
All requests go to the production base URL: https://presentations.demand-iq.com

Step 1: Authenticate

Deck and presentation endpoints authenticate with a session cookie obtained from POST /api/auth/login. Log in once and store the cookie — the examples below use a curl cookie jar (-b cookies.txt) to send it on every request:

curl -c cookies.txt -X POST https://presentations.demand-iq.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@yourcompany.com",
    "password": "••••••••"
  }'

A 401 Unauthorized on any later request means the session has expired — log in again to refresh the cookie.

Step 2: Create a deck

A deck holds your slides, narration, FAQs, and branding. Create one with a name and a deckContext — background about the audience and purpose that guides the AI narration, so the more specific the better. Set "type": "image-based" — the AI generation endpoint in the next step only works on image-based decks and returns a 400 for the default structured type:

curl -b cookies.txt -X POST https://presentations.demand-iq.com/api/decks \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Spring Solar Pitch",
    "type": "image-based",
    "deckContext": "Residential solar for storm-damage leads. Audience: homeowners aged 40-65 in the Southeast US."
  }'

The response includes the new deck:

{
  "deck": {
    "id": "3f6f2c1e-8a4b-4b6e-9f2d-1c5a7e9b0d42",
    "name": "Spring Solar Pitch",
    "type": "image-based",
    "isActive": true,
    "createdBy": "a1b4c8d2-6e3f-4f7a-9c0b-5d2e8f1a3b6c",
    "createdAt": "2026-07-06T17:04:00.000Z",
    "updatedAt": "2026-07-06T17:04:00.000Z"
  }
}

Save the id — it’s the {deckId} used in every request that follows.

Already have your deck as a PowerPoint file? POST /api/decks/import?source=pptx creates the deck and its slides from a .pptx file in one call, using each slide’s speaker notes as its narration script. It replaces steps 2 and 3 — see Import a PowerPoint presentation.

Step 3: Generate slides from your images

Send your slide images to the generate endpoint as multipart/form-data. AI Presentations runs each image through vision analysis, writes a narration script, and synthesizes spoken audio. Images are processed in the order you attach them, and each must be PNG, JPG, or WebP under 10 MB:

curl -b cookies.txt -X POST \
  https://presentations.demand-iq.com/api/decks/{deckId}/generate \
  -F "images=@slide-01.png" \
  -F "images=@slide-02.png" \
  -F "images=@slide-03.png"

Generation runs in the background — the endpoint returns immediately with a job ID:

{
  "jobId": "9b1d4e7a-2c3f-4a5b-8d6e-0f1a2b3c4d5e",
  "status": "started",
  "totalSlides": 3
}

Poll the status endpoint until status is completed. Generation usually takes under a minute:

curl -b cookies.txt \
  https://presentations.demand-iq.com/api/decks/{deckId}/generate/status

{
  "jobId": "9b1d4e7a-2c3f-4a5b-8d6e-0f1a2b3c4d5e",
  "status": "processing",
  "currentSlide": 2,
  "totalSlides": 3,
  "progress": 33,
  "error": null,
  "slidesCreated": 1,
  "faqsCreated": 0,
  "createdAt": "2026-07-06T17:05:00.000Z",
  "completedAt": null
}

progress counts only finished slides, so it shows 33 while slide 2 of 3 is still generating. A completed or failed job always reports 100. slidesCreated and faqsCreated report how many slide and FAQ rows exist right now. If you render slides as they land, refresh on these counts rather than currentSlide — currentSlide marks when a slide starts, so its content isn’t readable until a full slide’s work later. FAQs are written in one batch after the last slide, so faqsCreated stays 0 until near the end. To watch every deck in your organization with one request instead of polling each deck, call GET /api/decks/generation-status. It returns the latest unsettled job per deck, keyed by deck ID; a deck absent from the map has nothing running. If status comes back failed, the error field explains why. To review or tweak what was generated, list the slides with GET /api/decks/{deckId}/slides and edit scripts with PUT /api/slides/{slideId}.

Step 4: Set up branding (recommended)

Branding controls the colors and logo homeowners see throughout the presentation. palette and cta are required by the schema; the cta block ships alongside the branding record but is not what drives the main action button — that label is resolved from the deck’s action config (see Deck types and the action-configs endpoints in Contracts):

curl -b cookies.txt -X PUT \
  https://presentations.demand-iq.com/api/decks/{deckId}/branding \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Solar",
    "palette": {
      "primary": "#1a73e8",
      "primaryLight": "#4a9af5",
      "accent": "#fbbc04",
      "neutral": "#5f6368",
      "text": "#202124"
    },
    "cta": {
      "headline": "Ready to go solar?",
      "body": "Lock in your quote before the spring rush.",
      "buttonText": "Get My Quote",
      "buttonUrl": "https://acmesolar.example.com/quote"
    }
  }'

To add a logo or rep avatar, upload the image first with POST /api/images/upload (multipart, file field; JPG, PNG, WebP, or SVG up to 10 MB) and pass the returned S3 key as logo or avatar. Deleting an image with DELETE /api/images/{imageId} returns 409 Conflict while any deck or presentation still references it, along with a list of where it’s used. Clear those references first. You can also seed the live Q&A with your own answers — AI Presentations matches these during the presentation and responds with your exact wording:

curl -b cookies.txt -X POST \
  https://presentations.demand-iq.com/api/decks/{deckId}/faqs \
  -H "Content-Type: application/json" \
  -d '{
    "userQuestion": "How long does installation take?",
    "cannedAnswer": "Most installations are completed in a single day once permits are approved."
  }'

Step 5: Create and send a presentation

Create a personalized presentation for the homeowner. Provide a homeowner object (creates a new Core prospect from those details), an existing prospect_id (reuses a Core prospect’s contact and roof data), or both (attaches the existing prospect but uses the homeowner fields you send as-is for personalization). At least one of the two is required. For the homeowner path, first_name, address, city, and country are required; the address is validated via Google Geocoding, so a 422 with code INVALID_ADDRESS means it couldn’t be resolved. A 422 with code PROSPECT_NOT_FOUND means the prospect_id isn’t visible to your credential, and a 401 with code CORE_AUTH_REJECTED means your session or API key doesn’t have the required Core prospect scopes. If the deck’s slides from Step 3 are still generating, the request is refused with a 409 and code DECK_GENERATING. A presentation is a permanent snapshot of the deck at creation time, so one taken mid-generation would be permanently missing slides. Wait for the status endpoint to report completed, then retry.

curl -b cookies.txt -X POST \
  https://presentations.demand-iq.com/api/decks/{deckId}/presentations \
  -H "Content-Type: application/json" \
  -d '{
    "homeowner": {
      "first_name": "Dana",
      "last_name": "Rivera",
      "address": "1234 Maple Street",
      "city": "Charlotte",
      "state": "NC",
      "zip": "28205",
      "country": "US",
      "email": "dana@example.com",
      "phone": "+1 704 555 0123"
    }
  }'

Or, to build the presentation from an existing Core prospect:

curl -b cookies.txt -X POST \
  https://presentations.demand-iq.com/api/decks/{deckId}/presentations \
  -H "Content-Type: application/json" \
  -d '{
    "prospect_id": "prospect_01H8XYZ..."
  }'

The shareable URL comes back immediately:

{
  "deck_presentation_id": "7c2e5f8b-1a4d-4e6f-9b3c-8d0e2f4a6b1c",
  "url": "https://presentations.demand-iq.com/p/7c2e5f8b-1a4d-4e6f-9b3c-8d0e2f4a6b1c",
  "status": "pending"
}

Personalized audio may still be rendering in the background. If you want to wait until everything is ready before sending the link, poll the presentation status — it moves through pending → generating → ready (with a phase field showing what’s happening while it generates):

curl https://presentations.demand-iq.com/api/presentations/{presentationId}/status

{
  "id": "7c2e5f8b-1a4d-4e6f-9b3c-8d0e2f4a6b1c",
  "status": "ready",
  "deck_id": "3f6f2c1e-8a4b-4b6e-9f2d-1c5a7e9b0d42",
  "created_at": "2026-07-06T17:10:00.000Z",
  "updated_at": "2026-07-06T17:11:30.000Z"
}

Once it’s ready, deliver the url to the homeowner however your platform sends messages — text, email, or straight from your CRM. When they open it, they’ll see your branded landing page with their name and address woven into the narration.

Fetching the OpenAPI spec

Every environment serves its own live OpenAPI 3.0 document at /presentations/openapi.json. The spec always matches the code the environment is running, so you can point client-side codegen (OpenAPI Generator, openapi-typescript, and similar tools) at it directly:

curl https://presentations.demand-iq.com/presentations/openapi.json

The route is public and cached for 5 minutes. The first entry in servers reflects the environment serving the request, so a curl against stage returns a spec whose servers[0] is the stage URL.

What’s next

API Reference — every endpoint in this guide, plus slides, Q&A settings, narration, voices, and activity, is documented in full in the sidebar
Setting up your first template — template library, duplication, and personalization tokens
Branding — full walkthrough of every branding option
FAQs — how to get the most out of the Q&A system

Overview

Guides

API Reference

Before you start

Step 1: Authenticate

Step 2: Create a deck

Step 3: Generate slides from your images

Step 4: Set up branding (recommended)

Step 5: Create and send a presentation

Fetching the OpenAPI spec

What’s next

​Before you start

​Step 1: Authenticate

​Step 2: Create a deck

​Step 3: Generate slides from your images

​Step 4: Set up branding (recommended)

​Step 5: Create and send a presentation

​Fetching the OpenAPI spec

​What’s next

Before you start

Step 1: Authenticate

Step 2: Create a deck

Step 3: Generate slides from your images

Step 4: Set up branding (recommended)

Step 5: Create and send a presentation

Fetching the OpenAPI spec

What’s next