Integration of the quiz form with CRM Bitrix24

Integrating a Quiz Form with Bitrix24 CRM

A quiz form (a questionnaire with questions and answer choices) converts better than a standard inquiry form because it engages the user in a dialogue before requesting contact details. Quiz results carry information about the customer's needs — valuable data for a sales manager. The problem is that most quiz platforms (Marquiz, Qform, Tilda Quiz) send data to their own CRM or via email, without native integration with Bitrix24. The goal is to pass quiz answers into a Bitrix24 deal/lead so the manager sees not just "client filled out a form," but specific answers in context.

Integration Approaches

Option 1: Webhook from the quiz platform → Bitrix24. Most quiz platforms can send a webhook when a quiz is completed. Data arrives at your endpoint, and you create a lead via the Bitrix24 REST API.

Option 2: Custom quiz on the website → direct Bitrix24 REST integration. The quiz is built in-house (React/Vue), and the final step sends data directly via the REST API.

Option 3: Bitrix24 CRM forms with multi-step. A built-in Bitrix24 tool requiring no development. Limited in design customization.

Let us walk through Option 1, as it is the most common.

Webhook Handler: Marquiz → Bitrix24

Marquiz sends a POST request with a JSON payload when a quiz is completed:

{
  "quiz_id": "abc123",
  "quiz_name": "Window Selection",
  "contact": {
    "name": "Ivan",
    "phone": "+79161234567",
    "email": "[email protected]"
  },
  "answers": [
    {"question": "Room type", "answer": "Apartment"},
    {"question": "Number of windows", "answer": "3"},
    {"question": "Urgency", "answer": "Within a month"},
    {"question": "Budget", "answer": "50,000 – 100,000 RUB"}
  ],
  "result": "Standard Package",
  "utm": {
    "utm_source": "yandex",
    "utm_campaign": "windows_brand"
  }
}

Handler on your server (intermediary between Marquiz and Bitrix24):

// /local/api/quiz-webhook.php
require_once($_SERVER['DOCUMENT_ROOT'] . '/bitrix/modules/main/include/prolog_before.php');

header('Content-Type: application/json');

$payload = json_decode(file_get_contents('php://input'), true);

// Verify using a secret token in the header
$token  = $_SERVER['HTTP_X_QUIZ_TOKEN'] ?? '';
$secret = \Bitrix\Main\Config\Option::get('local.quiz', 'webhook_secret_marquiz');

if (!hash_equals($secret, $token)) {
    http_response_code(403);
    exit(json_encode(['error' => 'Unauthorized']));
}

$integrator = new \Local\Quiz\Bx24Integrator();
$result     = $integrator->createLeadFromQuiz($payload);

echo json_encode(['success' => true, 'lead_id' => $result]);

Creating a Lead in Bitrix24 via REST

namespace Local\Quiz;

use Local\Bx24\RestClient;

class Bx24Integrator
{
    private RestClient $bx24;

    public function __construct()
    {
        // Incoming Bitrix24 webhook with crm.lead.add permission
        $webhookUrl = \Bitrix\Main\Config\Option::get('local.quiz', 'bx24_webhook_url');
        $this->bx24 = new RestClient($webhookUrl);
    }

    public function createLeadFromQuiz(array $data): int
    {
        $contact = $data['contact'] ?? [];
        $answers = $data['answers'] ?? [];

        // Build a comment block with quiz answers
        $comments = $this->buildQuizComment($data['quiz_name'] ?? '', $answers, $data['result'] ?? '');

        $leadFields = [
            'TITLE'          => ($data['quiz_name'] ?? 'Quiz') . ': ' . ($contact['phone'] ?? ''),
            'NAME'           => $contact['name'] ?? '',
            'PHONE'          => [['VALUE' => $contact['phone'] ?? '', 'VALUE_TYPE' => 'WORK']],
            'EMAIL'          => [['VALUE' => $contact['email'] ?? '', 'VALUE_TYPE' => 'WORK']],
            'SOURCE_ID'      => 'WEB',
            'STATUS_ID'      => 'NEW',
            'COMMENTS'       => $comments,
            'UF_QUIZ_ID'     => $data['quiz_id'] ?? '',
            'UF_QUIZ_RESULT' => $data['result'] ?? '',
            'UF_UTM_SOURCE'  => $data['utm']['utm_source'] ?? '',
            'UF_UTM_CAMPAIGN'=> $data['utm']['utm_campaign'] ?? '',
        ];

        // Add individual fields for specific quiz questions
        $leadFields = $this->mapAnswersToFields($leadFields, $answers);

        $result = $this->bx24->call('crm.lead.add', ['fields' => $leadFields]);

        $leadId = (int)($result['result'] ?? 0);

        if ($leadId) {
            // Assign a task to the manager
            $this->bx24->call('crm.activity.add', [
                'fields' => [
                    'TYPE_ID'       => 2, // call
                    'SUBJECT'       => 'Call re quiz: ' . ($contact['phone'] ?? ''),
                    'OWNER_TYPE_ID' => 1, // lead
                    'OWNER_ID'      => $leadId,
                    'DEADLINE'      => date('c', strtotime('+2 hours')),
                ],
            ]);
        }

        return $leadId;
    }

    private function buildQuizComment(string $quizName, array $answers, string $result): string
    {
        $lines = ["=== Quiz: {$quizName} ==="];

        foreach ($answers as $answer) {
            $lines[] = ($answer['question'] ?? '?') . ': ' . ($answer['answer'] ?? '—');
        }

        if ($result) {
            $lines[] = '';
            $lines[] = "Quiz result: {$result}";
        }

        return implode("\n", $lines);
    }

    private function mapAnswersToFields(array $fields, array $answers): array
    {
        // Mapping specific questions to Bitrix24 custom fields
        $mapping = [
            'Number of windows' => 'UF_WINDOWS_COUNT',
            'Room type'         => 'UF_ROOM_TYPE',
            'Budget'            => 'UF_BUDGET_RANGE',
            'Urgency'           => 'UF_URGENCY',
        ];

        foreach ($answers as $answer) {
            $question = $answer['question'] ?? '';
            $fieldCode = $mapping[$question] ?? null;

            if ($fieldCode) {
                $fields[$fieldCode] = $answer['answer'] ?? '';
            }
        }

        return $fields;
    }
}

Custom Fields in Bitrix24 for the Quiz

Fields are created via the REST API or through the Bitrix24 interface (CRM → Settings → Custom Fields):

// Creating a custom field for a lead via REST
$this->bx24->call('crm.userfield.add', [
    'fields' => [
        'ENTITY_ID'   => 'CRM_LEAD',
        'FIELD_NAME'  => 'UF_QUIZ_RESULT',
        'USER_TYPE_ID'=> 'string',
        'XML_ID'      => 'QUIZ_RESULT',
        'EDIT_FORM_LABEL' => ['ru' => 'Результат квиза'],
        'LIST_COLUMN_LABEL' => ['ru' => 'Результат квиза'],
        'MANDATORY'   => 'N',
    ],
]);

Integration via Bitrix24 CRM Form

If the quiz is built from scratch — an alternative approach: a Bitrix24 CRM form with hidden fields. The final quiz step sends data directly into the form via the API:

// Final quiz step: send data to the Bitrix24 CRM form
async function submitQuizToBx24(answers, contact) {
    const formData = new FormData();

    // CRM form fields
    formData.append('fields[NAME]', contact.name);
    formData.append('fields[PHONE][0][VALUE]', contact.phone);
    formData.append('fields[UF_QUIZ_RESULT]', getQuizResult(answers));
    formData.append('fields[COMMENTS]', formatAnswers(answers));

    // Form ID from Bitrix24 settings
    const formId = document.getElementById('quiz-container').dataset.bx24FormId;

    await fetch(`https://your-domain.bitrix24.ru/crm/webform/import/form/${formId}/`, {
        method: 'POST',
        body: formData,
    });
}

Scope of Work

• Webhook handler for the quiz platform (Marquiz, Qform, or custom)
• Bitrix24 REST API client: creating leads and activities
• Creating custom fields for quiz answers
• Mapping quiz questions → CRM fields
• Building a structured comment with answers
• Passing UTM parameters into lead fields
• End-to-end testing: quiz completion → lead card in Bitrix24

Timeline: integration of one quiz platform via webhook — 3–7 days. Full setup with custom fields and multiple quizzes — 1–2 weeks.