Build branching video surveys, powered by your own data.

Core concepts

Six objects make up everything you build. Skim this once and the rest of the API reads as plumbing.

Client

Your organization's tenant on Ratefy. Every object you create is scoped to it — there is no cross-tenant visibility.

Environment

A named deployment target (production, staging, development). Surveys and your data-integration settings both live inside one environment, so you can build against staging data before promoting to production.

Survey

An ordered sequence of questions with a title, tied to one environment. Surveys can also be chained — a survey can splice another survey's questions into itself at a given position.

Question

A single step in the survey: prompt text, an optional video (uploaded or AI-generated), a set of answer buttons, variable bindings, and branching conditions.

Button

A reusable, styled answer option (label, color, type). Defined once, attached to as many questions as you like, each with its own "go to" target.

Variable

A typed, named field (string / number / date) that pulls its value from your own backend at survey start, and can drive branching or personalize question text.

Response

One respondent's full run through a survey: every answer, resolved variable values, device metadata, and any captured video or photos.

Quickstart

The shortest path from an empty account to a live, embeddable survey.

Authentication

The direction that matters for your integration: Ratefy authenticates itself to your systems — you don't authenticate to Ratefy to make this work.

Ratefy → your systems

When Ratefy needs to call your backend — to run fetch_survey_data, for instance — it authenticates itself using a token it fetches from an auth endpoint you configure. Register that endpoint once as fetch_auth_token; Ratefy calls it, caches the resulting token, and attaches it to every subsequent call to your systems — refreshing automatically before it expires. See Data integration for the exact configuration shape.

Portal access — for your team, not required for integration

Day-to-day survey building happens in the Portal UI. If your team prefers managing content through this API directly instead, staff authenticate the standard way: email/password for a short-lived JWT.

Send the token on every subsequent request:

Authorization: Bearer <access_token>

Password recovery

Team & roles

Every user on your tenant holds one of three roles, forming a strict hierarchy.

Inviting teammates

New team members are added by email invitation rather than direct account creation. An invited user receives an emailed link, accepts it, and sets their own password.

Environments

Environments separate your survey work by deployment stage. Every survey, and every data-integration setting, belongs to exactly one.

Data integration

This is what makes Ratefy surveys feel like part of your product: instead of asking respondents for information you already have, Ratefy asks you for it, live, the moment a survey starts.

Per environment, you register up to four callbacks describing how Ratefy should talk to your backend:

Example configuration

{
  "baseUrl": "https://api.yourcompany.com/v1/respondents",
  "method": "GET",
  "timeout": 30000,
  "headers": { "X-Source": "ratefy" }
}

For endpoints of your own that require a token, describe how to fetch one and where to find it in the response:

{
  "baseUrl": "https://api.yourcompany.com/v1/auth/token",
  "method": "POST",
  "body": { "clientId": "...", "clientSecret": "..." },
  "tokenPath": "data.token",
  "expiresInPath": "data.expiresIn",
  "tokenHeaderName": "Authorization",
  "tokenPrefix": "Bearer "
}

Reference

Buttons

A button is a reusable answer control — define "Yes", "No", or "Continue" once, then attach it to as many questions as you like.

Once created, a button is attached to a question with its own per-question order and goTo target — so the same "Continue" button can lead to question 4 in one place and question 9 in another.

Variables

A variable is the bridge between your backend and a survey. Its name is the key Ratefy looks up in the payload your fetch_survey_data endpoint returns.

Attach a variable to a question and its resolved value becomes available to that question's branching conditions, and is snapshotted onto the respondent's answer for reporting.

Surveys

A survey is a title, an environment, and the ordered questions inside it.

Questions & branching

Questions are managed under their parent survey. Each one carries its prompt, its answer buttons, its variable bindings, and the conditions that decide what happens next.

Conditions

Each condition compares a variable's resolved value against a target, then either skips a question or jumps to another one.

{
  "conditions": [
    {
      "field": "customerTier",
      "conditionType": "equal",
      "value": "enterprise",
      "action": "go to",
      "targetQuestionId": "9"
    }
  ]
}

AI presenter video

Give any question a narrated video without a camera or a studio. Provide a script (or let Ratefy use the question text), pick a presenter and voice, and Ratefy renders the clip for you.

Video status lifecycle

Starting a session

This is the one call your respondent-facing app makes to begin a survey. No authentication needed — tenant isolation comes from the survey ID itself.

Capturing responses

Choose the submission pattern that fits your client: a single JSON call, multipart for browsers uploading a webcam clip, or a decoupled presigned-URL flow for large files.

Submitting answers

Webcam start/end photos

A survey can capture a still photo at the start and end of the recording, for identity or presence verification.

Reviewing responses

Back on the management side, your team can list, filter, and play back what respondents submitted.