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.

INDEX:
  1. Endpoints
  2. Body shape (preview + create)
  3. Field catalogue
  4. Dynamic options
  5. How to configure end-to-end
  6. Key notes
  7. Where it fits
  8. When to use

================================================================================
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