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
Go to Settings → API
Click Generate API Key
Name your key (e.g., "Production Integration")
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/v1Authentication
API Key Authentication
Include your API key in the header:
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:
# Authorization endpoint
https://api.q-fi.io/oauth/authorize
# Token endpoint
https://api.q-fi.io/oauth/tokenAPI 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:
{
"success": true,
"data": {
// Response data here
},
"meta": {
"page": 1,
"per_page": 25,
"total": 100
}
}Error Responses
Errors return appropriate HTTP codes:
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid survey ID format",
"details": {
"field": "survey_id",
"issue": "Must be a valid UUID"
}
}
}| Code | Meaning |
|---|---|
| 400 | Bad request |
| 401 | Unauthorized |
| 403 | Forbidden |
| 404 | Not found |
| 429 | Rate limited |
| 500 | Server error |
Core Endpoints
Surveys
# 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
# List responses
GET /v1/surveys/{id}/responses
# Get single response
GET /v1/responses/{id}
# Export responses
POST /v1/surveys/{id}/responses/exportPanel Members
# 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
# List projects
GET /v1/projects
# Get project
GET /v1/projects/{id}
# Create project
POST /v1/projectsExample Requests
List Surveys
curl -X GET "https://api.q-fi.io/v1/surveys" \
-H "Authorization: Bearer YOUR_API_KEY"Response:
{
"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
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
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:
GET /v1/surveys?page=2&per_page=50Parameters:
page- Page number (default: 1)per_page- Items per page (default: 25, max: 100)
Response includes:
{
"meta": {
"page": 2,
"per_page": 50,
"total": 237,
"total_pages": 5
}
}Filtering
Filter results with query parameters:
# 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-34Webhooks
What Are Webhooks?
Webhooks notify your systems when events occur:
- Survey response submitted
- Member created/updated
- Focus group scheduled
- Export completed
Setting Up Webhooks
Go to Settings → API → Webhooks
Click Add Webhook
Enter your endpoint URL
Select events to subscribe to
Save and test
Webhook Payload
{
"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:
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
| Plan | Requests/minute | Requests/day |
|---|---|---|
| Professional | 100 | 10,000 |
| Enterprise | 500 | 100,000 |
Rate Limit Headers
Responses include:
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1642687200Handling Rate Limits
When rate limited (429 response):
- Check
Retry-Afterheader - Wait specified time
- Implement exponential backoff
- 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
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
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
- Email: api-support@q-fi.io
- Developer Discord: [link]
- Stack Overflow tag:
q-fi-api
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
- ChatGPT and Claude Connectors - Use ChatGPT or Claude as a survey assistant
- Zapier Integration - Automate workflows with triggers and actions
- Webhook Integration - Set up real-time notifications
- Data Export API - Bulk data access