Receiving leads from forms

The tracker accepts form data at two addresses: /api/v1/lead binds the email, phone and name to a click, and /api/v1/lead-file appends the lead as a line to the leads.php log of a hosted offer. Both addresses work without authorization on the tracking domain and on the campaign domains, so the page sends the data to its own domain.

Which one to choose

The methods are independent of each other: writing to the log does not fill in the Lead data block, and vice versa. One form can send data to both addresses.

In both requests the click is passed in the click_id, subid or aff_sub parameter. On a hosted page opened through the campaign link, the {click_id} macro inserts the value.

Binding data to a click

The /api/v1/lead address accepts GET and POST. The data is passed in the address parameters or in the request body: as a regular form or as FormData.

At least one data field is required. The tracker answers a POST with the text ok, and a GET with a transparent 1×1 image.

Ready-made form in the editor

1. Open Offers («Офферы») or Landing pages («Лендинги»).
2. In the row of the hosted page, click Editor («Редактор»).
3. Click + File («+ Файл»).
4. In the Template («Заготовка») block, choose HTML + lead form («HTML + форма лида»).
5. Check the File path («Путь файла»). The editor fills in index.html, or page.html if such a file already exists.
6. Click Create («Создать»).

The file gets a page with a form with the first_name and phone fields and a submit script:

<form id="lead-form">
  <input name="first_name" placeholder="Name" required>
  <input name="phone" placeholder="Phone" required>
  <button type="submit">Submit</button>
</form>

<script>
  document.getElementById('lead-form').addEventListener('submit', function (e) {
    var fd = new FormData(e.target);
    fd.append('click_id', '{click_id}');
    navigator.sendBeacon('/api/v1/lead', fd);
  });
</script>

The {click_id} macro is replaced with the click ID on a page opened through the campaign link. At the direct address there is no click, and the macro stays as text. Working with files is described on File editor, versions and export.

Source secret and repeated submissions

If the source the click came from has the Postback/lead secret («Секрет постбэка/лида») field filled in, the /api/v1/lead address accepts a request only with the correct secret parameter. Otherwise the response is 401. The form from the template does not pass the secret. How to set the secret is described on Incoming postback. The /api/v1/lead-file address does not check the secret.

A repeated submission to /api/v1/lead for the same click:

• no secret is set for the source — only empty fields are filled in, saved values do not change;
• a secret is set and passed correctly — the incoming fields replace the previous ones, and fields that were not passed stay as they were.

Where the lead data is shown

The block is visible to the owner and the admin.

1. Open the campaign statistics.
2. Go to the Click log («Лог кликов») tab.
3. Click the click row.

The click window has the Lead data block with the Email, Phone («Телефон»), First name («Имя») and Last name («Фамилия») rows. Empty rows are not shown. If no form was submitted for the click, the block says “no data (the lead did not submit the form)” («нет данных (лид не отправлял форму)»). The click card in the Logs («Логи») section does not show contacts — it shows only the time the form data was updated.

The tracker also inserts this data into the Facebook Conversions API event when the email, phone or name did not arrive in the postback.

Every accepted request leaves an entry in Logs → Postbacks («Логи → Postbacks»): “Lead data bound to … (email/phone/name)” («Данные лида закреплены за … (email/телефон/имя)»). If the request did not change the saved data, the entry is different: “Lead data for … is already saved — it is not overwritten without the source secret” («Данные лида за … уже сохранены — без секрета источника не перезаписываются»). In place of the ellipsis is the click ID.

Lead log of a hosted offer

The /api/v1/lead-file address accepts only POST. The data is passed in the request body: as a regular form, as FormData, or as a JSON object with the Content-Type: application/json header.

The offer ID is visible in the editor address: https://panel.example.com/offers/<offer ID>/editor.

At least one of the three is required: email, phone or name. Each value is cut to 256 characters. On success the tracker answers ok and writes to Logs → Postbacks: “Offer lead … written to leads.php” («Лид оффера … записан в leads.php»).

The request is sent by the offer page script — the same way as in the template above, but to the /api/v1/lead-file address and with the offer field — or by an HTML form with method="post" and action="/api/v1/lead-file". Regular page PHP does not make outgoing requests — see PHP in hosted pages and network access.

The leads.php file

The tracker creates the log in the offer root on the first lead. The file is visible in the editor file tree. The first line is a service line; after it, each record is one JSON line:

{"ts":"2026-10-04T12:30:00Z","click_id":"k3m9x2pq7wzt","conversions_tracking":"abc123","lead_id":"1024","email":"[email protected]","name":"John Smith","phone":"+1 2025550123"}

The time in ts is UTC. conversions_tracking gets the value of the conversions_tracking source token, or of the external_id token if there is none.

• The log can be opened by the owner, the admin and the team member who owns the offer. Others do not see it in the editor.
• The log is not served at a direct address: a request to leads.php gets a 404 response, or 403 when PHP is turned off.
• When leads.php reaches 5 MiB, the file is renamed to leads-<UTC date and time>.php, and writing continues in a new leads.php.
• Up to 10 such parts are kept. After that, new leads are not written until you delete the old parts in the editor.
• The log cannot be renamed. It can be deleted. For an offer with the PHP with network access («PHP с доступом в сеть») checkbox, only the owner and the admin can delete the log.
• When a new ZIP is uploaded, the log is kept. It does not get into a copy of the offer, into code versions or into Export ZIP («Экспорт ZIP»).
• Do not change the first line of the log and do not put your own leads.php file in the archive root. The tracker does not append leads to a file without the service first line, and requests get a 500 response.

Limits

• 600 requests per minute from one IP — a shared counter for both addresses.
• 5 log records per hour for one click of one offer.
• 1 MiB per request body.

Errors and their causes

An error response is JSON with the code and message fields. The table shows the message value.