advanced
Featured

API Overview

Connect external services and use the Quali-Fi API

15 min readUpdated January 20, 2026

API Overview

The Quali-Fi API enables you to integrate Quali-Fi with your existing systems, automate workflows, and build custom applications. This guide covers API basics and authentication.

What You Can Do

The Quali-Fi API allows you to:

  • Manage Surveys - Create, update, distribute surveys
  • Access Responses - Retrieve and analyze data
  • Manage Panel - Add, update, query members
  • Trigger Actions - Automate based on events
  • Build Integrations - Connect to other systems

Getting Started

API Access

API access requires:

  • Professional or Enterprise plan
  • Admin or Owner role
  • API credentials

Getting Your API Key

1

Go to Settings → API

2

Click Generate API Key

3

Name your key (e.g., "Production Integration")

4

Copy and securely store the key

Warning

API keys grant full access to your data. Never share keys or commit them to public repositories.

Base URL

All API requests use:

https://api.q-fi.io/v1

Authentication

API Key Authentication

Include your API key in the header:

bash
curl -X GET "https://api.q-fi.io/v1/surveys" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

OAuth 2.0 (Enterprise)

For user-context integrations:

bash
# Authorization endpoint
https://api.q-fi.io/oauth/authorize

# Token endpoint
https://api.q-fi.io/oauth/token

API Basics

Request Format

All requests should:

  • Use HTTPS
  • Include Content-Type: application/json
  • Include authentication header
  • Send JSON body for POST/PUT

Response Format

Responses are JSON:

json
{
  "success": true,
  "data": {
    // Response data here
  },
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 100
  }
}

Error Responses

Errors return appropriate HTTP codes:

json
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid survey ID format",
    "details": {
      "field": "survey_id",
      "issue": "Must be a valid UUID"
    }
  }
}
CodeMeaning
400Bad request
401Unauthorized
403Forbidden
404Not found
429Rate limited
500Server error

Core Endpoints

Surveys

bash
# List surveys
GET /v1/surveys

# Get survey
GET /v1/surveys/{id}

# Create survey
POST /v1/surveys

# Update survey
PUT /v1/surveys/{id}

# Delete survey
DELETE /v1/surveys/{id}

Responses

bash
# List responses
GET /v1/surveys/{id}/responses

# Get single response
GET /v1/responses/{id}

# Export responses
POST /v1/surveys/{id}/responses/export

Panel Members

bash
# List members
GET /v1/panel/members

# Get member
GET /v1/panel/members/{id}

# Create member
POST /v1/panel/members

# Update member
PUT /v1/panel/members/{id}

# Delete member
DELETE /v1/panel/members/{id}

Projects

bash
# List projects
GET /v1/projects

# Get project
GET /v1/projects/{id}

# Create project
POST /v1/projects

Example Requests

List Surveys

bash
curl -X GET "https://api.q-fi.io/v1/surveys" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

json
{
  "success": true,
  "data": [
    {
      "id": "srv_abc123",
      "name": "Customer Satisfaction Q1",
      "status": "active",
      "response_count": 150,
      "created_at": "2026-01-15T10:00:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 12
  }
}

Create a Panel Member

bash
curl -X POST "https://api.q-fi.io/v1/panel/members" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "attributes": {
      "age_group": "25-34",
      "location": "New York"
    }
  }'

Get Survey Responses

bash
curl -X GET "https://api.q-fi.io/v1/surveys/srv_abc123/responses?status=complete&limit=100" \
  -H "Authorization: Bearer YOUR_API_KEY"

Pagination

List endpoints support pagination:

bash
GET /v1/surveys?page=2&per_page=50

Parameters:

  • page - Page number (default: 1)
  • per_page - Items per page (default: 25, max: 100)

Response includes:

json
{
  "meta": {
    "page": 2,
    "per_page": 50,
    "total": 237,
    "total_pages": 5
  }
}

Filtering

Filter results with query parameters:

bash
# Surveys by status
GET /v1/surveys?status=active

# Responses by date
GET /v1/surveys/{id}/responses?created_after=2026-01-01

# Members by attribute
GET /v1/panel/members?age_group=25-34

Webhooks

What Are Webhooks?

Webhooks notify your systems when events occur:

  • Survey response submitted
  • Member created/updated
  • Focus group scheduled
  • Export completed

Setting Up Webhooks

1

Go to Settings → API → Webhooks

2

Click Add Webhook

3

Enter your endpoint URL

4

Select events to subscribe to

5

Save and test

Webhook Payload

json
{
  "event": "response.submitted",
  "timestamp": "2026-01-20T14:30:00Z",
  "data": {
    "survey_id": "srv_abc123",
    "response_id": "rsp_xyz789",
    "member_id": "mbr_def456"
  }
}

Verifying Webhooks

Validate webhook authenticity:

javascript
const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const hash = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return hash === signature;
}

Rate Limits

Default Limits

PlanRequests/minuteRequests/day
Professional10010,000
Enterprise500100,000

Rate Limit Headers

Responses include:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1642687200

Handling Rate Limits

When rate limited (429 response):

  1. Check Retry-After header
  2. Wait specified time
  3. Implement exponential backoff
  4. Consider request batching

SDKs & Libraries

Official SDKs

  • JavaScript/Node.js - npm install @q-fi/sdk
  • Python - pip install qfi-sdk
  • PHP - composer require qfi/sdk

JavaScript Example

javascript
import { QFiClient } from '@q-fi/sdk';

const client = new QFiClient({
  apiKey: process.env.QFI_API_KEY
});

// List surveys
const surveys = await client.surveys.list();

// Get responses
const responses = await client.surveys.getResponses('srv_abc123');

// Create member
const member = await client.panel.createMember({
  email: 'john@example.com',
  firstName: 'John'
});

Python Example

python
from qfi import QFiClient

client = QFiClient(api_key='your_api_key')

# List surveys
surveys = client.surveys.list()

# Get responses
responses = client.surveys.get_responses('srv_abc123')

# Create member
member = client.panel.create_member(
    email='john@example.com',
    first_name='John'
)

Best Practices

Security

  • Store API keys in environment variables
  • Use HTTPS only
  • Rotate keys periodically
  • Monitor for unusual activity

Performance

  • Cache responses when appropriate
  • Use pagination for large datasets
  • Batch requests when possible
  • Implement retry logic

Error Handling

  • Always check response status
  • Handle rate limits gracefully
  • Log errors for debugging
  • Implement circuit breakers

Tip

Use webhooks instead of polling for real-time updates. It's more efficient and provides faster notifications.

API Reference

For complete endpoint documentation:

Getting Help

Developer Support

ChatGPT and Claude connectors

End users can connect ChatGPT (Custom GPT) or Claude (custom connector) to list, create, and manage surveys through natural language. Org admins set up ChatGPT using OAuth credentials from API Access; Claude users add a connector URL from your administrator and sign in per user.

See ChatGPT and Claude Connectors for setup steps, permissions, and limitations.

Next Steps

Was this article helpful?