Appearance
Forms API
Form analytics. The tracker never sends what visitors type, only timing and whether a field holds a value.
All paths are relative to https://your-site.com/api/v1. Send Authorization: Bearer <token> and Accept: application/json; see authentication and errors.
| Method | Path | What it does |
|---|---|---|
| GET | /sites/{site}/forms | The site's forms with how many sessions started and submitted each (most used first) |
| DELETE | /sites/{site}/forms/{form} | Forgets a form and everything measured on it (recordings:write); it comes back when visitors use it again |
| GET | /sites/{site}/forms/{form}/report | Conversion of a form and how each field is used |
| GET | /sites/{site}/forms/{form}/sessions | The latest 50 sessions that abandoned the form (optionally at a field) or submitted it |
GET /sites/{site}/forms
The site's forms with how many sessions started and submitted each (most used first)
The period (default the last 30 days) and segment apply to the sessions that started the form.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
site | path | integer | yes | |
from | query | string (date) | ||
to | query | string (date) | ||
device | query | string | One of: desktop, mobile, tablet. | |
source | query | string | One of: direct, search, social, email, paid, referral. | |
visitor | query | string | One of: new, returning. |
Responses
- 200 — Forms.
- 404 — Missing, or another account's.
- 422 — Validation failed.
Response fields
| Field | Type | Required | Description |
|---|---|---|---|
data | object[] | ||
data[].id | integer | ||
data[].key | string | How the tracker tells the form apart: data-sr-form name, #id, form[name], or a CSS path. | |
data[].name | string, nullable | ||
data[].url | string, nullable | Page it was last started on. | |
data[].fields | integer | Fields the form lists. | |
data[].last_seen_at | string (date-time) | ||
data[].started | integer | ||
data[].submitted | integer | ||
data[].conversion | number | % of started sessions that submitted. | |
period | object | ||
period.from | string (date) | ||
period.to | string (date) |
bash
curl -X GET "https://your-site.com/api/v1/sites/{site}/forms" \
-H "Authorization: Bearer $REPLORA_TOKEN" \
-H "Accept: application/json"DELETE /sites/{site}/forms/{form}
Forgets a form and everything measured on it (recordings:write); it comes back when visitors use it again
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
site | path | integer | yes | |
form | path | integer | yes |
Responses
- 204 — Deleted.
- 404 — Missing, or another account's.
bash
curl -X DELETE "https://your-site.com/api/v1/sites/{site}/forms/{form}" \
-H "Authorization: Bearer $REPLORA_TOKEN" \
-H "Accept: application/json"GET /sites/{site}/forms/{form}/report
Conversion of a form and how each field is used
Fields in the form's order, then fields seen that the form no longer lists. Per field: sessions that used it, interaction (% of started), ignored (started but never used it), ms (average time in it per session), hesitation_ms (average time from focus to the first keystroke), blank (% left without a value), refilled (% that came back to it), dropped (abandoned sessions whose last field it was) and drop_share (% of abandoned).
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
site | path | integer | yes | |
form | path | integer | yes | |
from | query | string (date) | ||
to | query | string (date) | ||
device | query | string | One of: desktop, mobile, tablet. | |
source | query | string | One of: direct, search, social, email, paid, referral. | |
visitor | query | string | One of: new, returning. |
Responses
- 200 — The report.
- 404 — Missing, or another account's.
- 422 — Validation failed.
Response fields
| Field | Type | Required | Description |
|---|---|---|---|
data | object | ||
data.form | object | ||
data.form.id | integer | ||
data.form.key | string | How the tracker tells the form apart: data-sr-form name, #id, form[name], or a CSS path. | |
data.form.name | string, nullable | ||
data.form.url | string, nullable | Page it was last started on. | |
data.form.fields | integer | Fields the form lists. | |
data.form.last_seen_at | string (date-time) | ||
data.period | object | ||
data.period.from | string (date) | ||
data.period.to | string (date) | ||
data.started | integer | ||
data.submitted | integer | ||
data.abandoned | integer | ||
data.conversion | number | ||
data.submit_ms | integer, nullable | Average time from start to submit. | |
data.fields | object[] | ||
data.fields[].key | string | ||
data.fields[].label | string, nullable | ||
data.fields[].type | string, nullable | ||
data.fields[].sessions | integer | ||
data.fields[].interaction | number | ||
data.fields[].ignored | integer | ||
data.fields[].ms | integer | ||
data.fields[].hesitation_ms | integer, nullable | ||
data.fields[].blank | number | ||
data.fields[].refilled | number | ||
data.fields[].dropped | integer | ||
data.fields[].drop_share | number |
bash
curl -X GET "https://your-site.com/api/v1/sites/{site}/forms/{form}/report" \
-H "Authorization: Bearer $REPLORA_TOKEN" \
-H "Accept: application/json"GET /sites/{site}/forms/{form}/sessions
The latest 50 sessions that abandoned the form (optionally at a field) or submitted it
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
site | path | integer | yes | |
form | path | integer | yes | |
outcome | query | string | One of: abandoned, submitted. Default "abandoned". | |
field | query | string | Only sessions that abandoned the form after using this field last. | |
from | query | string (date) | ||
to | query | string (date) | ||
device | query | string | One of: desktop, mobile, tablet. | |
source | query | string | One of: direct, search, social, email, paid, referral. | |
visitor | query | string | One of: new, returning. |
Responses
- 200 — Session ids (replay at GET /sites/{site}/sessions/{session}), when they started the form, and the last field of abandoned ones.
- 404 — Missing, or another account's.
- 422 — Validation failed.
Response fields
| Field | Type | Required | Description |
|---|---|---|---|
data | object[] | ||
data[].session | string (uuid) | ||
data[].at_ms | integer | ||
data[].submitted | boolean | ||
data[].last_field | string, nullable |
bash
curl -X GET "https://your-site.com/api/v1/sites/{site}/forms/{form}/sessions" \
-H "Authorization: Bearer $REPLORA_TOKEN" \
-H "Accept: application/json"