A video survey engine your engineers wire up once — and your team edits forever.
Ratefy is an API-first, multi-tenant platform for branching video surveys: a documented REST API for integration, a no-code Portal for content, an asynchronous AI video-rendering pipeline, and server-side personalization driven by your own systems.
Two integration surfaces: one your engineers touch, one they don't.
Engineering integrates the data contract once, per environment. Everything downstream of that — survey structure, copy, branching, presenter scripts — is edited directly in the Portal, with no deploy in the loop.
01 · Model the flow
Content owners build the survey as a branching flow in the Portal. Structure is stored as data, evaluated at runtime — not compiled into your app.
02 · Wire the integration
Engineering registers your backend's data endpoints once per environment — fetch_survey_data and, if needed, fetch_auth_token.
03 · Serve the session
GET /surveys/start resolves branching and personalization server-side, using data fetched live from your systems, and returns a ready-to-render session.
04 · Capture and observe
The response streams back with full context attached. If the integration misbehaves along the way, that's logged and queryable, not swallowed.
Branching logic your content team owns — not your codebase.
Buttons, branches, and conditions are stored as configuration and evaluated server-side at session start. Every button carries two settings — isValidAnswer and endSurvey — that mark it as the expected response and control whether selecting it terminates the session. Edit the same flow two ways: visually, or as data.
isValidAnswer button in its path — the canvas flags this before it ever reaches a respondent.
Two ways in, one source of truth: the Flow view is where mistakes get caught — a button with no destination, two answers both marked expected, a question no path ever reaches. The Code view is the same definition as data, for teams that version, template, or bulk-generate surveys. Either way, product, CS, or marketing teams can edit content directly in the Portal, any time, with zero engineering involvement and no release.
Reusable buttons
Defined once, attached to any question with its own goTo target and order.
Expected answers
Mark any button isValidAnswer, and optionally endSurvey, to define what a correct or disqualifying response looks like.
Conditional routing
11 comparison operators (equal, contains, exists, …) evaluated against resolved variables at session start.
Linked surveys
Splice a shared question block into any parent survey at a given position — no duplication.
Personalized start message
Set the welcome message respondents see the moment a survey opens, directly in the Portal — personalized with resolved variables, no engineering involved.
A personalized, configurable presenter — generated on click, not on a shoot day.
Once a question's script is written, generating its video is a single click — no manual recording, editing, or encoding step at any point. The presenter's appearance, voice, and on-screen background are configurable per question, so the avatar can match your brand rather than a generic stock template.
Fully automated, zero manual steps
Click Generate once the script is defined; rendering runs as a background job — none → generating → ready / failed — with no human in the loop.
Personalized avatar, per question
Choose presenter, voice, and background independently for every question — swap any of them without re-shooting or re-editing anything.
3,000-character script limit
Per render request. Returns 202 Accepted immediately; a webhook callback or status poll reports completion.
script: 214 / 3000 chars
Personalization resolved server-side, from your systems.
Every session calls back into your backend before the first question renders. Four integration hooks, configured once per environment:
| API type | Called when | Status |
|---|---|---|
| fetch_survey_data | On every GET /surveys/start — returns the payload used to resolve variables and conditions. | Active |
| fetch_auth_token | Before calling your other endpoints, if they require a bearer token. Cached and auto-refreshed. | Active |
| send_survey_data | Push completed response data back to your systems. | Reserved |
| send_logs | Stream survey-session events to your own logging pipeline. | Reserved |
PUT /client-configs/environments/:environmentId/apis/fetch_survey_data
{
"baseUrl": "https://your-api.com/v1/respondents",
"method": "GET",
"timeout": 30000,
"headers": { "X-Source": "ratefy" }
}Tokens obtained via fetch_auth_token are cached and refreshed automatically, guarded by a distributed lock — concurrent survey sessions never stampede your auth endpoint.
Environments aren't limited to the three defaults. Create as many as you need, each with its own integration config — including one pointed at http://localhost:PORT for testing against a local dev server before anything touches staging.
Response capture, direct from the browser.
No plugin, no app install. Answers, webcam video, and verification photos are captured client-side and delivered to storage through one of several supported upload paths.
Multipart or base64 submission
Submit answers and video together in a single call — multipart form data or base64-encoded, whichever fits your client.
Start / end verification photos
Optional still captures, bound to the response for identity context.
Browser-native capture
Standard web media APIs — no downloads, works on desktop and mobile.
One verdict per session — Pass or Fail, computed automatically.
Every button already carries isValidAnswer and endSurvey — configured once in the Flow Builder. On top of that primitive, Ratefy will evaluate the full response against your configuration and deliver a single verdict to your system, with the response, resolved metadata, and session logs attached.
Fail triggers on any isValidAnswer: false selection where endSurvey is set, or on an incomplete session — the same configuration already defined per button.
No question bank to replicate: your system doesn't need to store questions, expected answers, or scoring logic — Ratefy is the source of truth for both, and hands back only the outcome and the evidence behind it.
Planned webhook payload · send_survey_data
{
"surveyId": 42,
"responseId": "a48f",
"verdict": "fail",
"failedAt": "q1",
"answers": [ "…" ],
"metadata": { "…" },
"logs": [ "…" ]
}Structured logs for every integration call, queryable in real time.
Each of the four hooks above will emit a structured event — what was expected, what arrived, and when. Pull it on demand, or have it pushed to your own pipeline via send_logs.
Scenario: a respondent opens survey #42 and Ratefy calls your fetch_survey_data endpoint — the response comes back missing customerTier. Rather than resolving silently with a gap, the failure is recorded with enough detail to diagnose it immediately.
Planned log entry schema
{
"level": "error",
"source": "fetch_survey_data",
"surveyId": 42,
"environment": "production",
"message": "Missing required field: customerTier",
"latencyMs": 214,
"timestamp": "2026-09-14T10:42:03Z"
}Two teams, one platform, no shared bottleneck.
Engineering owns environments, integrations, and access control — set up once. Everyone else owns survey content — edited continuously. Neither has to wait on the other.
Engineering sets up once
Config & access- Environments (production / staging / development)
- Data integration endpoints per environment
- Team roles and access boundaries
Content team edits anytime
No deploy required- Questions, buttons, branching, conditions
- Presenter scripts, voices, uploaded video
- Reviewing and filtering responses
Survey Builder
Drag questions into a flow, attach buttons and conditions, preview as you go.
Response Inbox
Every submission, searchable and filterable, with video playback built in.
Integration LogsRoadmap
Real-time diagnostics whenever your data integration misbehaves.
Team & access
Four-tier role hierarchy — Admin, Moderator, Editor, Viewer — scoped to your organization.
What's attached to every submission.
Beyond the selected answers, each response carries the context needed to interpret it — not just what was clicked, but how the session behaved.
Answers & choices
Every selected button and free-text reply, in submission order.
Personalization snapshot
The exact externalData values that shaped this session's branching.
Engagement timing
viewedAt / answeredAt / durationMs / revisitCount / changeCount / idleMs per answer.
Device & browser
Desktop or mobile, browser and OS, captured client-side.
Approximate location
City-level geolocation, stored alongside the response.
Video & photos
The webcam response, plus optional start/end verification stills, as S3 object keys.
Timing fields are informational rather than authoritative — useful for spotting hesitation or disengagement, not as a scored metric on their own.
Built for integration, not just for demos.
The technical characteristics that matter once this is carrying production traffic, not a sandbox account.
REST + OpenAPI
Every endpoint is documented and explorable through an interactive Swagger UI, generated from the same source as the API itself.
JWT + role-based access
Four-tier hierarchy — Admin, Moderator, Editor, Viewer — enforced per route, scoped to your organization only.
Multi-tenant, environment-isolated
Define as many environments as you need — production, staging, a local dev server, anything — none of them ever share data, configuration, or integration credentials.
Server-managed media uploads
Video and photo payloads are submitted directly to the API — multipart or base64 — and persisted to object storage server-side.
HTTP range-request streaming
Response video supports byte-range requests, so playback seeks instantly instead of downloading the full file.
Async rendering pipeline
AI presenter video generation runs as a background job with webhook or poll-based completion — never blocks a request thread.
Cached, auto-refreshing tokens
A distributed refresh lock prevents concurrent sessions from hammering your fetch_auth_token endpoint.
Strict request validation
Unknown fields are rejected at the API boundary, not silently dropped — validation errors are explicit and field-level.
Rate-limited sensitive routes
Auth and invitation endpoints are throttled independently of general API traffic.
Full endpoint reference, request/response schemas, and integration walkthroughs live in the developer documentation →