# QUIZ Service API Documentation

## Components

### Quiz Model

    {
      "id": integer,          // Id of created quiz
      "qid": string,         // string id for customers
      "deleted": boolean,    // true if quiz deleted
      "archived": boolean,   // true if quiz archived
      "fingerprinting": boolean,  // set true for save deviceId
      "repeatable": boolean,     // set true for allow user to repeat quiz
      "note_prevented": boolean, // set true for save statistic of incomplete quiz passing
      "mail_notifications": boolean, // set true for mail notification for each quiz passing
      "unique_answers": boolean,    // set true for save statistics only for unique quiz passing
      "name": string,        // name of quiz. max 280 length
      "description": string, // description of quiz
      "config": string,      // config of quiz. serialized json for rules of quiz flow
      "status": string,      // status of quiz. allow only '', 'draft', 'template', 'stop', 'start'
      "limit": integer,      // limit is count of max quiz passing
      "due_to": integer,     // last time when quiz is valid. timestamp in seconds
      "time_of_passing": integer, // seconds to pass quiz
      "pausable": boolean,   // true if it is allowed for pause quiz
      "version": integer,    // version of quiz
      "version_comment": string, // version comment to version of quiz
      "parent_ids": integer[], // array of previous versions of quiz
      "created_at": string,  // time of creating
      "updated_at": string,  // time of last updating
      "question_cnt": integer, // count of questions
      "passed_count": integer, // count passings
      "average_time": integer, // average time of passing
      "super": boolean,      // set true if squiz realize group functionality
      "group_id": integer    // group of new quiz
    }

### Question Model

    {
      "id": integer,         // Id of created question
      "quiz_id": integer,    // relation to quiz
      "title": string,       // title of question. max 512 length
      "description": string, // description of question
      "type": string,        // status of question. allow only text, select, file, variant, images, varimg, emoji, date, number, page, rating
      "required": boolean,   // user must pass this question
      "deleted": boolean,    // true if question is deleted
      "page": integer,       // page if question
      "content": string,     // serialized json of created question
      "version": integer,    // version of quiz
      "parent_ids": integer[], // array of previous versions of quiz
      "created_at": string,  // time of creating
      "updated_at": string   // time of last updating
    }

### Answer Model

    {
      "Id": integer,         // id ответа
      "Content": string,     // контент ответа
      "QuestionId": integer, // id вопроса к которому ответ
      "QuizId": integer,     // id опроса к которому ответ
      "Fingerprint": string, // fingerprint
      "Session": string,     // сессия
      "Result": boolean,     // true or false?
      "CreatedAt": string,   // таймшап когда ответ создан
      "New": boolean,        // новый ответ?
      "Deleted": boolean     // удален?
    }

### LeadTarget Model

    {
      "ID": integer,         // primary key
      "AccountID": string,   // account identifier
      "Type": string,        // type of target (mail, telegram, whatsapp)
      "QuizID": integer,     // ID of the quiz
      "Target": string,      // target address
      "InviteLink": string,  // invitation link
      "Deleted": boolean,    // is deleted
      "CreatedAt": string    // creation timestamp
    }

### TgAccount Model

    {
      "ID": integer,         // primary key
      "ApiID": integer,      // Telegram API ID
      "ApiHash": string,     // Telegram API Hash
      "PhoneNumber": string, // phone number
      "Password": string,    // account password
      "Status": string,      // account status (active, inactive, ban)
      "Deleted": boolean,    // is deleted
      "CreatedAt": string    // creation timestamp
    }

## Quiz Endpoints

### Create Quiz

POST `/quiz/create`

Create a new quiz with specified parameters.

#### Security

This endpoint requires authentication.

#### Request Body:

    {
      "fingerprinting": boolean,  // set true for save deviceId
      "repeatable": boolean,     // set true for allow user to repeat quiz
      "note_prevented": boolean, // set true for save statistic of incomplete quiz passing
      "mail_notifications": boolean, // set true for mail notification for each quiz passing
      "unique_answers": boolean,    // set true for save statistics only for unique quiz passing
      "name": string,        // name of quiz. max 280 length
      "description": string, // description of quiz
      "config": string,      // config of quiz. serialized json for rules of quiz flow
      "status": string,      // status of quiz. allow only '', 'draft', 'template', 'stop', 'start'
      "limit": integer,      // limit is count of max quiz passing
      "due_to": integer,     // last time when quiz is valid. timestamp in seconds
      "time_of_passing": integer, // seconds to pass quiz
      "pausable": boolean,   // true if it is allowed for pause quiz
      "question_cnt": integer, // count of questions
      "super": boolean,      // set true if squiz realize group functionality
      "group_id": integer    // group of new quiz
    }

#### Responses:

##### 201 Created

Quiz successfully created. Returns the created quiz object.

    {
      "id": integer,
      "qid": string,
      "name": string,
      "description": string,
      // ... other quiz properties
    }

##### 422 Unprocessable Entity

Name field should have less than 280 characters.

##### 406 Not Acceptable

Status on creating must be only draft, template, stop, start or due to time must be lesser than now.

Allowed status values: '', 'draft', 'template', 'stop', 'start'

##### 409 Conflict

You can pause quiz only if it has deadline for passing.

##### 500 Internal Server Error

If you get any content string send it to developer.

### Get Quiz List

POST `/quiz/getList`

Get paginated list of quizzes with filtering options.

#### Request Body:

    {
      "limit": integer,
      "offset": integer,
      "from": integer,
      "to": integer,
      "search": string,
      "status": string,
      "deleted": boolean,
      "archived": boolean,
      "super": boolean,
      "group_id": integer
    }

#### Responses:

##### 200 OK

Returns list of quizzes with total count.

    {
      "count": integer,
      "items": [
        {
          "id": integer,
          "qid": string,
          // ... other quiz properties
        }
      ]
    }

##### 406 Not Acceptable

Inappropriate status, allowed only '', 'stop', 'start', 'draft', 'template', 'timeout', 'offlimit'.

##### 500 Internal Server Error

If you get any content string send it to developer.

## Question Endpoints

### Create Question

POST `/question/create`

Create a new question for a quiz.

## Results Endpoints

### Get Quiz Results

POST `/results/getResults/{quizId}`

Get list of quiz results with pagination.

#### Path Parameters:

`quizId` - ID of the quiz to get results for

#### Request Body:

    {
      "to": integer,         // таймштамп времени, до которого выбирать статистику. если 0 или не передано - этого ограничения нет
      "from": integer,       // таймштамп времени, после которого выбирать статистику. если 0 или не передано - этого ограничения нет
      "new": boolean,        // флаг, по которому вернутся только новые результаты, ещё не просмотренные пользователем
      "page": integer,       // номер страницы для пагинации
      "limit": integer       // размер страницы для пагинации
    }

#### Responses:

##### 200 OK

Returns paginated list of results.

    {
      "total_count": integer,  // общее количество элементов удволетворяющее фильтру
      "results": [
        {
          "content": string,   // содержимое ответа
          "id": integer,       // айдишник ответа
          "new": boolean,      // статус, был ли просмотрен ответ
          "created_at": string // время создания этого результата
        }
      ]
    }

### Export Results

POST `/results/{quizID}/export`

Export quiz results to CSV format.

#### Path Parameters:

`quizID` - ID of the quiz to export results from

#### Request Body:

    {
      "to": string,          // Дата окончания диапазона времени для экспорта результатов
      "from": string,        // Дата начала временного диапазона для экспорта результатов
      "new": boolean         // Экспортировать ли только новые результаты?
    }

#### Responses:

##### 200 OK

Returns CSV file with quiz results.

    Content-Type: text/csv

## Telegram Endpoints

### Create Telegram Account

POST `/telegram/create`

Authorize server in Telegram account.

#### Request Body:

    {
      "ApiID": integer,      // Telegram API ID
      "ApiHash": string,     // Telegram API Hash
      "PhoneNumber": string, // Phone number
      "Password": string     // Account password
    }

#### Responses:

##### 200 OK

Returns signature for code verification.

    {
      "signature": string    // Session identifier for code verification
    }

##### 409 Conflict

Account already exists and is active.

## Audience Endpoints

### Create Quiz Audience

POST `/quiz/{quizID}/auditory`

Create audience for a quiz.

#### Path Parameters:

`quizID` - ID of the quiz

#### Responses:

##### 200 OK

Returns ID of created audience.

    {
      "id": integer    // ID of created auditory
    }

## Statistics Endpoints

### Get Question Statistics

POST `/statistic/{quizID}/questions`

Get statistics for specific questions in a quiz.

## Account Endpoints

### Add Lead Target

POST `/account/leadtarget`

Add a target destination for lead notifications.