Surveys

Retrieve a paginated list of surveys for your organization.

Query Parameters

Example Request

curl -X GET "https://app.surventrics.ai/api/v1/surveys?status=live" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "Customer Satisfaction Survey",
      "description": "Help us improve our service",
      "slug": "customer-satisfaction-2024",
      "status": "live",
      "questionCount": 10,
      "responseCount": 142,
      "viaAgents": 3,
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-20T14:45:00Z"
    }
  ],
  "pagination": {
    "total": 15,
    "page": 1,
    "pageSize": 20,
    "totalPages": 1,
    "hasMore": false
  }
}

responseCount is the survey's responses: completed sessions that are not excluded. viaAgents is how many of those came through a person's declared AI agent, so a survey reads “142 responses, of which 3 via agents”. It is always present (0 when none) and never more than responseCount. GET /surveys/:id returns the same two fields.

Create a new survey. The survey will be created in draft status.

Request Body

Example Request

curl -X POST "https://app.surventrics.ai/api/v1/surveys" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Product Feedback Survey",
    "description": "Tell us what you think about our product",
    "welcomeMessage": "Thanks for taking the time to share your thoughts!",
    "thankYouMessage": "Your feedback has been recorded."
  }'

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "title": "Product Feedback Survey",
  "description": "Tell us what you think about our product",
  "slug": "product-feedback-survey",
  "status": "draft",
  "questionCount": 0,
  "responseCount": 0,
  "viaAgents": 0,
  "createdAt": "2024-01-21T09:00:00Z",
  "updatedAt": "2024-01-21T09:00:00Z"
}

Retrieve a single survey by ID. If your API key has the questions:read scope, questions will be included in the response.

Path Parameters

Example Request

curl -X GET "https://app.surventrics.ai/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_API_KEY"

Update an existing survey. You can change the title, description, messages, and status.

Request Body

Example: Launch Survey

curl -X PUT "https://app.surventrics.ai/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "live"}'

Delete a survey. Live surveys cannot be deleted - pause or close them first. A deleted survey is hidden everywhere at once. An organisation admin or owner can restore it for 30 days; after that, it and all its responses are permanently deleted.

Example Request

curl -X DELETE "https://app.surventrics.ai/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_API_KEY"

Returns 204 No Content on success.

The clients your organization files surveys under: id, name, status and survey count. Needs the clients feature; without it the request is refused with 403 forbidden and details.feature "clients". The count is of the surveys your key may see.

Response

{
  "clients": [
    {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "name": "Acme Foods",
      "status": "active",
      "surveyCount": 3
    }
  ]
}

Create a read-only client portal link to the survey's results and/or one of its published reports. The link's URL is returned once, in this response, and cannot be shown again. An owner or admin must first allow agents to create client portal links at /organization/agents; the switch appears there once client portals are available to your organization. Needs edit on the survey. Each refusal is 403 forbidden with details.feature (agentPortalLinks or clientPortal) and details.reason; an invalid body is 400 invalid_request.

Request Body

Response

{
  "portal": {
    "id": "9b2f6c1e-3d4a-4f5b-8c7d-1e2f3a4b5c6d",
    "expiresAt": "2027-01-01T00:00:00.000Z",
    "hasPasscode": false,
    "tokenHint": "a1b2"
  },
  "url": "https://respond.surventrics.ai/portal/…"
}