Skip to content

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.

MethodPathWhat it does
GET/sites/{site}/formsThe 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}/reportConversion of a form and how each field is used
GET/sites/{site}/forms/{form}/sessionsThe 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 ​

NameInTypeRequiredDescription
sitepathintegeryes
fromquerystring (date)
toquerystring (date)
devicequerystringOne of: desktop, mobile, tablet.
sourcequerystringOne of: direct, search, social, email, paid, referral.
visitorquerystringOne of: new, returning.

Responses ​

  • 200 — Forms.
  • 404 — Missing, or another account's.
  • 422 — Validation failed.
Response fields
FieldTypeRequiredDescription
dataobject[]
data[].idinteger
data[].keystringHow the tracker tells the form apart: data-sr-form name, #id, form[name], or a CSS path.
data[].namestring, nullable
data[].urlstring, nullablePage it was last started on.
data[].fieldsintegerFields the form lists.
data[].last_seen_atstring (date-time)
data[].startedinteger
data[].submittedinteger
data[].conversionnumber% of started sessions that submitted.
periodobject
period.fromstring (date)
period.tostring (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 ​

NameInTypeRequiredDescription
sitepathintegeryes
formpathintegeryes

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 ​

NameInTypeRequiredDescription
sitepathintegeryes
formpathintegeryes
fromquerystring (date)
toquerystring (date)
devicequerystringOne of: desktop, mobile, tablet.
sourcequerystringOne of: direct, search, social, email, paid, referral.
visitorquerystringOne of: new, returning.

Responses ​

  • 200 — The report.
  • 404 — Missing, or another account's.
  • 422 — Validation failed.
Response fields
FieldTypeRequiredDescription
dataobject
data.formobject
data.form.idinteger
data.form.keystringHow the tracker tells the form apart: data-sr-form name, #id, form[name], or a CSS path.
data.form.namestring, nullable
data.form.urlstring, nullablePage it was last started on.
data.form.fieldsintegerFields the form lists.
data.form.last_seen_atstring (date-time)
data.periodobject
data.period.fromstring (date)
data.period.tostring (date)
data.startedinteger
data.submittedinteger
data.abandonedinteger
data.conversionnumber
data.submit_msinteger, nullableAverage time from start to submit.
data.fieldsobject[]
data.fields[].keystring
data.fields[].labelstring, nullable
data.fields[].typestring, nullable
data.fields[].sessionsinteger
data.fields[].interactionnumber
data.fields[].ignoredinteger
data.fields[].msinteger
data.fields[].hesitation_msinteger, nullable
data.fields[].blanknumber
data.fields[].refillednumber
data.fields[].droppedinteger
data.fields[].drop_sharenumber
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 ​

NameInTypeRequiredDescription
sitepathintegeryes
formpathintegeryes
outcomequerystringOne of: abandoned, submitted. Default "abandoned".
fieldquerystringOnly sessions that abandoned the form after using this field last.
fromquerystring (date)
toquerystring (date)
devicequerystringOne of: desktop, mobile, tablet.
sourcequerystringOne of: direct, search, social, email, paid, referral.
visitorquerystringOne 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
FieldTypeRequiredDescription
dataobject[]
data[].sessionstring (uuid)
data[].at_msinteger
data[].submittedboolean
data[].last_fieldstring, 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"

Replora: see what your visitors see.