Survey Templates API

The Survey Templates API allows you to create, customize, and manage reusable templates for employee mobility surveys. Templates define which questions appear in the survey, the work mode (hybrid, in-person, remote), and any custom fields.

Customizable SurveysTemplates control the survey experience for employees. Depending on the work mode selected, different questions are shown or hidden automatically. The backend sends default values for hidden questions to ensure CO2e calculations remain accurate.

Key Features

Work Modes: Configure surveys for hybrid, in-person only, or remote-only teams
Step Configuration: Enable/disable, reorder, and set questions as required or optional
Custom Fields: Add organization-specific questions (text, number, select, boolean)
Default Templates: Mark a template as the organization default for quick survey creation
Clone & Iterate: Duplicate templates to create variations without starting from scratch
Versioning: Templates auto-increment version on each update for response traceability

Authentication

All endpoints require authentication using an API key or JWT token, plus the organization header.

Headers

x-organization-id

string

required

Your organization UUIDExample: a8315ef3-dd50-43f8-b7ce-d839e68d51fa

x-api-key

string

required

Your API key for authenticationExample: sk_live_1234567890abcdef

Available Endpoints

List Templates

Retrieve all survey templates for your organization

Create Template

Create a new survey template

Get Template

Get a specific template by ID

Update Template

Modify template configuration

Delete Template

Soft-delete a template

Clone Template

Duplicate an existing template

Set Default

Set a template as the organization default

Data Model

Template Object

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "organization_id": "a8315ef3-dd50-43f8-b7ce-d839e68d51fa",
  "name": "Standard Commuting Survey",
  "description": "Default template for employee commuting surveys",
  "is_default": true,
  "status": "active",
  "version": 1,
  "config": {
    "version": 1,
    "work_mode": "hybrid",
    "steps": [...],
    "custom_fields": [],
    "branding": {}
  },
  "created_by": "user-uuid",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

Work Modes

Mode	Description	Hidden Questions
`hybrid`	Shows all questions	None
`in_person_only`	Office-only teams	Work model, hours/day, telecommuting days
`remote_only`	Remote-only teams	Transport, distance, fuel type, carpooling, commuting address

Step Keys

Key	Type	Description
`start_date`	date	Measurement period dates
`name`	text	Employee name or ID (optional)
`hours_worked_per_day`	number	Hours worked per day
`telecommute`	select	Work model (telecommute vs office)
`weekly_travels`	number	Days commuting per week
`weekly_telecommuting`	number	Days working from home per week
`daily_trips`	number	Round trips per day
`total_km`	number	One-way distance in km
`transport`	select	Primary transport mode
`fuel_type`	select	Fuel type (conditional on transport)
`carpooling`	select	Car sharing (conditional on car)
`commuting_address`	text	Origin/destination addresses

Step Configuration

Each step in the config.steps array has:

Field	Type	Description
`key`	string	Step identifier (from Step Keys table)
`enabled`	boolean	Whether the step appears in the survey
`required`	boolean	Whether the step is mandatory
`default_value`	any	Default value when step is hidden
`description`	string	Custom subtitle shown under the question
`order`	integer	Display order (1-based)

Custom Fields

Custom fields allow adding organization-specific questions:

{
  "key": "department",
  "label": { "en": "Department", "es": "Departamento" },
  "field_type": "select",
  "required": false,
  "options": [
    { "value": "engineering", "label": { "en": "Engineering", "es": "Ingeniería" } },
    { "value": "marketing", "label": { "en": "Marketing", "es": "Marketing" } }
  ],
  "order": 1
}

Field Type	Description
`text`	Short text answer
`number`	Numeric input
`select`	Dropdown with predefined options
`boolean`	Yes/No toggle

Workflow

Creating a Customized Survey

Create Template: Define name, work mode, and question configuration
Customize Steps: Enable/disable and reorder questions
Add Custom Fields: Add organization-specific questions
Set as Default: Mark as the organization’s default template
Send Survey: Use the template when sending surveys via CSV upload or QR code

Using Templates with Surveys

When sending surveys via POST /v1/employees/csv or generating QR codes, pass the template_id parameter to use a specific template. If omitted, the organization’s default template is used.

Employees API

Manage employee records and commuting data

CSV Import

Bulk import employees and send surveys

Bulk Delete by Filters List Survey Templates

​Survey Templates API

​Key Features

​Authentication

​Headers

​Available Endpoints

List Templates

Create Template

Get Template

Update Template

Delete Template

Clone Template

Set Default

​Data Model

​Template Object

​Work Modes

​Step Keys

​Step Configuration

​Custom Fields

​Workflow

​Creating a Customized Survey

​Using Templates with Surveys

​Related Documentation

Employees API

CSV Import

Survey Templates API

Key Features

Authentication

Headers

Available Endpoints

Data Model

Template Object

Work Modes

Step Keys

Step Configuration

Custom Fields

Workflow

Creating a Customized Survey

Using Templates with Surveys

Related Documentation