Get a Presentation URL via API

This guide shows the fastest way to turn a lead into a personalized presentation link:

Prospect ID or prospect details  →  Create Presentation API  →  Link for that prospect

You send AI Presentations a Demand IQ prospect ID (when the lead already exists in Demand IQ), the prospect’s details (name, address, contact info), or both, and you get back a shareable URL. Open that URL and the prospect sees your branded, narrated presentation — personalized with their name and address. It’s written for two audiences:

Developers integrating AI Presentations into a CRM, lead platform, or backend — follow the numbered steps with the curl examples.
Non-technical users automating with Zapier — read How it works and Key terms, then jump to the Zapier walkthrough, which spells out every field to fill in.

This guide assumes you already have a template with slides. If you don’t yet, build one in the dashboard first (Quickstart) or over the API (API Quickstart).

How it works

Creating a presentation is one API call to one endpoint — POST /api/decks/{deckId}/presentations. What you send in the body depends on where your lead lives:

You have…	Send
Lead details in your CRM, a form, or a spreadsheet	A `homeowner` object with their name, address, and contact info
A prospect that already exists in Demand IQ (e.g. from your Journeys funnel)	Their Demand IQ `prospect_id`
Both — an existing prospect, but you want the presentation to use your own contact fields	`prospect_id` and `homeowner`. The prospect is attached; the `homeowner` fields you send are used as-is

At least one of the two must be present — sending neither returns a 400 (“Provide homeowner or prospect_id”). The request returns a presentation URL immediately. The link is live as soon as you get it — narration audio may still be rendering in the background for a short while, and you can check on that if you want to wait until everything is ready.

How this relates to prospects in Demand IQ. Every presentation is linked to a Demand IQ prospect record. Send prospect_id alone and AI Presentations personalizes the presentation from that existing prospect’s contact info. Send homeowner details alone and AI Presentations creates a new prospect record in Demand IQ for you as part of the same call. Send both and AI Presentations attaches the existing prospect to the presentation but takes the homeowner fields you send as authoritative.

What you’ll need

A AI Presentations account. Your organization must be provisioned — if you’re not sure, ask your Demand IQ account manager.
An API key, generated from the dashboard. Covered in Step 1.
A template with slides. Presentations are created from a template (the API calls it a deck). The template must have at least one slide. Creating a presentation from an empty template returns a 400 (“Deck has no slides”). If the template’s slides are still being generated, the request returns a 409 with code DECK_GENERATING instead — a presentation is a permanent snapshot of the template at creation time, so one taken mid-generation would be permanently missing slides. Retry once generation completes.
Your template’s deck ID. Covered in Step 2.

All presentation API requests go to the production base URL:

https://presentations.demand-iq.com

Step 1: Generate an API key

API keys are generated in the Demand IQ dashboard, not created over the API:

Log in at app.demand-iq.com and go to Settings → Company → API Keys (/company/settings/apiKeys).
Click Add New API Key.
Choose what you’ll use it for. None of the presets are specifically about presentations, so pick Custom. AI Presentations forwards your API key to Demand IQ to look up or create the prospect on your behalf, so your key needs the underlying prospect permissions. Check Write Prospects if you’ll send prospect details (a new Demand IQ prospect gets created for the presentation). Check Read Prospects if you’ll send an existing prospect_id or use both fields together. If you’ll use both paths interchangeably, check both. A 401 with code CORE_AUTH_REJECTED at request time means one of these scopes is missing (or the credential expired).
Give it a name (e.g. “Zapier — presentation links”) and confirm the expiration date. Keys default to expiring two years out; pick sooner if you’d rather rotate more often.
Click Create, then copy the key immediately — it’s shown only once and can’t be retrieved again later.

Send that key on every presentation API request as a header:

Authorization: Bearer <your-api-key>

Step 2: Find your deck ID

Every request that creates a presentation names the template — the deck — it’s created from. Two ways to find its ID: From the dashboard: open your template in the editor and copy the ID from the browser’s address bar:

https://presentations.demand-iq.com/templates/3f6f2c1e-8a4b-4b6e-9f2d-1c5a7e9b0d42/edit
                                              └──────────── this is the deck ID ───────┘

From the API: list your decks and pick by name:

curl https://presentations.demand-iq.com/api/decks \
  -H "Authorization: Bearer $API_KEY"

{
  "decks": [
    {
      "id": "3f6f2c1e-8a4b-4b6e-9f2d-1c5a7e9b0d42",
      "name": "Spring Solar Pitch",
      "isActive": true
    }
  ]
}

Step 3: Create the presentation

Send homeowner, prospect_id, or both to the same endpoint. Sending neither returns a 400 (“Provide homeowner or prospect_id”). If the lead’s details live in your CRM, a web form, a spreadsheet — anywhere outside Demand IQ — send them in a homeowner object:

curl -X POST \
  https://presentations.demand-iq.com/api/decks/{deckId}/presentations \
  -H "Authorization: Bearer $API_KEY" \
  -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, if the prospect already exists in Demand IQ — for example, they came through your Journeys funnel — send their ID instead:

curl -X POST \
  https://presentations.demand-iq.com/api/decks/{deckId}/presentations \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prospect_id": "b8a3d9e1-4c2f-4a7b-9e5d-6f1c8a2b3d4e"
  }'

Both return the same response, immediately:

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

url is the link you deliver to the prospect. deck_presentation_id is its ID for status checks and other API calls.

Sending prospect details (`homeowner`)

Field	Required	Notes
`first_name`	Yes	Used in the narration greeting
`address`	Yes	Street address
`city`	Yes
`state`	Yes	Required by Demand IQ’s prospect lookup
`zip`	Yes	Required by Demand IQ’s prospect lookup
`last_name`	No
`country`	No	Two-letter ISO code, e.g. `"US"`. Defaults to `"US"` if omitted
`email`	No	Needed if you want AI Presentations to email the link
`phone`	No

Behind the scenes, AI Presentations creates a new prospect record in Demand IQ from these details as part of this same call, using your API key. That’s why the key needs Write Prospects for this path, and it’s why state and zip are required here (Demand IQ’s own prospect API needs them) even though they aren’t required on the prospect_id path. If Demand IQ rejects the address or contact info, you’ll get a 422 with code PROSPECT_CREATE_FAILED; if Demand IQ rejects the credential itself, a 401 with code CORE_AUTH_REJECTED (check the scopes on your API key); if Demand IQ is unreachable, a 503. Separately, AI Presentations also validates the address via Google Geocoding when it builds the presentation — a 422 with code INVALID_ADDRESS means that step couldn’t resolve it to a real location. Either way, check for typos.

If your template uses pricing formulas, you can pass values for its price variables in a price_inputs object alongside homeowner (e.g. "price_inputs": {"system_size_kw": 8.4}). Missing variables don’t cause an error — the price is deferred and the slide shows a placeholder until values are available. Only variables that a pricing formula on the deck’s current slides references count here; variables left over from a removed product slide are ignored.

Sending a prospect ID (`prospect_id`)

Field	Required	Notes
`prospect_id`	Yes	The prospect’s Demand IQ ID

Looking up the prospect uses the Read Prospects permission covered in Step 1. A 422 with code PROSPECT_NOT_FOUND means the prospect ID doesn’t exist in Demand IQ or isn’t visible to your account — don’t retry the same ID; send their details with homeowner instead. A 401 with code CORE_AUTH_REJECTED means the key is missing Read Prospects (or the credential expired).

Sending both (`prospect_id` + `homeowner`)

Send both when the prospect already exists in Demand IQ but you want the presentation to use your contact details rather than whatever’s on that prospect record — for example, when your CRM has a fresher phone number or email than Demand IQ does. The prospect_id is attached to the presentation (Demand IQ verifies it exists and is visible to your key, so this path also needs Read Prospects), and the homeowner fields you send are used as-is for personalization. No new prospect is created, so Write Prospects is not required for this path. A 422 with code PROSPECT_NOT_FOUND means the prospect ID isn’t visible to your key.

This only pulls the prospect’s contact info — it doesn’t pull in pricing data or product selections from their journey (utility bill, roof measurements, etc.), so if your template has pricing formulas you still need to supply price_inputs explicitly, the same as with homeowner. If you need journey data pulled in automatically, and idempotent, auto-emailed delivery for a high-volume webhook integration, see POST /api/decks/{deckId}/ingest in the API Reference — that endpoint is purpose-built for automated journey-completion events rather than one-off calls like this guide covers.

The URL works the moment you receive it. Personalized narration audio can take a little while to render, and for some templates generation doesn’t start until the prospect opens the link — either way, the viewer experience handles it gracefully. If you’d rather hold delivery until everything is pre-rendered, poll the status endpoint (no auth required):

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

{
  "id": "7c2e5f8b-1a4d-4e6f-9b3c-8d0e2f4a6b1c",
  "status": "ready"
}

status moves through pending → generating → ready (a not_started status means generation kicks off when the prospect opens the link — the link is still ready to share). Once you have the URL, deliver it however you reach your prospects: text, email, a CRM field, or let AI Presentations send it (see Notifications for delivery and open tracking). Deliver the URL exactly as returned. The path segment after /p/ is the presentation’s UUID, and AI Presentations validates its format before looking anything up. A truncated or otherwise malformed link returns a 404 page. When the URL is pasted into SMS, iMessage, Slack, or similar apps, it unfurls into a rich preview: the deck name as the title, the deck description, your company name from branding, and the presentation’s first slide as the preview image. Everything is derived automatically from the template — nothing to configure. If the deck has no description or first-slide image, the preview falls back to the template’s intro background and default text. Unknown, deleted, or malformed links render no preview.

What’s next

Notifications — have AI Presentations email the link for you, get webhooks when the prospect opens it, and track engagement
API Quickstart — build the template itself over the API: create a deck, generate narrated slides from images, set branding
API Reference — full request/response details for every endpoint, in the sidebar

Overview

Guides

API Reference

Get a Presentation URL via API

How it works

What you’ll need

Step 1: Generate an API key

Step 2: Find your deck ID

Step 3: Create the presentation

Sending prospect details (`homeowner`)

Sending a prospect ID (`prospect_id`)

Sending both (`prospect_id` + `homeowner`)

What’s next

​How it works

​What you’ll need

​Step 1: Generate an API key

​Step 2: Find your deck ID

​Step 3: Create the presentation

​Sending prospect details (homeowner)

​Sending a prospect ID (prospect_id)

​Sending both (prospect_id + homeowner)

​Step 4: Share the link

​What’s next

How it works

What you’ll need

Step 1: Generate an API key

Step 2: Find your deck ID

Step 3: Create the presentation

Sending prospect details (`homeowner`)

Sending a prospect ID (`prospect_id`)

Sending both (`prospect_id` + `homeowner`)

Step 4: Share the link

What’s next