# Surveys

**Summary:** Endpoints for Surveys

- Role: [Developers](https://www.subrite.no/developers)
- Source: https://www.subrite.no/developers/surveys
- Updated: 2026-10-13
- Markdown index: https://www.subrite.no/developers/llms.txt

<a id="get-api-v1-surveys"></a>
## List surveys (paginated)

`GET /api/v1/surveys`

**Authentication:** Bearer token (JWT)

### Parameters

| Name | In | Type | Description |
| --- | --- | --- | --- |
| `page` | query | `number` | Default: `1` · `minimum`: `1` |
| `take` | query | `number` | Default: `10` · `minimum`: `1`, `maximum`: `50` |
| `orderBy` | query | `string` | Allowed values: `"createdAt"`, `"id"`, `"updatedAt"` · Default: `"createdAt"` |
| `orderDirection` | query | `string` | Allowed values: `"asc"`, `"desc"` · Default: `"desc"` |
| `status` | query | `string` | Filter by survey status · Allowed values: `"draft"`, `"published"`, `"paused"`, `"stopped"`, `"archived"` |
| `search` | query | `string` | Search surveys by name · `maxLength`: `255` |

### Responses

#### 200

Content type: `application/json` · `SurveyResponseDtoPaginated`

| Name | Type | Description |
| --- | --- | --- |
| `items` (Required) | `array of SurveyResponseDto` |   |
| `items[].id` (Required when parent is present) | `string` |   |
| `items[].name` (Required when parent is present) | `string` |   |
| `items[].status` (Required when parent is present) | `string` | Allowed values: `"draft"`, `"published"`, `"paused"`, `"stopped"`, `"archived"` |
| `items[].formJson` | `object` | Can be null |
| `items[].themeJson` | `object` | Can be null |
| `items[].completionJson` | `object` | Can be null |
| `items[].startDate` | `string (date-time)` | Can be null |
| `items[].endDate` | `string (date-time)` | Can be null |
| `items[].publishedAt` | `string (date-time)` | Can be null |
| `items[].stoppedAt` | `string (date-time)` | Can be null |
| `items[].createdAt` (Required when parent is present) | `string (date-time)` |   |
| `items[].updatedAt` (Required when parent is present) | `string (date-time)` |   |
| `items[].createdByUserId` | `number` | Can be null |
| `items[].updatedByUserId` | `number` | Can be null |
| `items[].responseCount` (Required when parent is present) | `number` | Number of responses for this survey |
| `meta` (Required) | `PageMeta` |   |
| `meta.page` (Required) | `number` |   |
| `meta.take` (Required) | `number` |   |
| `meta.count` (Required) | `number` |   |
| `meta.pageCount` (Required) | `number` |   |
| `meta.hasPreviousPage` (Required) | `boolean` |   |
| `meta.hasNextPage` (Required) | `boolean` |   |

#### 401

unauthorized

### Example request

```bash
curl https://api.subrite.no/api/v1/surveys \
  --header 'Authorization: Bearer <token>'
```

### Example response

200 · `application/json`

```json
{
  "items": [
    {
      "formJson": {},
      "themeJson": {},
      "completionJson": {}
    }
  ],
  "meta": {
    "page": 0,
    "take": 0,
    "count": 0,
    "pageCount": 0,
    "hasPreviousPage": true,
    "hasNextPage": true
  }
}
```

<a id="post-api-v1-surveys"></a>
## Create a new draft survey

`POST /api/v1/surveys`

**Authentication:** Bearer token (JWT)

### Request body

Content type: `application/json` · Required · `CreateSurveyDto`

| Name | Type | Description |
| --- | --- | --- |
| `name` (Required) | `string` | Survey name · `maxLength`: `255` |
| `status` | `string` | Survey status (defaults to draft) · Allowed values: `"draft"`, `"published"`, `"paused"`, `"stopped"`, `"archived"` |
| `formJson` | `object` | SurveyJS form definition |
| `themeJson` | `object` | SurveyJS theme definition |
| `startDate` | `string` | Survey start date |
| `endDate` | `string` | Survey end date |
| `completionJson` | `object` | Completion screen configuration |

**Example request body**

`application/json`

```json
{
  "name": "string",
  "status": "draft",
  "formJson": {},
  "themeJson": {},
  "startDate": "string",
  "endDate": "string",
  "completionJson": {}
}
```

### Responses

#### 201

Content type: `application/json` · `SurveyResponseDto`

| Name | Type | Description |
| --- | --- | --- |
| `id` (Required) | `string` |   |
| `name` (Required) | `string` |   |
| `status` (Required) | `string` | Allowed values: `"draft"`, `"published"`, `"paused"`, `"stopped"`, `"archived"` |
| `formJson` | `object` | Can be null |
| `themeJson` | `object` | Can be null |
| `completionJson` | `object` | Can be null |
| `startDate` | `string (date-time)` | Can be null |
| `endDate` | `string (date-time)` | Can be null |
| `publishedAt` | `string (date-time)` | Can be null |
| `stoppedAt` | `string (date-time)` | Can be null |
| `createdAt` (Required) | `string (date-time)` |   |
| `updatedAt` (Required) | `string (date-time)` |   |
| `createdByUserId` | `number` | Can be null |
| `updatedByUserId` | `number` | Can be null |
| `responseCount` (Required) | `number` | Number of responses for this survey |

#### 400

Content type: `application/json` · `ErrorResponse`

surveyInvalidCreateStatus \| surveyFormJsonRequired \| surveyFormJsonMissingQuestions \| surveyEndDateMustBeFuture \| surveyEndDateBeforeStartDate

| Name | Type | Description |
| --- | --- | --- |
| `messageCode` (Required) | `string` | Allowed values: `"surveyInvalidCreateStatus"` |
| `message` | `string` |   |
| `errors` (Required) | `array of FieldError` |   |
| `errors[].field` (Required when parent is present) | `string` |   |
| `errors[].fieldValue` (Required when parent is present) | `string` |   |
| `errors[].identifier` (Required when parent is present) | `string` |   |
| `errors[].identifierValue` (Required when parent is present) | `string` |   |
| `errors[].messageCode` (Required when parent is present) | `string` |   |
| `errors[].message` | `string` |   |
| `errors[].errorType` (Required when parent is present) | `string` |   |

**Example response**

`application/json`

```json
{
  "messageCode": "surveyInvalidCreateStatus",
  "message": "string",
  "errors": [
    {}
  ]
}
```

#### 401

unauthorized

#### 409

Content type: `application/json` · `ErrorResponse`

surveyNameAlreadyExists

| Name | Type | Description |
| --- | --- | --- |
| `messageCode` (Required) | `string` | Allowed values: `"surveyNameAlreadyExists"` |
| `message` | `string` |   |
| `errors` (Required) | `array of FieldError` |   |
| `errors[].field` (Required when parent is present) | `string` |   |
| `errors[].fieldValue` (Required when parent is present) | `string` |   |
| `errors[].identifier` (Required when parent is present) | `string` |   |
| `errors[].identifierValue` (Required when parent is present) | `string` |   |
| `errors[].messageCode` (Required when parent is present) | `string` |   |
| `errors[].message` | `string` |   |
| `errors[].errorType` (Required when parent is present) | `string` |   |

**Example response**

`application/json`

```json
{
  "messageCode": "surveyNameAlreadyExists",
  "message": "string",
  "errors": [
    {}
  ]
}
```

### Example request

```bash
curl https://api.subrite.no/api/v1/surveys \
  --request POST \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "string",
  "status": "draft",
  "formJson": {},
  "themeJson": {},
  "startDate": "string",
  "endDate": "string",
  "completionJson": {}
}'
```

### Example response

201 · `application/json`

```json
{
  "id": "string",
  "name": "string",
  "status": "draft",
  "formJson": {},
  "themeJson": {},
  "completionJson": {},
  "startDate": "2019-08-24T14:15:22Z",
  "endDate": "2019-08-24T14:15:22Z",
  "publishedAt": "2019-08-24T14:15:22Z",
  "stoppedAt": "2019-08-24T14:15:22Z",
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z",
  "createdByUserId": 0,
  "updatedByUserId": 0,
  "responseCount": 0
}
```

<a id="get-api-v1-surveys-templates"></a>
## List survey templates

`GET /api/v1/surveys/templates`

**Authentication:** Bearer token (JWT)

### Responses

#### 200

Content type: `application/json` · `array of SurveyTemplateResponseDto`

| Name | Type | Description |
| --- | --- | --- |
| `[].id` (Required when parent is present) | `string` |   |
| `[].name` (Required when parent is present) | `string` |   |
| `[].description` | `string` | Can be null |
| `[].formJson` (Required when parent is present) | `object` |   |
| `[].metaData` | `object` | Can be null |
| `[].createdAt` (Required when parent is present) | `string (date-time)` |   |
| `[].updatedAt` (Required when parent is present) | `string (date-time)` |   |

#### 401

unauthorized

### Example request

```bash
curl https://api.subrite.no/api/v1/surveys/templates \
  --header 'Authorization: Bearer <token>'
```

### Example response

200 · `application/json`

```json
[
  {
    "id": "string",
    "name": "string",
    "description": "string",
    "formJson": {},
    "metaData": {},
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z"
  }
]
```

<a id="get-api-v1-surveys-id"></a>
## Get a single survey by ID

`GET /api/v1/surveys/{id}`

**Authentication:** Bearer token (JWT)

### Parameters

| Name | In | Type | Description |
| --- | --- | --- | --- |
| `id` (Required) | path | `string` |   |

### Responses

#### 200

Content type: `application/json` · `SurveyResponseDto`

Same fields as [Create a new draft survey (201)](https://www.subrite.no/developers/surveys?md=true#post-api-v1-surveys).

#### 401

unauthorized

#### 404

Content type: `application/json` · `ErrorResponse`

surveyNotFound

| Name | Type | Description |
| --- | --- | --- |
| `messageCode` (Required) | `string` | Allowed values: `"surveyNotFound"` |
| `message` | `string` |   |
| `errors` (Required) | `array of FieldError` |   |
| `errors[].field` (Required when parent is present) | `string` |   |
| `errors[].fieldValue` (Required when parent is present) | `string` |   |
| `errors[].identifier` (Required when parent is present) | `string` |   |
| `errors[].identifierValue` (Required when parent is present) | `string` |   |
| `errors[].messageCode` (Required when parent is present) | `string` |   |
| `errors[].message` | `string` |   |
| `errors[].errorType` (Required when parent is present) | `string` |   |

**Example response**

`application/json`

```json
{
  "messageCode": "surveyNotFound",
  "message": "string",
  "errors": [
    {}
  ]
}
```

### Example request

```bash
curl 'https://api.subrite.no/api/v1/surveys/{id}' \
  --header 'Authorization: Bearer <token>'
```

### Example response

200 · `application/json`

```json
{
  "id": "string",
  "name": "string",
  "status": "draft",
  "formJson": {},
  "themeJson": {},
  "completionJson": {},
  "startDate": "2019-08-24T14:15:22Z",
  "endDate": "2019-08-24T14:15:22Z",
  "publishedAt": "2019-08-24T14:15:22Z",
  "stoppedAt": "2019-08-24T14:15:22Z",
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z",
  "createdByUserId": 0,
  "updatedByUserId": 0,
  "responseCount": 0
}
```

<a id="delete-api-v1-surveys-id"></a>
## Soft delete a draft, stopped, or archived survey

`DELETE /api/v1/surveys/{id}`

**Authentication:** Bearer token (JWT)

### Parameters

| Name | In | Type | Description |
| --- | --- | --- | --- |
| `id` (Required) | path | `string` |   |

### Responses

#### 204

Survey deleted

#### 400

Content type: `application/json` · `ErrorResponse`

surveyOnlyDraftStoppedOrArchivedCanBeDeleted

| Name | Type | Description |
| --- | --- | --- |
| `messageCode` (Required) | `string` | Allowed values: `"surveyOnlyDraftStoppedOrArchivedCanBeDeleted"` |
| `message` | `string` |   |
| `errors` (Required) | `array of FieldError` |   |
| `errors[].field` (Required when parent is present) | `string` |   |
| `errors[].fieldValue` (Required when parent is present) | `string` |   |
| `errors[].identifier` (Required when parent is present) | `string` |   |
| `errors[].identifierValue` (Required when parent is present) | `string` |   |
| `errors[].messageCode` (Required when parent is present) | `string` |   |
| `errors[].message` | `string` |   |
| `errors[].errorType` (Required when parent is present) | `string` |   |

**Example response**

`application/json`

```json
{
  "messageCode": "surveyOnlyDraftStoppedOrArchivedCanBeDeleted",
  "message": "string",
  "errors": [
    {}
  ]
}
```

#### 401

unauthorized

#### 404

Content type: `application/json` · `ErrorResponse`

surveyNotFound

Same fields as [Get a single survey by ID (404)](https://www.subrite.no/developers/surveys?md=true#get-api-v1-surveys-id).

**Example response**

`application/json`

```json
{
  "messageCode": "surveyNotFound",
  "message": "string",
  "errors": [
    {}
  ]
}
```

### Example request

```bash
curl 'https://api.subrite.no/api/v1/surveys/{id}' \
  --request DELETE \
  --header 'Authorization: Bearer <token>'
```

<a id="patch-api-v1-surveys-id"></a>
## Update a survey

`PATCH /api/v1/surveys/{id}`

**Authentication:** Bearer token (JWT)

### Parameters

| Name | In | Type | Description |
| --- | --- | --- | --- |
| `id` (Required) | path | `string` |   |

### Request body

Content type: `application/json` · Required · `UpdateSurveyDto`

| Name | Type | Description |
| --- | --- | --- |
| `name` | `string` | Survey name · `maxLength`: `255` |
| `status` | `string` | Survey status (defaults to draft) · Allowed values: `"draft"`, `"published"`, `"paused"`, `"stopped"`, `"archived"` |
| `formJson` | `object` | SurveyJS form definition |
| `themeJson` | `object` | SurveyJS theme definition |
| `startDate` | `string` | Survey start date |
| `endDate` | `string` | Survey end date |
| `completionJson` | `object` | Completion screen configuration |

**Example request body**

`application/json`

```json
{
  "name": "string",
  "status": "draft",
  "formJson": {},
  "themeJson": {},
  "startDate": "string",
  "endDate": "string",
  "completionJson": {}
}
```

### Responses

#### 200

Content type: `application/json` · `SurveyResponseDto`

Same fields as [Create a new draft survey (201)](https://www.subrite.no/developers/surveys?md=true#post-api-v1-surveys).

#### 400

Content type: `application/json` · `ErrorResponse`

surveyArchivedCannotBeEdited \| surveyPublishedFormCannotBeEdited \| surveyPublishedDatesCannotBeEdited \| surveyInvalidStatusTransition \| surveyFormJsonRequired \| surveyFormJsonMissingQuestions \| surveyEndDateMustBeFuture \| surveyEndDateBeforeStartDate

| Name | Type | Description |
| --- | --- | --- |
| `messageCode` (Required) | `string` | Allowed values: `"surveyArchivedCannotBeEdited"` |
| `message` | `string` |   |
| `errors` (Required) | `array of FieldError` |   |
| `errors[].field` (Required when parent is present) | `string` |   |
| `errors[].fieldValue` (Required when parent is present) | `string` |   |
| `errors[].identifier` (Required when parent is present) | `string` |   |
| `errors[].identifierValue` (Required when parent is present) | `string` |   |
| `errors[].messageCode` (Required when parent is present) | `string` |   |
| `errors[].message` | `string` |   |
| `errors[].errorType` (Required when parent is present) | `string` |   |

**Example response**

`application/json`

```json
{
  "messageCode": "surveyArchivedCannotBeEdited",
  "message": "string",
  "errors": [
    {}
  ]
}
```

#### 401

unauthorized

#### 404

Content type: `application/json` · `ErrorResponse`

surveyNotFound

Same fields as [Get a single survey by ID (404)](https://www.subrite.no/developers/surveys?md=true#get-api-v1-surveys-id).

**Example response**

`application/json`

```json
{
  "messageCode": "surveyNotFound",
  "message": "string",
  "errors": [
    {}
  ]
}
```

#### 409

Content type: `application/json` · `ErrorResponse`

surveyNameAlreadyExists

Same fields as [Create a new draft survey (409)](https://www.subrite.no/developers/surveys?md=true#post-api-v1-surveys).

**Example response**

`application/json`

```json
{
  "messageCode": "surveyNameAlreadyExists",
  "message": "string",
  "errors": [
    {}
  ]
}
```

### Example request

```bash
curl 'https://api.subrite.no/api/v1/surveys/{id}' \
  --request PATCH \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "string",
  "status": "draft",
  "formJson": {},
  "themeJson": {},
  "startDate": "string",
  "endDate": "string",
  "completionJson": {}
}'
```

### Example response

200 · `application/json`

```json
{
  "id": "string",
  "name": "string",
  "status": "draft",
  "formJson": {},
  "themeJson": {},
  "completionJson": {},
  "startDate": "2019-08-24T14:15:22Z",
  "endDate": "2019-08-24T14:15:22Z",
  "publishedAt": "2019-08-24T14:15:22Z",
  "stoppedAt": "2019-08-24T14:15:22Z",
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z",
  "createdByUserId": 0,
  "updatedByUserId": 0,
  "responseCount": 0
}
```

<a id="post-api-v1-surveys-id-copy"></a>
## Copy a survey as a new draft

`POST /api/v1/surveys/{id}/copy`

**Authentication:** Bearer token (JWT)

### Parameters

| Name | In | Type | Description |
| --- | --- | --- | --- |
| `id` (Required) | path | `string` |   |

### Responses

#### 201

Content type: `application/json` · `SurveyResponseDto`

Same fields as [Create a new draft survey (201)](https://www.subrite.no/developers/surveys?md=true#post-api-v1-surveys).

#### 401

unauthorized

#### 404

Content type: `application/json` · `ErrorResponse`

surveyNotFound

Same fields as [Get a single survey by ID (404)](https://www.subrite.no/developers/surveys?md=true#get-api-v1-surveys-id).

**Example response**

`application/json`

```json
{
  "messageCode": "surveyNotFound",
  "message": "string",
  "errors": [
    {}
  ]
}
```

#### 409

Content type: `application/json` · `ErrorResponse`

surveyNameAlreadyExists

Same fields as [Create a new draft survey (409)](https://www.subrite.no/developers/surveys?md=true#post-api-v1-surveys).

**Example response**

`application/json`

```json
{
  "messageCode": "surveyNameAlreadyExists",
  "message": "string",
  "errors": [
    {}
  ]
}
```

### Example request

```bash
curl 'https://api.subrite.no/api/v1/surveys/{id}/copy' \
  --request POST \
  --header 'Authorization: Bearer <token>'
```

### Example response

201 · `application/json`

```json
{
  "id": "string",
  "name": "string",
  "status": "draft",
  "formJson": {},
  "themeJson": {},
  "completionJson": {},
  "startDate": "2019-08-24T14:15:22Z",
  "endDate": "2019-08-24T14:15:22Z",
  "publishedAt": "2019-08-24T14:15:22Z",
  "stoppedAt": "2019-08-24T14:15:22Z",
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z",
  "createdByUserId": 0,
  "updatedByUserId": 0,
  "responseCount": 0
}
```

<a id="get-api-v1-surveys-surveyid-analytics"></a>
## Get aggregated analytics for a survey

`GET /api/v1/surveys/{surveyId}/analytics`

**Authentication:** Bearer token (JWT)

### Parameters

| Name | In | Type | Description |
| --- | --- | --- | --- |
| `surveyId` (Required) | path | `string` |   |
| `timePeriod` | query | `string` | Time period filter for analytics data · Allowed values: `"all_time"`, `"last_7_days"`, `"last_30_days"` · Default: `"all_time"` |
| `isComplete` | query | `boolean` | Filter by completion status |

### Responses

#### 200

Content type: `application/json` · `SurveyAnalyticsResponseDto`

| Name | Type | Description |
| --- | --- | --- |
| `summary` (Required) | `AnalyticsSummaryDto` |   |
| `summary.totalResponses` (Required) | `number` |   |
| `summary.completed` (Required) | `number` |   |
| `summary.incomplete` (Required) | `number` |   |
| `summary.completionRate` (Required) | `number` |   |
| `questions` (Required) | `array of QuestionAnalyticsItemDto` |   |
| `questions[].name` (Required when parent is present) | `string` |   |
| `questions[].type` (Required when parent is present) | `string` |   |
| `questions[].title` (Required when parent is present) | `string` |   |
| `questions[].choices` (Required when parent is present) | `array of string` |   |
| `questions[].position` (Required when parent is present) | `number` |   |
| `questions[].totalQuestions` (Required when parent is present) | `number` |   |
| `questions[].rateMin` | `number` |   |
| `questions[].rateMax` | `number` |   |
| `questions[].rows` | `array of string` |   |
| `questions[].columns` | `array of string` |   |
| `questions[].totalResponses` (Required when parent is present) | `number` | Responses that answered this specific question |
| `questions[].distribution` (Required when parent is present) | `array of QuestionDistributionDto` |   |
| `questions[].distribution[].label` (Required when parent is present) | `string` |   |
| `questions[].distribution[].count` (Required when parent is present) | `number` |   |
| `questions[].textResponses` | `array of TextResponseDto` |   |
| `questions[].textResponses[].id` (Required when parent is present) | `string` |   |
| `questions[].textResponses[].text` (Required when parent is present) | `string` |   |
| `questions[].textResponses[].submittedAt` (Required when parent is present) | `string` |   |

#### 401

unauthorized

#### 404

Content type: `application/json` · `ErrorResponse`

surveyNotFound

Same fields as [Get a single survey by ID (404)](https://www.subrite.no/developers/surveys?md=true#get-api-v1-surveys-id).

**Example response**

`application/json`

```json
{
  "messageCode": "surveyNotFound",
  "message": "string",
  "errors": [
    {}
  ]
}
```

### Example request

```bash
curl 'https://api.subrite.no/api/v1/surveys/{surveyId}/analytics' \
  --header 'Authorization: Bearer <token>'
```

### Example response

200 · `application/json`

```json
{
  "summary": {
    "totalResponses": 0,
    "completed": 0,
    "incomplete": 0,
    "completionRate": 0
  },
  "questions": [
    {
      "choices": [],
      "rows": [],
      "columns": [],
      "distribution": [],
      "textResponses": []
    }
  ]
}
```

<a id="get-api-v1-surveys-surveyid-text-responses"></a>
## Get paginated text responses for a specific question

`GET /api/v1/surveys/{surveyId}/text-responses`

**Authentication:** Bearer token (JWT)

### Parameters

| Name | In | Type | Description |
| --- | --- | --- | --- |
| `surveyId` (Required) | path | `string` |   |
| `page` | query | `number` | Default: `1` · `minimum`: `1` |
| `take` | query | `number` | Default: `10` · `minimum`: `1`, `maximum`: `50` |
| `orderBy` | query | `string` | Allowed values: `"createdAt"`, `"id"`, `"updatedAt"` · Default: `"createdAt"` |
| `orderDirection` | query | `string` | Allowed values: `"asc"`, `"desc"` · Default: `"desc"` |
| `questionName` (Required) | query | `string` | Question name to fetch text responses for · `maxLength`: `255` |
| `timePeriod` | query | `string` | Time period filter · Allowed values: `"all_time"`, `"last_7_days"`, `"last_30_days"` · Default: `"all_time"` |
| `isComplete` | query | `boolean` | Filter by completion status |

### Responses

#### 200

Content type: `application/json` · `TextResponseDtoPaginated`

| Name | Type | Description |
| --- | --- | --- |
| `items` (Required) | `array of TextResponseDto` |   |
| `items[].id` (Required when parent is present) | `string` |   |
| `items[].text` (Required when parent is present) | `string` |   |
| `items[].submittedAt` (Required when parent is present) | `string` |   |
| `meta` (Required) | `PageMeta` |   |
| `meta.page` (Required) | `number` |   |
| `meta.take` (Required) | `number` |   |
| `meta.count` (Required) | `number` |   |
| `meta.pageCount` (Required) | `number` |   |
| `meta.hasPreviousPage` (Required) | `boolean` |   |
| `meta.hasNextPage` (Required) | `boolean` |   |

#### 401

unauthorized

#### 404

Content type: `application/json` · `ErrorResponse`

surveyNotFound

Same fields as [Get a single survey by ID (404)](https://www.subrite.no/developers/surveys?md=true#get-api-v1-surveys-id).

**Example response**

`application/json`

```json
{
  "messageCode": "surveyNotFound",
  "message": "string",
  "errors": [
    {}
  ]
}
```

### Example request

```bash
curl 'https://api.subrite.no/api/v1/surveys/{surveyId}/text-responses?questionName=%3CquestionName%3E' \
  --header 'Authorization: Bearer <token>'
```

### Example response

200 · `application/json`

```json
{
  "items": [
    {}
  ],
  "meta": {
    "page": 0,
    "take": 0,
    "count": 0,
    "pageCount": 0,
    "hasPreviousPage": true,
    "hasNextPage": true
  }
}
```

<a id="get-api-v1-surveys-surveyid-responses"></a>
## List responses for a survey (paginated)

`GET /api/v1/surveys/{surveyId}/responses`

**Authentication:** Bearer token (JWT)

### Parameters

| Name | In | Type | Description |
| --- | --- | --- | --- |
| `surveyId` (Required) | path | `string` |   |
| `page` | query | `number` | Default: `1` · `minimum`: `1` |
| `take` | query | `number` | Default: `10` · `minimum`: `1`, `maximum`: `50` |
| `orderBy` | query | `string` | Allowed values: `"createdAt"`, `"id"`, `"updatedAt"` · Default: `"createdAt"` |
| `orderDirection` | query | `string` | Allowed values: `"asc"`, `"desc"` · Default: `"desc"` |
| `isComplete` | query | `boolean` | Filter by completion status |
| `createdAfter` | query | `string` | Filter responses created after this date (ISO 8601) |

### Responses

#### 200

Content type: `application/json` · `SurveyResponseItemDtoPaginated`

| Name | Type | Description |
| --- | --- | --- |
| `items` (Required) | `array of SurveyResponseItemDto` |   |
| `items[].id` (Required when parent is present) | `string` |   |
| `items[].answers` (Required when parent is present) | `object` |   |
| `items[].isComplete` (Required when parent is present) | `boolean` |   |
| `items[].completedAt` | `string (date-time)` | Can be null |
| `items[].progress` | `object` | Can be null |
| `items[].surveyId` (Required when parent is present) | `string` |   |
| `items[].userId` | `number` | Can be null |
| `items[].createdAt` (Required when parent is present) | `string (date-time)` |   |
| `items[].updatedAt` (Required when parent is present) | `string (date-time)` |   |
| `meta` (Required) | `PageMeta` |   |
| `meta.page` (Required) | `number` |   |
| `meta.take` (Required) | `number` |   |
| `meta.count` (Required) | `number` |   |
| `meta.pageCount` (Required) | `number` |   |
| `meta.hasPreviousPage` (Required) | `boolean` |   |
| `meta.hasNextPage` (Required) | `boolean` |   |

#### 401

unauthorized

#### 404

Content type: `application/json` · `ErrorResponse`

surveyNotFound

Same fields as [Get a single survey by ID (404)](https://www.subrite.no/developers/surveys?md=true#get-api-v1-surveys-id).

**Example response**

`application/json`

```json
{
  "messageCode": "surveyNotFound",
  "message": "string",
  "errors": [
    {}
  ]
}
```

### Example request

```bash
curl 'https://api.subrite.no/api/v1/surveys/{surveyId}/responses' \
  --header 'Authorization: Bearer <token>'
```

### Example response

200 · `application/json`

```json
{
  "items": [
    {
      "answers": {},
      "progress": {}
    }
  ],
  "meta": {
    "page": 0,
    "take": 0,
    "count": 0,
    "pageCount": 0,
    "hasPreviousPage": true,
    "hasNextPage": true
  }
}
```

<a id="post-api-v1-surveys-surveyid-responses"></a>
## Submit a new survey response (public)

`POST /api/v1/surveys/{surveyId}/responses`

### Parameters

| Name | In | Type | Description |
| --- | --- | --- | --- |
| `surveyId` (Required) | path | `string` |   |
| `x-survey-session` | header | `string (uuid)` | Opaque per-respondent session id used to detect a duplicate submission. Must be a UUID; a malformed value is rejected with 400 rather than ignored, since silently dropping it would silently disable duplicate protection. Omit it to skip duplicate detection. |

### Request body

Content type: `application/json` · Required · `CreateSurveyResponseDto`

| Name | Type | Description |
| --- | --- | --- |
| `answers` (Required) | `object` | Response answers as JSON object |
| `isComplete` | `boolean` | Whether the response is complete |
| `progress` | `object` | Progress tracking data |

**Example request body**

`application/json`

```json
{
  "answers": {},
  "isComplete": true,
  "progress": {}
}
```

### Responses

#### 201

Content type: `application/json` · `SurveyResponseItemDto`

| Name | Type | Description |
| --- | --- | --- |
| `id` (Required) | `string` |   |
| `answers` (Required) | `object` |   |
| `isComplete` (Required) | `boolean` |   |
| `completedAt` | `string (date-time)` | Can be null |
| `progress` | `object` | Can be null |
| `surveyId` (Required) | `string` |   |
| `userId` | `number` | Can be null |
| `createdAt` (Required) | `string (date-time)` |   |
| `updatedAt` (Required) | `string (date-time)` |   |

#### 400

Content type: `application/json` · `ErrorResponse`

surveyNotAcceptingResponses \| surveyAuthRequired

| Name | Type | Description |
| --- | --- | --- |
| `messageCode` (Required) | `string` | Allowed values: `"surveyNotAcceptingResponses"` |
| `message` | `string` |   |
| `errors` (Required) | `array of FieldError` |   |
| `errors[].field` (Required when parent is present) | `string` |   |
| `errors[].fieldValue` (Required when parent is present) | `string` |   |
| `errors[].identifier` (Required when parent is present) | `string` |   |
| `errors[].identifierValue` (Required when parent is present) | `string` |   |
| `errors[].messageCode` (Required when parent is present) | `string` |   |
| `errors[].message` | `string` |   |
| `errors[].errorType` (Required when parent is present) | `string` |   |

**Example response**

`application/json`

```json
{
  "messageCode": "surveyNotAcceptingResponses",
  "message": "string",
  "errors": [
    {}
  ]
}
```

#### 404

Content type: `application/json` · `ErrorResponse`

surveyNotFound

Same fields as [Get a single survey by ID (404)](https://www.subrite.no/developers/surveys?md=true#get-api-v1-surveys-id).

**Example response**

`application/json`

```json
{
  "messageCode": "surveyNotFound",
  "message": "string",
  "errors": [
    {}
  ]
}
```

#### 409

Content type: `application/json` · `ErrorResponse`

surveyAlreadySubmitted

| Name | Type | Description |
| --- | --- | --- |
| `messageCode` (Required) | `string` | Allowed values: `"surveyAlreadySubmitted"` |
| `message` | `string` |   |
| `errors` (Required) | `array of FieldError` |   |
| `errors[].field` (Required when parent is present) | `string` |   |
| `errors[].fieldValue` (Required when parent is present) | `string` |   |
| `errors[].identifier` (Required when parent is present) | `string` |   |
| `errors[].identifierValue` (Required when parent is present) | `string` |   |
| `errors[].messageCode` (Required when parent is present) | `string` |   |
| `errors[].message` | `string` |   |
| `errors[].errorType` (Required when parent is present) | `string` |   |

**Example response**

`application/json`

```json
{
  "messageCode": "surveyAlreadySubmitted",
  "message": "string",
  "errors": [
    {}
  ]
}
```

#### 429

Content type: `application/json` · `ErrorResponse`

surveyRateLimitExceeded \| surveyFloodLimitExceeded

| Name | Type | Description |
| --- | --- | --- |
| `messageCode` (Required) | `string` | Allowed values: `"surveyRateLimitExceeded"` |
| `message` | `string` |   |
| `errors` (Required) | `array of FieldError` |   |
| `errors[].field` (Required when parent is present) | `string` |   |
| `errors[].fieldValue` (Required when parent is present) | `string` |   |
| `errors[].identifier` (Required when parent is present) | `string` |   |
| `errors[].identifierValue` (Required when parent is present) | `string` |   |
| `errors[].messageCode` (Required when parent is present) | `string` |   |
| `errors[].message` | `string` |   |
| `errors[].errorType` (Required when parent is present) | `string` |   |

**Example response**

`application/json`

```json
{
  "messageCode": "surveyRateLimitExceeded",
  "message": "string",
  "errors": [
    {}
  ]
}
```

#### 503

Content type: `application/json` · `ErrorResponse`

surveySubmissionTemporarilyUnavailable

| Name | Type | Description |
| --- | --- | --- |
| `messageCode` (Required) | `string` | Allowed values: `"surveySubmissionTemporarilyUnavailable"` |
| `message` | `string` |   |
| `errors` (Required) | `array of FieldError` |   |
| `errors[].field` (Required when parent is present) | `string` |   |
| `errors[].fieldValue` (Required when parent is present) | `string` |   |
| `errors[].identifier` (Required when parent is present) | `string` |   |
| `errors[].identifierValue` (Required when parent is present) | `string` |   |
| `errors[].messageCode` (Required when parent is present) | `string` |   |
| `errors[].message` | `string` |   |
| `errors[].errorType` (Required when parent is present) | `string` |   |

**Example response**

`application/json`

```json
{
  "messageCode": "surveySubmissionTemporarilyUnavailable",
  "message": "string",
  "errors": [
    {}
  ]
}
```

### Example request

```bash
curl 'https://api.subrite.no/api/v1/surveys/{surveyId}/responses' \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "answers": {},
  "isComplete": true,
  "progress": {}
}'
```

### Example response

201 · `application/json`

```json
{
  "id": "string",
  "answers": {},
  "isComplete": true,
  "completedAt": "2019-08-24T14:15:22Z",
  "progress": {},
  "surveyId": "string",
  "userId": 0,
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}
```

<a id="get-api-v1-surveys-surveyid-responses-id"></a>
## Get a single survey response

`GET /api/v1/surveys/{surveyId}/responses/{id}`

**Authentication:** Bearer token (JWT)

### Parameters

| Name | In | Type | Description |
| --- | --- | --- | --- |
| `surveyId` (Required) | path | `string` |   |
| `id` (Required) | path | `string` |   |

### Responses

#### 200

Content type: `application/json` · `SurveyResponseItemDto`

Same fields as [Submit a new survey response (public) (201)](https://www.subrite.no/developers/surveys?md=true#post-api-v1-surveys-surveyid-responses).

#### 401

unauthorized

#### 404

Content type: `application/json` · `ErrorResponse`

surveyNotFound \| surveyResponseNotFound

Same fields as [Get a single survey by ID (404)](https://www.subrite.no/developers/surveys?md=true#get-api-v1-surveys-id).

**Example response**

`application/json`

```json
{
  "messageCode": "surveyNotFound",
  "message": "string",
  "errors": [
    {}
  ]
}
```

### Example request

```bash
curl 'https://api.subrite.no/api/v1/surveys/{surveyId}/responses/{id}' \
  --header 'Authorization: Bearer <token>'
```

### Example response

200 · `application/json`

```json
{
  "id": "string",
  "answers": {},
  "isComplete": true,
  "completedAt": "2019-08-24T14:15:22Z",
  "progress": {},
  "surveyId": "string",
  "userId": 0,
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}
```

<a id="patch-api-v1-surveys-surveyid-responses-id"></a>
## Update an in-progress survey response (public partial save)

`PATCH /api/v1/surveys/{surveyId}/responses/{id}`

### Parameters

| Name | In | Type | Description |
| --- | --- | --- | --- |
| `surveyId` (Required) | path | `string` |   |
| `id` (Required) | path | `string` |   |
| `x-survey-session` | header | `string (uuid)` | Opaque per-respondent session id used to detect a duplicate submission. Must be a UUID; a malformed value is rejected with 400 rather than ignored, since silently dropping it would silently disable duplicate protection. Omit it to skip duplicate detection. |

### Request body

Content type: `application/json` · Required · `UpdateSurveyResponseDto`

| Name | Type | Description |
| --- | --- | --- |
| `answers` | `object` | Response answers as JSON object |
| `isComplete` | `boolean` | Whether the response is complete |
| `progress` | `object` | Progress tracking data |

**Example request body**

`application/json`

```json
{
  "answers": {},
  "isComplete": true,
  "progress": {}
}
```

### Responses

#### 200

Content type: `application/json` · `SurveyResponseItemDto`

Same fields as [Submit a new survey response (public) (201)](https://www.subrite.no/developers/surveys?md=true#post-api-v1-surveys-surveyid-responses).

#### 400

Content type: `application/json` · `ErrorResponse`

surveyNotAcceptingResponses \| surveyResponseAlreadyCompleted

Same fields as [Submit a new survey response (public) (400)](https://www.subrite.no/developers/surveys?md=true#post-api-v1-surveys-surveyid-responses).

**Example response**

`application/json`

```json
{
  "messageCode": "surveyNotAcceptingResponses",
  "message": "string",
  "errors": [
    {}
  ]
}
```

#### 404

Content type: `application/json` · `ErrorResponse`

surveyNotFound \| surveyResponseNotFound

Same fields as [Get a single survey by ID (404)](https://www.subrite.no/developers/surveys?md=true#get-api-v1-surveys-id).

**Example response**

`application/json`

```json
{
  "messageCode": "surveyNotFound",
  "message": "string",
  "errors": [
    {}
  ]
}
```

#### 409

Content type: `application/json` · `ErrorResponse`

surveyAlreadySubmitted

Same fields as [Submit a new survey response (public) (409)](https://www.subrite.no/developers/surveys?md=true#post-api-v1-surveys-surveyid-responses).

**Example response**

`application/json`

```json
{
  "messageCode": "surveyAlreadySubmitted",
  "message": "string",
  "errors": [
    {}
  ]
}
```

#### 429

Content type: `application/json` · `ErrorResponse`

surveyFloodLimitExceeded

| Name | Type | Description |
| --- | --- | --- |
| `messageCode` (Required) | `string` | Allowed values: `"surveyFloodLimitExceeded"` |
| `message` | `string` |   |
| `errors` (Required) | `array of FieldError` |   |
| `errors[].field` (Required when parent is present) | `string` |   |
| `errors[].fieldValue` (Required when parent is present) | `string` |   |
| `errors[].identifier` (Required when parent is present) | `string` |   |
| `errors[].identifierValue` (Required when parent is present) | `string` |   |
| `errors[].messageCode` (Required when parent is present) | `string` |   |
| `errors[].message` | `string` |   |
| `errors[].errorType` (Required when parent is present) | `string` |   |

**Example response**

`application/json`

```json
{
  "messageCode": "surveyFloodLimitExceeded",
  "message": "string",
  "errors": [
    {}
  ]
}
```

#### 503

Content type: `application/json` · `ErrorResponse`

surveySubmissionTemporarilyUnavailable

Same fields as [Submit a new survey response (public) (503)](https://www.subrite.no/developers/surveys?md=true#post-api-v1-surveys-surveyid-responses).

**Example response**

`application/json`

```json
{
  "messageCode": "surveySubmissionTemporarilyUnavailable",
  "message": "string",
  "errors": [
    {}
  ]
}
```

### Example request

```bash
curl 'https://api.subrite.no/api/v1/surveys/{surveyId}/responses/{id}' \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --data '{
  "answers": {},
  "isComplete": true,
  "progress": {}
}'
```

### Example response

200 · `application/json`

```json
{
  "id": "string",
  "answers": {},
  "isComplete": true,
  "completedAt": "2019-08-24T14:15:22Z",
  "progress": {},
  "surveyId": "string",
  "userId": 0,
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}
```

<a id="get-api-v1-surveys-id-form"></a>
## Get published survey form (public respondent view)

`GET /api/v1/surveys/{id}/form`

### Parameters

| Name | In | Type | Description |
| --- | --- | --- | --- |
| `id` (Required) | path | `string` |   |

### Responses

#### 200

Content type: `application/json` · `SurveyPublicFormDto`

| Name | Type | Description |
| --- | --- | --- |
| `id` (Required) | `string` |   |
| `name` (Required) | `string` |   |
| `formJson` | `object` | Can be null |
| `themeJson` | `object` | Can be null |
| `completionJson` | `object` | Can be null |

#### 404

Content type: `application/json` · `ErrorResponse`

surveyNotFound

Same fields as [Get a single survey by ID (404)](https://www.subrite.no/developers/surveys?md=true#get-api-v1-surveys-id).

**Example response**

`application/json`

```json
{
  "messageCode": "surveyNotFound",
  "message": "string",
  "errors": [
    {}
  ]
}
```

### Example request

```bash
curl 'https://api.subrite.no/api/v1/surveys/{id}/form'
```

### Example response

200 · `application/json`

```json
{
  "id": "string",
  "name": "string",
  "formJson": {},
  "themeJson": {},
  "completionJson": {}
}
```