> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serval.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Typeform

> Connect Typeform to Serval with your own Typeform OAuth app so workflows can manage forms and quizzes, pull survey responses, and provision webhooks for new submissions.

## About Typeform

Typeform is a conversational form and survey platform. The Serval Typeform integration lets your workflows manage forms and quizzes, pull and clean up form responses, organize workspaces and themes, upload images, and register webhooks that notify other systems about new submissions. Serval only ever talks to Typeform's official API address (api.typeform.com), and the integration currently carries a **Beta** label in the Serval app catalog.

**Authentication:** OAuth 2.0 with your own Typeform app ("bring your own app"). Your team registers an app in Typeform's Developer Apps panel and supplies its Client ID and Client Secret in Serval's connect form - Serval does not operate a shared Typeform app. Once connected, Serval keeps access fresh automatically, so a healthy connection never needs periodic re-authorization.

**Data sync:** On-demand only. Serval reads from and writes to Typeform exclusively when a workflow step runs. There is no background sync, no entity ingestion, and no prebuilt workflows are installed with this integration.

## What the Typeform integration enables

| Capability   | Description                                                                                                                                                          |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Account info | Look up the connected Typeform account (name, email, language). Also used at connect time to name the connection after your account.                                 |
| Forms        | List and search forms (optionally within one workspace), create new forms or quizzes, read a form's full definition, update it fully or partially, and delete forms. |
| Responses    | List a form's responses with rich filters (date ranges, completion status, text search, specific response IDs) and delete responses - up to 1000 per call.           |
| Webhooks     | See the webhooks configured on a form, and create, update, read, or remove a webhook by its tag, so other systems are notified about new submissions.                |
| Workspaces   | List and search workspaces, create new ones, read their details, modify them, and delete them.                                                                       |
| Themes       | List the account's themes, create new ones, read, update, and delete them.                                                                                           |
| Images       | List the account's image library and upload new images from a file or a public URL. (Deleting individual images is not supported - see Gotchas.)                     |

Anything defined in the [Typeform API](https://www.typeform.com/developers/) can be accessed through Serval.

## Get your credentials

You need your own Typeform OAuth app - a Client ID and Client Secret - registered in [Typeform's Developer Apps panel](https://admin.typeform.com/account#/section/apps). Typeform's registration form requires Serval's redirect URI up front, so the setup interleaves with the Serval side: start in Serval, register in Typeform, then finish back in Serval. See Typeform's [Applications guide](https://www.typeform.com/developers/get-started/applications/) for background.

<Steps>
  <Step title="Start the connection in Serval first">
    Open the Connect Typeform form in Serval. It displays the environment-specific **Redirect URI** with a **Copy** button - copy it now, and leave this form open while you work in Typeform.
  </Step>

  <Step title="Open Typeform's Developer Apps panel">
    Log in at [admin.typeform.com](https://admin.typeform.com/) and open the Developer Apps panel: click the icon drop-down next to your organization name in the upper-left corner, then **Developer Apps** under the Organization section (direct link: [admin.typeform.com/account#/section/apps](https://admin.typeform.com/account#/section/apps)). Click **Register a new app**.
  </Step>

  <Step title="Register the app">
    Fill in **App name** (e.g. "Serval Integration"), **App website** (cosmetic - it appears on the consent screen), **Redirect URI(s)** (paste the exact URI you copied from Serval), and **Developer email**. Click **Register app**.
  </Step>

  <Step title="Copy the Client Secret immediately">
    Typeform shows the **Client Secret** only once, at registration time. Copy it now. The **Client ID** stays visible in the panel afterward.
  </Step>

  <Step title="Approve all 14 scopes">
    On the new app's OAuth 2.0 scopes settings, approve every scope Serval requests: `accounts:read`, `forms:read`, `forms:write`, `images:read`, `images:write`, `themes:read`, `themes:write`, `workspaces:read`, `workspaces:write`, `responses:read`, `responses:write`, `webhooks:read`, `webhooks:write`, and `offline`. A missing scope makes the authorization step fail.
  </Step>
</Steps>

<Warning>
  The Client Secret is shown a single time. If you navigate away without copying it, you must regenerate it - which immediately invalidates the old value and breaks any Serval connection still using it.
</Warning>

<Note>
  Always copy the Redirect URI from the Serval form rather than typing it by hand. It must match exactly, and it differs per environment.
</Note>

## Connect in Serval

<Steps>
  <Step title="Open the Connect Typeform form">
    In Serval, add the **Typeform** integration (it carries a **Beta** label in the app catalog) to open the connect form.
  </Step>

  <Step title="Copy the Redirect URI if you have not already">
    The read-only **Redirect URI** field shows the value to register in Typeform, with a **Copy** button (it briefly switches to "Copied"). Its helper text reads "Add this as a Redirect URI in your Typeform app settings."
  </Step>

  <Step title="Enter the Client ID">
    Fill in **Client ID** (required) - placeholder "Enter your Typeform Client ID". Stray whitespace is trimmed automatically.
  </Step>

  <Step title="Enter the Client Secret">
    Fill in **Client Secret** (required) - a masked, password-style field with placeholder "Enter your Typeform Client Secret". Stray whitespace is trimmed automatically.
  </Step>

  <Step title="Connect and approve">
    Click **Connect to Typeform**. The button stays disabled until both fields are filled in; if a blank value slips through anyway, the form shows "Please fill in all required fields" and the server rejects it with "clientId is required" or "clientSecret is required". Serval sends you to Typeform's consent screen - approve it to finish. The connection is named after your Typeform account.
  </Step>
</Steps>

<Note>
  Complete Typeform's consent screen within 10 minutes of clicking **Connect to Typeform**. The credentials you entered are held only briefly, and taking longer shows "Invalid or expired OAuth state" or "OAuth session expired, please try again" - just restart from the connect form.
</Note>

<Note>
  There is no separate edit-credentials form for this integration. To rotate the Client Secret or update the app's settings, run the connect flow again with the same Typeform account - it updates the existing connection in place and keeps your workflows wired up.
</Note>

## Verifying the connection

The Typeform integration includes three named health checks:

* **Test Typeform Connection** - verifies Serval can authenticate by looking up the connected account, and reports it by name, email, or user ID (whichever is available first; "unknown user" if none are). On success: "Successfully connected to Typeform as \[name]". On failure: "Unable to connect to Typeform. Verify your OAuth credentials are valid, the app has the accounts:read scope approved, and the token has not been revoked."
* **List Typeform Forms** - verifies form read access by listing a small sample of forms. On success: "Found \[number] form(s): \[up to 3 sample titles]." If the account has no forms yet: "API access verified but this account has no forms yet. Create a form in Typeform to start automating responses." On failure: "Unable to list forms. Verify your Typeform app has the forms:read scope approved on the OAuth scopes settings."
* **List Typeform Workspaces** - verifies workspace read access by listing a small sample of workspaces. On success: "Found \[number] workspace(s): \[up to 3 sample names]." If the account has no workspaces yet: "API access verified but this account has no workspaces yet." On failure: "Unable to list workspaces. Verify your Typeform app has the workspaces:read scope approved on the OAuth scopes settings."

Behind the scenes, Serval also re-verifies authentication with the same account lookup used by the first check. A failure there means the token was revoked, the app was deleted, or its scopes changed on the Typeform side.

<Tip>
  If all three checks are green but workflows later start failing, the cause is almost always on the Typeform side: the app was revoked or deleted, or its Client Secret was regenerated after you connected. Re-run the connect flow with fresh credentials to repair the connection.
</Tip>

## Gotchas and troubleshooting

<AccordionGroup>
  <Accordion title="Authorization fails with an invalid_scope error">
    Serval requests the same fixed set of 14 scopes on every connection: `accounts:read`, `forms:read`, `forms:write`, `images:read`, `images:write`, `themes:read`, `themes:write`, `workspaces:read`, `workspaces:write`, `responses:read`, `responses:write`, `webhooks:read`, `webhooks:write`, and `offline`. If any one of them is not enabled on your app's OAuth scopes settings, Typeform rejects the authorization with invalid\_scope. Enable the missing scope(s) in the Developer Apps panel and connect again.
  </Accordion>

  <Accordion title="&#x22;Invalid or expired OAuth state&#x22; or &#x22;OAuth session expired, please try again&#x22;">
    The Client ID and Client Secret you enter are held for only 10 minutes between clicking **Connect to Typeform** and returning from Typeform's consent screen. If the approval takes longer, the attempt expires. Restart the connection from the Serval connect form - your Typeform app itself is unaffected.
  </Accordion>

  <Accordion title="The connection broke about a week after connecting">
    Typeform access tokens expire after about one week by default. The `offline` scope - which Serval always requests - is what lets Serval refresh access automatically with a long-lived refresh token that lasts until revoked. If `offline` was not approved on your app when you connected, the connection breaks after roughly a week. Approve `offline` in the Developer Apps panel and reconnect.
  </Accordion>

  <Accordion title="I regenerated the Client Secret and workflows started failing">
    Serval stores your app's Client ID and Client Secret with the connection and uses them to refresh access. If the secret is regenerated in Typeform, refreshes fail as soon as the current access lapses. There is no separate update-credentials form - re-run the connect flow with the fresh Client Secret, and the existing connection is repaired in place.
  </Accordion>

  <Accordion title="I lost the Client Secret">
    Typeform displays the Client Secret only once, at app registration, and Serval never reveals it back to you. If you did not copy it, regenerate it in the Developer Apps panel - note this immediately invalidates the old value and breaks any Serval connection still using it - then re-run the connect flow with the new secret.
  </Accordion>

  <Accordion title="Typeform will not let me register the app without a Redirect URI">
    Typeform's **Register app** button stays disabled until **Redirect URI(s)** is filled in. That is why the setup starts in Serval: open the connect form first to reveal and copy the environment-specific Redirect URI, register the Typeform app with it in a second tab, then return to the still-open Serval form with your credentials. Always copy the URI from the form - it must match exactly.
  </Accordion>

  <Accordion title="What happens when I reconnect?">
    Connections are keyed on the Typeform account you authorize. Reconnecting with the same account - for example after rotating the Client Secret or approving more scopes - updates the existing connection in place and preserves the workflows wired to it. Reconnecting with a different Typeform account creates a separate connection instead.
  </Accordion>

  <Accordion title="Deleting images is not supported">
    Workflows can list the account's image library and upload new images (from a file or a public URL), but there is no way to retrieve or delete an individual image through the integration. Remove images in Typeform directly if needed.
  </Accordion>

  <Accordion title="Why does Typeform show a Beta label?">
    The integration is marked Beta in the Serval app catalog. That reflects its catalog status, not a problem with your connection - everything on this page describes its current behavior.
  </Accordion>
</AccordionGroup>

***

Need help? Contact **[support@serval.com](mailto:support@serval.com)** for assistance with your Typeform integration.