SOURCE_ID: import_from_typeform
NAME: Import Typeform Responses
CATEGORY: First-party

Import responses to a Typeform form into Floqer — backfill the existing
responses and keep importing new submissions as they arrive. Each response
becomes a row whose fields are the form answers you select. Imported rows
become available to your Floqer workflows for enrichment, scoring, outreach,
and the like.

1. ENDPOINTS

Source identifier (used in every endpoint path): `import_from_typeform`.

  POST /api/v1/sources/import_from_typeform/preview
    Scope: sources:read
    Returns a sample page of responses for the chosen form / fields, without
    creating anything. Use this to validate the form and field selection and
    inspect row shape before committing.

  POST /api/v1/sources/import_from_typeform
    Scope: sources:write
    Creates the source, imports existing responses immediately (when
    `pull_existing`), and keeps importing new submissions as they arrive.
    Returns `source_instance_id` (the new source's UUID).

  POST /api/v1/sources/import_from_typeform/options/<field_name>
    Scope: sources:read
    Resolves dynamic option values for a field: `form_id` and `form_fields`
    (see §4).

  GET /api/v1/sources/<source_instance_id>/data
    Scope: sources:read
    Paginated rows imported into the created source. `<source_instance_id>` is the
    UUID returned by Create. Query: `page_no`
    (default 1), `page_size` (default 20, max 200). Source-agnostic;
    see concepts.txt §10.

  POST /api/v1/sources/<source_instance_id>/sync
    Scope: sources:write
    Connects the created source to a workflow and (by default) backfills
    it with the source's current rows. `<source_instance_id>` here is the UUID
    returned by Create. Body: { workflow_id, field_mapping, push_existing?,
    run? } — `field_mapping` keys are `input.<field>` references on the
    target workflow, values are the source fields to pull. This step is
    source-agnostic; see concepts.txt §10 for the full shape.

  PATCH /api/v1/sources/<source_instance_id>/status
    Scope: sources:write
    Pause or resume the source by UUID. Body: {"status": "active" |
    "paused"}. Source-agnostic.

Every endpoint for this source first verifies the API-key user has an
active Typeform connection. Missing connection → 424.

2. BODY SHAPE (PREVIEW + CREATE)

Field names are snake_case. Unknown top-level keys are rejected with 400 —
the body is strict.

Preview accepts:
  form_id      required: the Typeform form ID
  form_fields  required: non-empty object mapping field id → display label

Create accepts all the preview fields plus:
  name           required: display name for the new source
  pull_existing  boolean (or "true"/"false"); optional (backfill existing
                 responses on create)

3. FIELD CATALOGUE

  form_id (string) — required
    The Typeform form whose responses you want to import. Resolve it with
    the `form_id` dynamic-options call (§4).

  form_fields (object) — required
    A non-empty object mapping each Typeform field ID to the display label
    you want that answer to appear under on imported rows:
      { "<field_id>": "<label>", "<field_id>": "<label>", ... }
    Build it from the `form_fields` dynamic-options call (which returns the
    field ids and their titles). Each entry becomes one column on the
    imported response rows.

  name (string) — required on create only
    Human-readable display name for the source.

  pull_existing (boolean | "true" | "false") — optional, create only
    When true, the form's existing responses are imported on create. When
    false, only new submissions going forward are imported.

4. DYNAMIC OPTIONS

Two dynamic-options field names are available for this source. Both are
POSTs to
  /api/v1/sources/import_from_typeform/options/<field_name>
with body `{ "context"?: {...} }`.

  form_id
    Context: none.
    Returns: {value: <form_id>, label: <form_title>, extras}. Use the
    returned `value` directly as `form_id`.

  form_fields
    Context: { "form_id": "<id>" } — REQUIRED.
    Returns: {value: <field_id>, label: <field_title>, extras} for each
    field on the form. Build the `form_fields` object as
    `{ "<field_id>": "<label>", ... }` — typically `field_id` → the field's
    title.

Connection check: each call verifies the API-key user has an active
Typeform connection first. Missing connection → 424.

5. HOW TO CONFIGURE END-TO-END

Typical flow for an AI agent building a Typeform import source:

  Step 1 — Resolve the form
    POST /api/v1/sources/import_from_typeform/options/form_id
    Body: {}
    Pick the form's `value` as `form_id`.

  Step 2 — Resolve the form fields
    POST /api/v1/sources/import_from_typeform/options/form_fields
    Body: {"context": {"form_id": "<id from step 1>"}}
    Build `form_fields` as `{ "<field_id>": "<label>", ... }` from the
    returned ids and titles (pick the answers you want as columns).

  Step 3 — Preview before committing
    POST /api/v1/sources/import_from_typeform/preview
    Body:
      { "form_id": "<id>",
        "form_fields": { "abc123": "Email", "def456": "Company" } }
    Check the returned `data[]` row shape. Iterate the field selection until
    you're happy — preview never creates anything.

  Step 4 — Create the source
    POST /api/v1/sources/import_from_typeform
    Body: <same as preview body> + the create-only fields:
      "name": "<display name>",
      "pull_existing": true             // optional
    Response: { "status": 201, "data": { "source_instance_id": "<uuid>", "name",
    "created_at" }}

  Step 4b — (Optional) Poll imported rows while the import runs
    GET /api/v1/sources/<source_instance_id>/data?page_no=1&page_size=20
      (<source_instance_id> = UUID from Step 4)
    Row keys match the labels you set in `form_fields`. `total_count` grows
    until the import finishes.

  Step 5 — Sync the source into a workflow (so its responses flow downstream)
    POST /api/v1/sources/<source_instance_id>/sync          ( <source_instance_id> = UUID from Step 4 )
    First build `field_mapping`:
      a. GET /api/v1/workflows  → pick the destination workflow_id.
      b. GET /api/v1/workflows/<workflow_id>/sheets/<workflow_id>/inputs
         → each input has a `reference` like `{{input.email}}`.
      c. Map each workflow input (reference WITHOUT braces) to a source
         field — the source fields are the labels from `form_fields`.
    Body:
      { "workflow_id": "<uuid>",
        "field_mapping": { "input.email": "Email", "input.company": "Company" },
        "push_existing": true,
        "run": "all" }
    See concepts.txt §10 for the full sync semantics (source-agnostic).

The initial import runs asynchronously — the create call returns as soon
as the source is created and the import has started, not when responses
have finished arriving. New submissions are imported as they come in.

6. KEY NOTES

- Typeform connection is mandatory. If the API-key user has no active
  Typeform connection, every endpoint (preview, create, options) returns
  424 ("User is not connected to 'typeform'."). Surface this as a "connect
  Typeform first" CTA.

- `form_fields` maps Typeform field IDs to the labels imported rows use. It
  must be a non-empty object — pick at least one answer to import.

- After create, new submissions to the form keep flowing into the source.
  `pull_existing` controls whether the form's existing responses are
  backfilled on create.

- Credits are consumed when the source is created. If credit consumption
  fails (e.g. insufficient balance), the source is still created but its
  import can't start; the API returns 402 so you can top up and retry.

- Use PATCH /status to pause the source and resume it later without
  recreating it.

7. WHERE IT FITS

UPSTREAM (in Typeform)
  Form responses are submitted to a form in the user's Typeform account.
  Field ids and answer values come from Typeform's own data model.

THIS SOURCE
  Creates a Typeform import source. On creation it imports existing
  responses (when `pull_existing`) and keeps importing new submissions as
  they arrive, one row per response with the fields you selected.

DOWNSTREAM (in Floqer)
  Imported responses become available to your Floqer workflows — wire the
  source into a workflow to enrich, score, or run outreach on each response.

8. WHEN TO USE

- Route new Typeform submissions into a Floqer workflow for instant
  follow-up (lead routing, enrichment, outreach).

- Backfill all existing responses for analysis or one-time enrichment:
  `pull_existing: true`.

Last updated: 2026-06-02. Reference: https://floqer.com/docs/reference