Skip to main content

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.

​
About Typeform

Typeform is a conversational form and survey platform with a REST API that covers form design, response collection, theming, and webhook delivery. Connecting Typeform to Serval enables workflows that read and create forms, pull form responses into your CRM or warehouse, manage themes and images, and register webhooks that fire on every new submission.

​
What the Typeform integration enables

CapabilityDescriptionTypeform scope required
Account infoRead the connected user’s email, language, and account IDaccounts:read
Form managementList, create, update, and delete forms; perform JSON Patch updates on existing formsforms:read, forms:write
Response collectionPull paginated responses for a form, filter by date range or token, delete specific responsesresponses:read, responses:write
WebhooksList, create, update, and delete webhooks per form, addressed by tagwebhooks:read, webhooks:write
WorkspacesList, create, update, and delete workspaces, including searching by nameworkspaces:read, workspaces:write
ThemesList, create, update, and delete themes used across formsthemes:read, themes:write
ImagesList, upload, and delete images stored in the account for use across formsimages:read, images:write
Anything defined in the Typeform Create, Responses, and Webhooks APIs can be accessed through Serval.

​
Prerequisites

Serval uses the “bring your own app” model for Typeform. Each team that connects Typeform registers their own Typeform app as part of the connection flow below, which means you control the app’s scopes, audit logs, and rate-limit budget. Serval does not share a global Typeform app across customers.

​
Connect Typeform to Serval

The Typeform app registration form requires the Redirect URI up front — you cannot save the app and add it later. Because of that, the connection flow interleaves between Serval and Typeform: start the connection in Serval to reveal the Redirect URI, register your Typeform app with that URI, then come back to Serval with the resulting Client ID and Client Secret to finish. Have both browser tabs open before you start. The full sequence:
1

Start the connection in Serval to reveal the Redirect URI

In Serval, navigate to Apps → Available → Typeform and click Connect. The Connect Typeform modal opens with a Redirect URI at the top (environment-specific, something like https://svflow-auth-config.api.serval.com/typeform/oauth/callback).Click Copy to grab the URI. Leave this modal open — you’ll come back to it once you have your Typeform credentials.
The redirect URI is environment-specific. Always copy the exact value from the Serval modal; do not construct it by hand.
2

Register a Typeform app with the Redirect URI

In a new tab, log in at Typeform and click the icon drop-down menu next to your organization name in the upper-left corner. Under the Organization section, click Developer Apps, then click Register a new app.Fill in the form:
  • App name — for example, Serval Integration.
  • App website — your company website. This is metadata Typeform shows on the consent screen and does not affect the OAuth flow.
  • Redirect URI(s) — paste the URI you copied from the Serval Connect modal. This field is required at registration.
  • Developer email — your email; Typeform contacts you here about the app.
Click Register app.
After you click Register app, Typeform shows the Client Secret one time only. Copy it immediately and store it somewhere safe — if you leave the page without copying it, you will need to regenerate it (which invalidates the value you just registered).
3

Approve the OAuth 2.0 scopes on the new app

Still in the Typeform Developer Apps panel, open the app you just registered and 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
  • offline
The offline scope is required for Serval to refresh access tokens automatically. Without it, Typeform issues access tokens that expire after one week and the connection would need to be reauthorized every week. With offline, Typeform issues a refresh token alongside the access token and Serval uses it transparently.
Copy the Client ID from the same panel — you’ll paste it into Serval next, alongside the Client Secret you copied at registration time.
4

Finish the connection in Serval

Switch back to the Serval Connect Typeform modal you left open in step 1 and:
  1. Paste the Client ID from the Typeform Developer Apps panel.
  2. Paste the Client Secret you copied when you registered the app.
  3. Click Connect to Typeform.
Serval redirects you to Typeform’s consent screen — review the requested permissions and click Accept. Typeform redirects you back to Serval with the integration connected.
Anyone with the Client ID and Client Secret can act as your Typeform app. Treat the Client Secret like a password — never commit it to source control or share it in plain text.
The integration is keyed on the Typeform user_id of the account that authorized the app. Reconnecting the same Typeform account later — for example, after rotating the Client Secret or expanding scopes — updates the existing Serval connection in place, preserving any workflows already wired to it. Reconnecting with a different Typeform account creates a new, separate connection.

​
Updating scopes

If you approve a new OAuth scope on your Typeform app after you’ve already connected Serval, the existing connection keeps using the scopes it was originally granted. To pick up new scopes:
  1. In the Typeform Developer Apps panel, confirm the new scope is approved on your app.
  2. In Serval, open the connected Typeform integration and click Reconnect.
  3. Typeform will show the consent screen again with the expanded scope list — approve it to refresh the grant.
Reconnecting preserves the connection’s Serval ID, so workflows keep running with the newly expanded permissions.

​
Troubleshooting

This almost always means the Client Secret Serval has does not match the one Typeform has on file. The most common causes:
  • Someone clicked Regenerate client secret in the Edit app panel after the old one was pasted into Serval. Typeform invalidates the previous secret immediately.
  • The secret was copied with a leading or trailing character — Typeform shows the secret only once, so a typo can slip through unnoticed.
  • The Client ID and Client Secret pasted into Serval belong to different Typeform apps.
To fix it: in the Typeform Developer Apps panel, click Regenerate client secret to produce a known-good value, then reconnect in Serval and paste the fresh secret.
Typeform rejects the authorize step if any scope Serval requests is not approved on your Typeform app. Open the app in the Developer Apps panel, confirm every scope listed in the Approve the OAuth 2.0 scopes step above is enabled, save your changes, and try connecting again.
This indicates the offline scope was not granted, so Typeform did not issue a refresh token alongside the access token. Typeform access tokens expire after one week by default — without a refresh token, the connection cannot recover automatically.To fix: confirm the offline scope is approved on your Typeform app, then reconnect in Serval. The new authorize step will include offline in the requested scopes and Typeform will issue a refresh token.
Each Typeform endpoint requires a specific scope (see the table at the top of this page). A 403 on a particular endpoint means the connection’s granted scopes do not include the one that endpoint needs. Approve the missing scope on your Typeform app and reconnect in Serval to refresh the grant.

​
External Resources