Unformal API
Create and manage conversational Pulses programmatically. Send someone a link, an AI agent has the conversation, you get structured insights back.
Authentication
Most requests require an API key. Get one instantly via the signup endpoint, or create one at Studio → Settings.
AI Agent Setup
Install the Unformal skill so your AI agent can create Pulses with a single command:
# Install the Unformal skill for Claude Code
mkdir -p ~/.claude/skills/unformal && curl -s https://unformal.ai/SKILL.md > ~/.claude/skills/unformal/SKILL.md
After install, just say: “Create an onboarding Pulse for my consulting business”
Full integration guide →CLI
Every API endpoint is exposed as a subcommand in @unformal/cli. Great for shell scripts, CI, quick ops, and piping to other agents via --json.
# Install globally
npm i -g @unformal/cli
# Or run without installing
npx @unformal/cli <command>
# Authenticate
unformal init --key unf_YOUR_KEY
# Examples
unformal create --intention "Qualify leads"
unformal list
unformal conversations PULSE_ID
unformal resonance PULSE_ID
unformal export PULSE_ID --format csv --output all.csv
Source and full command list: github.com/Spark-Collective/unformal-skills/cli →
Agent Signup — No Browser Required
One API call to create an account, get an API key, and start creating Pulses. No login flow needed.
# Create account + get API key
curl -X POST "https://unformal.ai/api/v1/signup" \
-H "Content-Type: application/json" \
-d '{"email": "agent@company.com"}'
# Response:
{ "data": { "api_key": "unf_xxx...", "workspace_id": "...", "email": "agent@company.com", "credits": 50 } }
The API key is shown once. Store it securely. No authentication required for this endpoint.
Base URL
Quick Start
Create a Pulse and get a shareable link in one call:
# Create a Pulse
curl -X POST "https://unformal.ai/api/v1/pulses" \
-H "Authorization: Bearer unf_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"intention": "Understand what a new client needs before our first meeting"}'
# Response:
{ "data": { "id": "...", "url": "https://unformal.ai/p/your-slug", "status": "active" } }
Endpoints
POST /pulses — Request Body
| Field | Type | Description |
|---|---|---|
| intention* | string | What the AI should learn from the respondent |
| slug | string | Custom URL slug (lowercase, numbers, hyphens, 2-80 chars). If omitted, auto-generated from intention. |
| context | string | Background info for the AI (not shown to respondent) |
| mode | string | interview (default) — guided Q&A, one question at a time. extract — brain dump first, then fill gaps. |
| tone | string | conversational (default), formal, coaching, casual, custom |
| maxDurationMin | number | Max duration in minutes: 2, 5, 10, 15 (default: 5) |
| maxQuestions | number | Max questions: 3, 5, 8, 12, 20 (default: 8) |
| linkType | string | multi (default) or single (one response only) |
| model | string | claude-sonnet (default), gpt-4o, gemini |
| welcomeTitle | string | Custom title on the welcome screen before conversation starts |
| welcomeDescription | string | Custom description on the welcome screen |
| webhookUrl | string | URL to POST Echo data when conversation completes |
| notifyEmail | string | Email to notify on completion |
| dictationEnabled | boolean | Allow voice dictation (default: true) |
| showInsights | boolean | Show respondent insights on completion (default: false) |
| insightExchange | boolean | Insight Exchange — respondents see anonymized group insights after completing (default: false) |
| allowResearch | boolean | AI web research during conversation, 2x credits (default: false) |
| persona | string | Custom AI personality/voice. The AI adopts this character during conversations. |
| outputFields | array | Custom extraction fields: [{name, type, description}]. Types: string, number, boolean, array. Auto-generated if omitted. |
| topics | array | Theme guidance for the AI (array of strings) |
| completionPriority | string | balanced (default), coverage (thorough, 90%+ fields), speed (closes at maxQuestions) |
| completionRedirect | string | Custom redirect URL after conversation completion |
| themeMode | string | system (default), light, dark — conversation UI theme |
Modes
🎙️ Interview (default)
Guided conversation. The AI asks one question at a time, adapting follow-ups based on responses. Best for structured discovery, qualifications, and deep-dive interviews.
🗒️ Extract
Brain dump first. The respondent writes everything they want to say upfront. The AI then asks only about what's missing from the output fields. Best for intake forms, bug reports, and data collection where the respondent already knows what to share.
Output Fields — Structured Data Extraction
Output fields define the structured data the AI extracts from conversations. They're auto-generated from your intention, but you can customize them. This is the key to getting consistent, structured data from every conversation.
Echo — Structured Output
When a conversation completes, the AI extracts structured data (Echo) from the transcript:
Webhooks
Set webhookUrl on a Pulse to receive Echo data on completion:
Signed with X-Unformal-Signature (HMAC-SHA256).
Errors
Integrate with AI Agents
Drop a skill file into your project or install via ClawHub. Your AI assistant creates Pulses and gets structured data back.
Integration guide →