> ## Documentation Index
> Fetch the complete documentation index at: https://code.dcycle.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Survey Templates API

> Create and manage customizable employee mobility survey templates

# 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.

<Note>
  **Customizable Surveys**

  Templates 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.
</Note>

## 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

<ParamField header="x-organization-id" type="string" required>
  Your organization UUID

  **Example:** `a8315ef3-dd50-43f8-b7ce-d839e68d51fa`
</ParamField>

<ParamField header="x-api-key" type="string" required>
  Your API key for authentication

  **Example:** `sk_live_1234567890abcdef`
</ParamField>

## Available Endpoints

<CardGroup cols={2}>
  <Card title="List Templates" icon="list" href="/api-reference/employees/survey-templates/list">
    Retrieve all survey templates for your organization
  </Card>

  <Card title="Create Template" icon="plus" href="/api-reference/employees/survey-templates/create">
    Create a new survey template
  </Card>

  <Card title="Get Template" icon="file" href="/api-reference/employees/survey-templates/get">
    Get a specific template by ID
  </Card>

  <Card title="Update Template" icon="pencil" href="/api-reference/employees/survey-templates/update">
    Modify template configuration
  </Card>

  <Card title="Delete Template" icon="trash" href="/api-reference/employees/survey-templates/delete">
    Soft-delete a template
  </Card>

  <Card title="Clone Template" icon="copy" href="/api-reference/employees/survey-templates/clone">
    Duplicate an existing template
  </Card>

  <Card title="Set Default" icon="star" href="/api-reference/employees/survey-templates/set-default">
    Set a template as the organization default
  </Card>
</CardGroup>

## Data Model

### Template Object

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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

1. **Create Template**: Define name, work mode, and question configuration
2. **Customize Steps**: Enable/disable and reorder questions
3. **Add Custom Fields**: Add organization-specific questions
4. **Set as Default**: Mark as the organization's default template
5. **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.

## Related Documentation

<CardGroup cols={2}>
  <Card title="Employees API" icon="users" href="/api-reference/employees/overview">
    Manage employee records and commuting data
  </Card>

  <Card title="CSV Import" icon="upload" href="/api-reference/employees/csv-import">
    Bulk import employees and send surveys
  </Card>
</CardGroup>