Back to Home

Norman AI API Documentation

Build powerful integrations with Norman AI's comprehensive REST API. Automate UX testing workflows, manage participants, and retrieve insights programmatically.

Introduction

The Norman AI API is a RESTful web service that allows you to integrate UX testing capabilities into your applications. With our API, you can:

Create and manage UX tests programmatically
Recruit and manage test participants
Retrieve test results and analytics
Generate reports and insights
Set up webhooks for real-time notifications
Integrate with your existing design and development tools

🚀 Quick Start

Get started with our API in minutes. All you need is an API key and a few lines of code.

Authentication

Norman AI uses API keys for authentication. Include your API key in the Authorization header of all requests.

curl -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     https://api.normanai.com/v1/tests
            

Getting Your API Key

Log into your Norman AI dashboard
Navigate to Settings > API Keys
Click "Generate New Key"
Copy and securely store your API key

⚠️ Security Best Practices

Keep your API key secure and never expose it in client-side code
Use environment variables or secure key management systems
Rotate your API keys regularly
Use different keys for different environments (development, staging, production)

Base URL

All API requests should be made to:

https://api.normanai.com/v1

Rate Limits

API requests are rate limited to ensure fair usage and system stability:

Plan	Requests per minute	Requests per day
Starter	60	1,000
Professional	300	10,000
Enterprise	1,000	100,000

Tests

Tests are the core resource in Norman AI. They represent UX testing studies that you want to conduct.

Create a Test

POST /tests

Request Body

{
  "name": "Mobile App Onboarding Test",
  "description": "Test the new user onboarding flow for our mobile app",
  "type": "usability",
  "scenarios": [
    {
      "title": "Complete Sign Up",
      "description": "Create a new account and complete profile setup",
      "tasks": [
        "Navigate to sign up page",
        "Fill out registration form",
        "Verify email address",
        "Complete profile setup"
      ],
      "success_criteria": "User successfully creates account and completes profile"
    }
  ],
  "participant_criteria": {
    "age_range": [18, 35],
    "locations": ["US", "CA"],
    "device_types": ["mobile"],
    "experience_level": "beginner",
    "demographics": {
      "gender": "any",
      "income": "any"
    }
  },
  "budget": 500,
  "participant_count": 20,
  "duration_minutes": 15,
  "launch_immediately": false
}
            

Response

201 Created { "id": "test_123456789", "name": "Mobile App Onboarding Test", "description": "Test the new user onboarding flow for our mobile app", "status": "draft", "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-15T10:30:00Z", "participant_count": 20, "budget": 500, "estimated_completion": "2024-01-17T10:30:00Z" }

Get All Tests

GET /tests

Query Parameters

Parameter	Type	Required	Description
status	string	No	Filter by test status (draft, active, completed, cancelled)
limit	integer	No	Number of tests to return (default: 20, max: 100)
offset	integer	No	Number of tests to skip (default: 0)

Get Test Details

GET /tests/{test_id}

Update a Test

PUT /tests/{test_id}

Launch a Test

POST /tests/{test_id}/launch

Cancel a Test

POST /tests/{test_id}/cancel

Participants

Manage test participants and their recruitment process.

Get Test Participants

GET /tests/{test_id}/participants

Add Custom Participants

POST /tests/{test_id}/participants

{
  "participants": [
    {
      "email": "participant@example.com",
      "name": "John Doe",
      "demographics": {
        "age": 28,
        "location": "San Francisco, CA",
        "device_type": "mobile",
        "experience_level": "intermediate"
      }
    }
  ]
}
            

Results

Retrieve test results, video recordings, and participant feedback.

Get Test Results

GET /tests/{test_id}/results

Response

200 OK { "test_id": "test_123456789", "status": "completed", "participant_count": 20, "completion_rate": 95, "results": [ { "participant_id": "participant_123", "session_id": "session_456", "completed_at": "2024-01-16T14:30:00Z", "duration_seconds": 900, "tasks_completed": 4, "success_rate": 100, "video_url": "https://api.normanai.com/v1/sessions/session_456/video", "transcript_url": "https://api.normanai.com/v1/sessions/session_456/transcript", "feedback": { "overall_rating": 4.5, "difficulty_rating": 2.0, "comments": "The onboarding flow was intuitive and easy to follow." }, "interactions": [ { "timestamp": "00:00:30", "action": "click", "element": "signup_button", "success": true } ] } ], "analytics": { "average_completion_time": 12.5, "success_rate": 95, "common_issues": [ "Email verification step unclear", "Profile picture upload failed" ], "user_satisfaction": 4.2 } }

Get Session Details

GET /sessions/{session_id}

Download Session Video

GET /sessions/{session_id}/video

Reports

Generate comprehensive reports and insights from test results.

Generate Report

POST /tests/{test_id}/reports

{
  "format": "pdf",
  "include_videos": true,
  "include_transcripts": true,
  "sections": [
    "executive_summary",
    "user_journey_analysis",
    "usability_metrics",
    "recommendations"
  ]
}
            

Get Report Status

GET /reports/{report_id}

Download Report

GET /reports/{report_id}/download

Webhooks

Set up webhooks to receive real-time notifications about test events.

Create Webhook

POST /webhooks

{
  "url": "https://your-app.com/webhooks/norman-ai",
  "events": [
    "test.launched",
    "test.completed",
    "participant.completed",
    "report.generated"
  ],
  "secret": "your_webhook_secret"
}
            

Webhook Events

test.launched

Triggered when a test is launched and participant recruitment begins.

test.completed

Triggered when all participants have completed the test.

participant.completed

Triggered when an individual participant completes their session.

report.generated

Triggered when a report generation is complete and ready for download.

Integrations

Integrate Norman AI with your favorite design and development tools.

Figma Integration

// Install Norman AI Figma plugin
// Then use the API to create tests from Figma frames

const test = await normanAI.tests.create({
  name: "Figma Design Test",
  source: "figma",
  figma_file_id: "your_file_id",
  frame_ids: ["frame_1", "frame_2"],
  scenarios: [
    {
      title: "Test Design Usability",
      tasks: ["Navigate through the design", "Complete the main flow"]
    }
  ]
});
            

Slack Integration

// Send test results to Slack channel
const webhook = await normanAI.webhooks.create({
  url: "https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK",
  events: ["test.completed"],
  filters: {
    test_status: "completed"
  }
});
            

Analytics

Access detailed analytics and insights about your testing activities.

Get Analytics Dashboard

GET /analytics/dashboard

Get Test Analytics

GET /tests/{test_id}/analytics

AI Features

Leverage Norman AI's artificial intelligence capabilities for enhanced testing.

AI Test Generation

POST /ai/generate-test

{
  "product_description": "E-commerce mobile app for fashion",
  "target_audience": "Young adults aged 18-35",
  "testing_goals": ["usability", "conversion_optimization"],
  "complexity": "intermediate"
}
            

AI Insights Analysis

POST /ai/analyze-insights

Official SDKs

Use our official SDKs to integrate Norman AI into your applications quickly and easily.

Available SDKs

JavaScript/Node.js Python PHP Ruby Go Java

JavaScript Example

// Install: npm install @norman-ai/sdk

const NormanAI = require('@norman-ai/sdk');

const client = new NormanAI({
  apiKey: process.env.NORMAN_AI_API_KEY
});

// Create a test
const test = await client.tests.create({
  name: "My UX Test",
  scenarios: [
    {
      title: "Test User Flow",
      tasks: ["Complete signup", "Navigate to dashboard"]
    }
  ],
  participant_criteria: {
    age_range: [25, 40],
    locations: ["US"]
  }
});

// Launch the test
await client.tests.launch(test.id);

// Get results when ready
const results = await client.tests.getResults(test.id);
            

Postman Collection

Import our Postman collection to quickly test API endpoints and explore the API.

📥 Download Postman Collection

Get our complete Postman collection with all API endpoints, example requests, and environment variables.

Download Collection

Code Examples

Real-world examples of common API usage patterns.

Complete Testing Workflow

// 1. Create a test
const test = await client.tests.create({
  name: "E-commerce Checkout Flow",
  scenarios: [
    {
      title: "Complete Purchase",
      tasks: [
        "Add item to cart",
        "Proceed to checkout",
        "Enter payment details",
        "Complete purchase"
      ]
    }
  ],
  participant_criteria: {
    age_range: [18, 65],
    locations: ["US", "CA", "UK"],
    device_types: ["desktop", "mobile"]
  },
  budget: 1000,
  participant_count: 50
});

// 2. Launch the test
await client.tests.launch(test.id);

// 3. Set up webhook for completion notification
await client.webhooks.create({
  url: "https://your-app.com/webhook",
  events: ["test.completed"]
});

// 4. Generate report when test is complete
const report = await client.tests.generateReport(test.id, {
  format: "pdf",
  include_videos: true
});

// 5. Download and process results
const results = await client.tests.getResults(test.id);
console.log(`Test completed with ${results.participant_count} participants`);
            

Error Codes

Common error codes and their meanings.

Code	HTTP Status	Description
invalid_api_key	401	Invalid or missing API key
rate_limit_exceeded	429	Rate limit exceeded
test_not_found	404	Test with specified ID not found
insufficient_budget	400	Insufficient budget for test requirements
invalid_participant_criteria	400	Participant criteria is invalid or too restrictive

Changelog

Recent changes and updates to the API.

Version 1.2.0 (January 2024)

Added AI-powered test generation endpoint
Enhanced analytics with new metrics
Improved webhook reliability
Added support for custom participant recruitment

Version 1.1.0 (December 2023)

Added Figma integration endpoints
Enhanced report generation options
Improved error handling and messages
Added bulk operations for participants

Support

Need help with the API? We're here to support you.

📚 Documentation

Comprehensive guides and reference materials

💬 Community

Join our developer community for help and discussions

📧 Support

Contact our technical support team

🐛 Bug Reports

Report issues and request features

🚀 Ready to Get Started?

Start building with the Norman AI API today. Get your API key and begin creating powerful UX testing integrations.

Get API Access

Getting Started

Core Resources

Advanced Features

SDKs & Tools

Reference

Norman AI API Documentation

Introduction

🚀 Quick Start

Authentication

Getting Your API Key

⚠️ Security Best Practices

Base URL

Rate Limits

Tests

Create a Test

Request Body

Response

Get All Tests

Query Parameters

Get Test Details

Update a Test

Launch a Test

Cancel a Test

Participants

Get Test Participants

Add Custom Participants

Results

Get Test Results

Response

Get Session Details

Download Session Video

Reports

Generate Report

Get Report Status

Download Report

Webhooks

Create Webhook

Webhook Events

test.launched

test.completed

participant.completed

report.generated

Integrations

Figma Integration

Slack Integration

Analytics

Get Analytics Dashboard

Get Test Analytics

AI Features

AI Test Generation

AI Insights Analysis

Official SDKs

Available SDKs

JavaScript Example

Postman Collection

📥 Download Postman Collection

Code Examples

Complete Testing Workflow

Error Codes

Changelog

Version 1.2.0 (January 2024)

Version 1.1.0 (December 2023)

Support

📚 Documentation

💬 Community

📧 Support

🐛 Bug Reports

🚀 Ready to Get Started?