Simpleforms Public API v1

https://api.simpleforms.ru/

Public API v1 предназначен для интеграций: чтения проектов, заказов, заданий и заполненных анкет, получения сводки черновика шаблона, а также постановки отчётов на формирование.

Ключ API можно получить в разделе “Настройки компании” (раздел доступен пользователям с ролью Администратор).

Аутентификация

Аутентификация осуществляется через заголовок X-API-Key. Этот заголовок обязателен для всех запросов.

GET /api/projects?api-version=1.0 HTTP/1.1
Host: api.simpleforms.ru
X-API-Key: your_api_key_here

Версия API

Для всех маршрутов v1 передавайте query-параметр api-version=1.0. Версия в путь не входит: используются маршруты вида /api/projects, /api/forms и т. п.

GET https://api.simpleforms.ru/api/projects?api-version=1.0

Пагинация

Списки проектов, заказов, заданий и отчётов используют постраничную пагинацию: pageIndex начинается с 0, pageSize по умолчанию равен 10 и ограничивается сервером значением 100. Ответ содержит data, totalCount и totalPages.

Список заполненных анкет использует курсорную пагинацию: pageSize — от 1 до 50 (по умолчанию 50), следующую страницу запрашивают с afterId, равным nextCursor из предыдущего ответа.

Формат дат

Все даты в запросах и ответах должны быть в формате RFC 3339 (например, 2017-07-21T17:32:28Z), где время указывается в UTC с суффиксом Z.

Проекты (Projects)

Список проектов

GET /api/projects

Получить постраничный список проектов.

Параметры запроса:

pageSize (integer, optional): Количество элементов на одной странице результатов. По умолчанию: 10.
pageIndex (integer, optional): Индекс страницы результатов. По умолчанию: 0.
api-version (string, required): Версия API в формате 'major.minor'. Пример: "1.0".
status (integer, optional): Статус проекта. По умолчанию: <не указано>. Возможные значения:
- 0: initial
- 1: inprogress
- 2: archive
- 3: temporary
- 4: testing
- 5: insettings
- 10: changestatuses
deadlineFrom (string, optional): Плановая дата завершения проекта 'от' UTC. Формат: RFC 3339. Пример: 2017-07-21T17:32:28Z. По умолчанию: <не указано>
deadlineTo (string, optional): Плановая дата завершения проекта 'до' UTC. Формат: RFC 3339. Пример: 2017-07-21T17:32:28Z. По умолчанию: <не указано>

Пример ответа (200 OK):

{
  "data": [
    {
      "id": "uuid", // Идентификатор проекта
      "name": "string", // Название проекта
      "number": 0, // Номер проекта
      "currentCount": 0, // Текущее количество целевых анкет
      "count": 0, // Заданное количество целевых анкет
      "status": 0, // Статус проекта
      "deadline": "2017-07-21T17:32:28Z" // Плановая дата завершения проекта
    }
  ],
  "totalCount": 0, // Всего записей
  "totalPages": 0 // Всего страниц
}

Коды ошибок:

400 Bad Request: Неверный запрос. Возвращается объект ProblemDetails:
{ "type": "string", "title": "string", "status": 400, "detail": "string", "instance": "string" }
401 Unauthorized: Отсутствует или неверный API-ключ.
403 Forbidden: Недостаточно прав для доступа.

Информация по проекту

GET /api/projects/{id}

Получить информацию по проекту.

Параметры пути:

id (string, required): Идентификатор проекта (UUID).

Параметры запроса:

api-version (string, required): Версия API в формате 'major.minor'. Пример: "1.0".

Пример ответа (200 OK):

{
  "id": "uuid", // Идентификатор проекта
  "name": "string", // Название проекта
  "number": 0, // Номер проекта
  "currentCount": 0, // Текущее количество целевых анкет
  "count": 0, // Заданное количество целевых анкет
  "status": 0, // Статус проекта
  "deadline": "2017-07-21T17:32:28Z" // Плановая дата завершения проекта
}

Коды ошибок:

400 Bad Request: Неверный формат идентификатора. Возвращается объект ProblemDetails.
401 Unauthorized: Отсутствует или неверный API-ключ.
403 Forbidden: Недостаточно прав для доступа.
404 Not Found: Проект с указанным идентификатором не найден.

Заказы (GlobalOrders)

Список заказов

GET /api/globalorders

Получить постраничный список заказов.

Параметры запроса:

pageSize (integer, optional): Количество элементов на одной странице результатов. По умолчанию: 10.
pageIndex (integer, optional): Индекс страницы результатов. По умолчанию: 0.
api-version (string, required): Версия API в формате 'major.minor'. Пример: "1.0".
status (integer, optional): Статус заказа. По умолчанию: <не указано>. Возможные значения:
- 0: initial
- 1: inprogress
- 2: archive
- 3: insettings
projectId (string, optional): Идентификатор проекта (UUID). По умолчанию: <не указано>

Пример ответа (200 OK):

{
  "data": [
    {
      "id": "uuid", // Идентификатор заказа
      "projectId": "uuid", // Идентификатор проекта
      "currentCount": 0, // Текущее количество целевых анкет
      "count": 0, // Заданное количество целевых анкет
      "status": 0, // Статус заказа
      "isOwn": true, // Признак собственного заказа
      "isCawi": true, // Признак CAWI заказа
      "partner": "string", // Партнер
      "partnerId": "uuid" // Идентификатор партнера
    }
  ],
  "totalCount": 0, // Всего записей
  "totalPages": 0 // Всего страниц
}

Коды ошибок:

400 Bad Request: Неверный запрос. Возвращается объект ProblemDetails.
401 Unauthorized: Отсутствует или неверный API-ключ.
403 Forbidden: Недостаточно прав для доступа.

Информация по заказу

GET /api/globalorders/{id}

Получить информацию по заказу.

Параметры пути:

id (string, required): Идентификатор заказа (UUID).

Параметры запроса:

api-version (string, required): Версия API в формате 'major.minor'. Пример: "1.0".

Пример ответа (200 OK):

{
  "id": "uuid", // Идентификатор заказа
  "projectId": "uuid", // Идентификатор проекта
  "currentCount": 0, // Текущее количество целевых анкет
  "count": 0, // Заданное количество целевых анкет
  "status": 0, // Статус заказа
  "isOwn": true, // Признак собственного заказа
  "isCawi": true, // Признак CAWI заказа
  "partner": "string", // Партнер
  "partnerId": "uuid" // Идентификатор партнера
}

Коды ошибок:

400 Bad Request: Неверный формат идентификатора. Возвращается объект ProblemDetails.
401 Unauthorized: Отсутствует или неверный API-ключ.
403 Forbidden: Недостаточно прав для доступа.
404 Not Found: Заказ с указанным идентификатором не найден.

Задания (LocalOrders)

Список заданий

GET /api/globalorders/{id}/localorders

Получить постраничный список заданий.

Параметры пути:

id (string, required): Идентификатор заказа (UUID).

Параметры запроса:

pageSize (integer, optional): Количество элементов на одной странице результатов. По умолчанию: 10.
pageIndex (integer, optional): Индекс страницы результатов. По умолчанию: 0.
api-version (string, required): Версия API в формате 'major.minor'. Пример: "1.0".
status (integer, optional): Статус задания. По умолчанию: <не указано>. Возможные значения:
- 0: initial
- 1: inprogress
- 2: archive
- 3: isready
term (string, optional): Строка для поиска. По умолчанию: <не указано>

Пример ответа (200 OK):

{
  "data": [
    {
      "id": "uuid", // Идентификатор задания
      "globalOrderId": "uuid", // Идентификатор заказа
      "count": 0, // Заданное количество целевых анкет
      "status": 0, // Статус задания
      "interviewer": "string", // Интервьюер
      "currentCount": 0 // Текущее количество целевых анкет
    }
  ],
  "totalCount": 0, // Всего записей
  "totalPages": 0 // Всего страниц
}

Коды ошибок:

400 Bad Request: Неверный запрос. Возвращается объект ProblemDetails.
401 Unauthorized: Отсутствует или неверный API-ключ.
403 Forbidden: Недостаточно прав для доступа.
404 Not Found: Заказ с указанным идентификатором не найден.

Информация по заданию

GET /api/localorders/{id}

Получить информацию по заданию.

Параметры пути:

id (string, required): Идентификатор задания (UUID).

Параметры запроса:

api-version (string, required): Версия API в формате 'major.minor'. Пример: "1.0".

Пример ответа (200 OK):

{
  "id": "uuid", // Идентификатор задания
  "globalOrderId": "uuid", // Идентификатор заказа
  "count": 0, // Заданное количество целевых анкет
  "status": 0, // Статус задания
  "interviewer": "string", // Интервьюер
  "currentCount": 0 // Текущее количество целевых анкет
}

Коды ошибок:

400 Bad Request: Неверный формат идентификатора. Возвращается объект ProblemDetails.
401 Unauthorized: Отсутствует или неверный API-ключ.
403 Forbidden: Недостаточно прав для доступа.
404 Not Found: Задание с указанным идентификатором не найдено.

Заполненные анкеты (Forms)

Список заполненных анкет

GET /api/forms

Получить страницу заполненных анкет с нормализованными ответами.

Область выборки: необходимо передать ровно один из параметров projectId, globalOrderId или localOrderId. Все три значения имеют формат UUID.

Параметры запроса:

api-version (string, required): 1.0.
projectId / globalOrderId / localOrderId (UUID): ровно одна область выборки.
afterId (integer, optional): курсор из поля nextCursor предыдущего ответа.
pageSize (integer, optional): от 1 до 50, по умолчанию 50.
includeIncomplete (boolean, optional): включать незавершённые анкеты; по умолчанию false.
includeScreeners (boolean, optional): включать отборочные анкеты; по умолчанию false.
numberFrom / numberTo (integer, optional): включительные границы диапазона номеров анкет.
questionCodes (string, optional): коды вопросов через ;; если параметр не задан, возвращаются ответы на все вопросы.

Пример запроса:

GET /api/forms?api-version=1.0&projectId=11111111-1111-1111-1111-111111111111&pageSize=50 HTTP/1.1
Host: api.simpleforms.ru
X-API-Key: your_api_key_here

Пример ответа (200 OK):

{
  "items": [
    {
      "id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
      "number": 123,
      "templateVersion": 4,
      "fillerEmail": "interviewer@example.com",
      "localOrderId": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
      "globalOrderId": "cccccccc-cccc-cccc-cccc-cccccccccccc",
      "projectId": "11111111-1111-1111-1111-111111111111",
      "controlStatus": "Accepted",
      "sourceType": "Cawi",
      "isIncomplete": false,
      "isScreener": false,
      "isOverquota": false,
      "submitDateTime": "2026-09-10T08:30:00Z",
      "startedAt": "2026-09-10T08:20:00Z",
      "completedAt": "2026-09-10T08:30:00Z",
      "offset": "+05:00",
      "latitude": null,
      "longitude": null,
      "answers": [
        {
          "questionCode": "Q1",
          "questionType": "Check",
          "cycle": null,
          "startedAt": "2026-09-10T08:21:00+05:00",
          "completedAt": "2026-09-10T08:21:10+05:00",
          "locale": "ru-ru",
          "values": [
            {
              "answerCode": "A1",
              "rowCode": null,
              "cellValue": null,
              "value": null
            }
          ]
        }
      ]
    }
  ],
  "nextCursor": 123,
  "hasNextPage": true
}

Коды ошибок:

400 Bad Request: не задана область выборки, задано несколько областей или pageSize вне диапазона 1–50.
401 Unauthorized: отсутствует или неверный API-ключ.
403 Forbidden: нет доступа к выбранной области.
404 Not Found: указанная область не найдена.

Шаблоны (Templates)

Сводка черновика шаблона

GET /api/templates/{id}

Получить текущую сводку черновика шаблона: версию, ревизию и hash, языки, вопросы и настроенные конечные состояния. В публичном REST API v1 доступно только чтение этой сводки; операции редактирования шаблона в REST-контракт v1 не входят.

Параметры:

id (UUID, path, required): идентификатор шаблона.
api-version (string, query, required): 1.0.

Пример ответа (200 OK):

{
  "id": "dddddddd-dddd-dddd-dddd-dddddddddddd",
  "name": "Исследование",
  "status": 0,
  "templateVersion": 4,
  "draftRevision": 12,
  "temporaryDataHash": "sha256-hash",
  "languages": [
    {
      "id": 1,
      "name": "Русский",
      "locale": "ru-ru",
      "default": true,
      "published": true
    }
  ],
  "questions": [
    {
      "id": "eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee",
      "native": "Q1",
      "type": 3,
      "texts": {
        "1": "Первый вопрос"
      },
      "hasComplexConstraints": false
    }
  ],
  "configuredEndStates": [
    "default"
  ]
}

Коды ошибок:

401 Unauthorized: отсутствует или неверный API-ключ.
403 Forbidden: компании недоступно чтение/редактирование шаблонов через API.
404 Not Found: шаблон не найден в компании владельца API-ключа.

Отчеты (Reports)

Список отчетов

GET /api/reports

Получить постраничный список отчетов.

Параметры запроса:

pageSize (integer, optional): Количество элементов на одной странице результатов. По умолчанию: 10.
pageIndex (integer, optional): Индекс страницы результатов. По умолчанию: 0.
api-version (string, required): Версия API в формате 'major.minor'. Пример: "1.0".
isFailed (boolean, optional): Флаг, указывающий, завершено ли формирование отчета с ошибкой. По умолчанию: <не указано>
isCompleted (boolean, optional): Флаг, указывающий, завершено ли формирование отчета успешно. По умолчанию: <не указано>
createdOnUtcFrom (string, optional): Дата/время создания запроса для формирования отчета 'от' UTC. Формат: RFC 3339. Пример: 2017-07-21T17:32:28Z. По умолчанию: <не указано>
createdOnUtcTo (string, optional): Дата/время создания запроса для формирования отчета 'до' UTC. Формат: RFC 3339. Пример: 2017-07-21T17:32:28Z. По умолчанию: <не указано>

Пример ответа (200 OK):

{
  "data": [
    {
      "id": "uuid", // Идентификатор отчёта
      "isFailed": false, // Отчёт сформирован с ошибкой
      "isCompleted": true, // Отчёт сформирован успешно
      "createdOnUtc": "2017-07-21T17:32:28Z", // Дата/время создания запроса отчёта
      "type": 0, // Тип отчёта
      "name": "string" // Название отчёта
    }
  ],
  "totalCount": 0, // Всего записей
  "totalPages": 0 // Всего страниц
}

Коды ошибок:

400 Bad Request: Неверный запрос. Возвращается объект ProblemDetails.
401 Unauthorized: Отсутствует или неверный API-ключ.
403 Forbidden: Недостаточно прав для доступа.

Информация по отчету

GET /api/reports/{id}

Получить информацию по отчету.

Параметры пути:

id (string, required): Идентификатор отчета (UUID).

Параметры запроса:

api-version (string, required): Версия API в формате 'major.minor'. Пример: "1.0".

Пример ответа (200 OK):

{
  "links": ["string"], // Ссылки, полученные в результате генерации отчёта
  "id": "uuid", // Идентификатор отчёта
  "isFailed": false, // Отчёт сформирован с ошибкой
  "isCompleted": true, // Отчёт сформирован успешно
  "createdOnUtc": "2017-07-21T17:32:28Z", // Дата/время создания запроса отчёта
  "type": 0, // Тип отчёта
  "name": "string" // Название отчёта
}

Коды ошибок:

400 Bad Request: Неверный формат идентификатора. Возвращается объект ProblemDetails.
401 Unauthorized: Отсутствует или неверный API-ключ.
403 Forbidden: Недостаточно прав для доступа.
404 Not Found: Отчет с указанным идентификатором не найден.

Создание отчетов

Создание отчета по анкетам в формате DocX

POST /api/reports/surveyReport/toWord

Создать отчет по анкетам в формате DocX, возвращает идентификатор.

Параметры запроса:

api-version (string, required): Версия API в формате 'major.minor'. Пример: "1.0".

Тело запроса:

includeServiceData (boolean, optional): Включать служебные данные. По умолчанию: true
geolocationFormat (integer, optional): Формат геолокации. Значения определяются системой. По умолчанию: <координаты>
includeIncompleteSurveys (boolean, optional): Включать незавершенные анкеты. По умолчанию: true
includeQuestionDuration (boolean, optional): Включать длительность вопросов. По умолчанию: false
questionTiming (string, optional): Время заполнения. По умолчанию: <не указано>
locale (string, optional): Язык выгрузки. По умолчанию: <не указано>
objectId (string, required): Идентификатор сущности (UUID).
entityType (integer, optional): Тип сущности. Значения определяются системой. По умолчанию: <проект>
includeScreenerSurveys (boolean, optional): Включать нецелевые анкеты. По умолчанию: true
includeDeclinedSurveys (boolean, optional): Включать забракованные анкеты. По умолчанию: true
includeCommercialSecret (boolean, optional): Включать анкеты с коммерческой тайной. По умолчанию: true
timeZone (string, optional): Часовой пояс в формате ±HH:MM:SS[.fffffff]. Пример: "-05:00:00". По умолчанию: <не указано>
startReportDate (string, optional): Начало периода выгрузки. Формат: RFC 3339. Пример: 2017-07-21T17:32:28Z. По умолчанию: <не указано>
endReportDate (string, optional): Конец периода выгрузки. Формат: RFC 3339. Пример: 2017-07-21T17:32:28Z. По умолчанию: <не указано>
startNumber (integer, optional): Начало диапазона номеров анкет. По умолчанию: <не указано>
endNumber (integer, optional): Конец диапазона номеров анкет. По умолчанию: <не указано>

Пример тела запроса:

{
  "includeServiceData": true,
  "geolocationFormat": 0,
  "includeIncompleteSurveys": false,
  "includeQuestionDuration": true,
  "questionTiming": "string",
  "locale": "string",
  "objectId": "uuid",
  "entityType": 0,
  "includeScreenerSurveys": false,
  "includeDeclinedSurveys": true,
  "includeCommercialSecret": false,
  "timeZone": "-05:00:00",
  "startReportDate": "2017-07-21T17:32:28Z",
  "endReportDate": "2017-07-21T17:32:28Z",
  "startNumber": 1,
  "endNumber": 100
}

Пример ответа (200 OK):

{
  "id": "uuid" // Идентификатор созданного отчета
}

Коды ошибок:

400 Bad Request: Неверный запрос. Возвращается объект ProblemDetails.
401 Unauthorized: Отсутствует или неверный API-ключ.
403 Forbidden: Недостаточно прав для доступа.

Создание отчета по анкетам в формате Excel

POST /api/reports/surveyReport/toExcel

Создать отчет по анкетам в формате Excel, возвращает идентификатор.

Параметры запроса:

api-version (string, required): Версия API в формате 'major.minor'. Пример: "1.0".

Тело запроса:

templateVersion (integer, optional): Версия шаблона. По умолчанию: <текущая версия, указанная в проекте>
includeQuestionLog (boolean, optional): Включать лог вопросов. По умолчанию: true
analysisMethod (integer, optional): Метод анализа ответов. Значения определяются системой. По умолчанию: <дихотомия>
includeQuestionText (boolean, optional): Включать текст вопросов. По умолчанию: true
answerExportFormat (integer, optional): Формат выгрузки ответов. Значения определяются системой. По умолчанию: <кодами>
codeIdentification (integer, optional): Тип идентификации кода. Значения определяются системой. По умолчанию: <Id>
otherOptionExport (integer, optional): Обработка варианта "другое". Значения определяются системой. По умолчанию: <Один столбец>
multipleChoiceExport (integer, optional): Обработка множественного выбора. Значения определяются системой. По умолчанию: <Один столбец>
includeServiceData (boolean, optional): Включать служебные данные. По умолчанию: true
geolocationFormat (integer, optional): Формат геолокации. Значения определяются системой. По умолчанию: <координаты>
includeIncompleteSurveys (boolean, optional): Включать незавершенные анкеты. По умолчанию: true
includeQuestionDuration (boolean, optional): Включать длительность вопросов. По умолчанию: false
questionTiming (string, optional): Время заполнения. По умолчанию: <не указано>
locale (string, optional): Язык выгрузки. По умолчанию: <не указано>
objectId (string, required): Идентификатор сущности (UUID).
entityType (integer, optional): Тип сущности. Значения определяются системой. По умолчанию: <проект>
includeScreenerSurveys (boolean, optional): Включать нецелевые анкеты. По умолчанию: true
includeDeclinedSurveys (boolean, optional): Включать забракованные анкеты. По умолчанию: true
includeCommercialSecret (boolean, optional): Включать анкеты с коммерческой тайной. По умолчанию: true
timeZone (string, optional): Часовой пояс в формате ±HH:MM:SS[.fffffff]. Пример: "-05:00:00". По умолчанию: <не указано>
startReportDate (string, optional): Начало периода выгрузки. Формат: RFC 3339. Пример: 2017-07-21T17:32:28Z. По умолчанию: <не указано>
endReportDate (string, optional): Конец периода выгрузки. Формат: RFC 3339. Пример: 2017-07-21T17:32:28Z. По умолчанию: <не указано>
startNumber (integer, optional): Начало диапазона номеров анкет. По умолчанию: <не указано>
endNumber (integer, optional): Конец диапазона номеров анкет. По умолчанию: <не указано>

Пример тела запроса:

{
  "templateVersion": 1,
  "includeQuestionLog": true,
  "analysisMethod": 0,
  "includeQuestionText": false,
  "answerExportFormat": 0,
  "codeIdentification": 0,
  "otherOptionExport": 0,
  "multipleChoiceExport": 0,
  "includeServiceData": true,
  "geolocationFormat": 0,
  "includeIncompleteSurveys": false,
  "includeQuestionDuration": true,
  "questionTiming": "string",
  "locale": "string",
  "objectId": "uuid",
  "entityType": 0,
  "includeScreenerSurveys": false,
  "includeDeclinedSurveys": true,
  "includeCommercialSecret": false,
  "timeZone": "-05:00:00",
  "startReportDate": "2017-07-21T17:32:28Z",
  "endReportDate": "2017-07-21T17:32:28Z",
  "startNumber": 1,
  "endNumber": 100
}

Пример ответа (200 OK):

{
  "id": "uuid" // Идентификатор созданного отчета
}

Коды ошибок:

400 Bad Request: Неверный запрос. Возвращается объект ProblemDetails.
401 Unauthorized: Отсутствует или неверный API-ключ.
403 Forbidden: Недостаточно прав для доступа.

Создание отчета по анкетам в формате Json

POST /api/reports/surveyReport/toJson