API Documentation | Survey Creators

Authentication

All API requests require an API key. Include your API key in the X-API-Key header with every request.

Create and manage API keys in your Account Settings.

Example Request

curl -X GET "https://insightfromfeedback.com/api/v1/surveys" \
  -H "X-API-Key: sc_live_your_api_key_here"

⚠️ Keep Your Keys Secure

Never expose keys in client-side code
Use environment variables in your applications
Rotate keys if you suspect they've been compromised

Rate Limits

API requests are rate limited based on your subscription plan:

Plan	Daily Limit
Starter	500 requests/day
Professional	5,000 requests/day

📊 Rate Limit Headers

Every response includes these headers:

X-RateLimit-Limit — Your daily limit
X-RateLimit-Remaining — Requests remaining
X-RateLimit-Reset — When the limit resets (ISO timestamp)

Surveys

GET /api/v1/surveys

List all surveys in your workspace.

Response

{
  "success": true,
  "data": [
    {
      "id": 123,
      "title": "Vendor Security Assessment",
      "description": "Annual vendor security review",
      "status": "active",
      "type": "vendor",
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-01-20T14:00:00Z"
    }
  ]
}

GET /api/v1/surveys/:id

Get details for a specific survey including question and response counts.

POST /api/v1/surveys/:id/send

Send a survey to one or more contacts. Creates invitations and sends email notifications.

Request Body

Parameter	Type	Description
contactsrequired	array	Array of contact objects (max 100)
contacts[].emailrequired	string	Contact's email address
contacts[].name	string	Contact's name (optional)

Example

curl -X POST "https://insightfromfeedback.com/api/v1/surveys/123/send" \
  -H "X-API-Key: sc_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      {"email": "john@example.com", "name": "John Smith"},
      {"email": "jane@example.com", "name": "Jane Doe"}
    ]
  }'

Response

{
  "success": true,
  "data": {
    "sent": 2,
    "failed": 0,
    "results": [
      {
        "email": "john@example.com",
        "success": true,
        "invitation_id": 456,
        "survey_link": "https://insightfromfeedback.com/survey/abc123..."
      }
    ]
  }
}

Invitations

GET /api/v1/invitations/:id

Check the status of a survey invitation.

Response

{
  "success": true,
  "data": {
    "id": 456,
    "email": "john@example.com",
    "name": "John Smith",
    "status": "completed",
    "completed": true,
    "survey_id": 123,
    "survey_title": "Vendor Security Assessment",
    "created_at": "2025-01-20T10:00:00Z",
    "completed_at": "2025-01-21T15:30:00Z",
    "view_url": "https://insightfromfeedback.com/dashboard/responses/123"
  }
}

Status Values

Status	Description
`pending`	Invitation sent, survey not started
`in_progress`	Respondent has started the survey
`completed`	Survey completed

Webhooks

Receive real-time notifications when events occur, such as when a survey response is completed.

GET /api/v1/webhooks

List all webhooks for your workspace.

POST /api/v1/webhooks

Create a new webhook.

Request Body

Parameter	Type	Description
urlrequired	string	HTTPS URL to receive webhook payloads
event_type	string	`response.completed` or `response.started`

⚠️ Save Your Secret

The webhook secret is only returned once when you create the webhook. Use it to verify webhook signatures.

DELETE /api/v1/webhooks/:id

Delete a webhook.

Webhook Payload

When an event occurs, we send a POST request to your webhook URL:

{
  "event": "response.completed",
  "timestamp": "2025-01-21T15:30:00Z",
  "data": {
    "invitation_id": 456,
    "survey_id": 123,
    "survey_title": "Vendor Security Assessment",
    "respondent_email": "john@example.com",
    "completed_at": "2025-01-21T15:30:00Z",
    "score": 72,
    "risk_level": "medium",
    "view_url": "https://insightfromfeedback.com/dashboard/responses/123"
  }
}

Verifying Signatures

Each webhook includes an X-Webhook-Signature header. Verify it using HMAC-SHA256:

const crypto = require('crypto');

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

Error Handling

The API uses standard HTTP status codes and returns errors in a consistent format:

{
  "error": "validation_error",
  "message": "contacts array is required"
}

Status Codes

Code	Description
`200`	Success
`201`	Created successfully
`400`	Bad request — check your parameters
`401`	Unauthorized — invalid or missing API key
`403`	Forbidden — subscription inactive or plan doesn't allow API
`404`	Resource not found
`429`	Rate limit exceeded
`500`	Server error — contact support

Need Help?

If you have questions or need assistance with the API, contact us at support@insightfromfeedback.com.