API Step

Published July 25, 2026 • Updated October 20, 2026

Use the API Step when a quiz needs to talk to an external system while the participant moves through the flow. It can send quiz answers, lead fields, tags, variables, or scores to tools like CRMs and webhooks, or fetch data from another service and store response values for later copy, logic, and outcomes.

Unlike question blocks, the API Step runs in the background and does not render as a participant-facing prompt.

Best used for

When to choose another step

Setup flow

1. Add an API Step in Build Flow where the request should run.
2. Choose the request method and HTTPS endpoint URL.
3. For a protected service, select a saved credential under Authentication and check Send credential as. Create credentials in Settings → API, then use Refresh credentials to load newly created or changed credentials.
4. Add any required headers, query parameters, and body content.
5. Use placeholders for quiz values that should be sent with the request.
6. Click Send to test the request and inspect the response shape.
7. Map response paths into variables if later logic, copy, or outcome content depends on them.
8. Enable a failure destination when the quiz needs a fallback path if the request fails.
9. Preview the flow and confirm later steps behave correctly with captured variables.

Settings reference

Connect a saved credential

1. Open Settings → API → New credential. Give it a recognizable name and choose its authentication type: Bearer token, API key, Basic auth, or OAuth2 access token.
2. Save the secret there. Secret values cannot be read back after saving; use Rotate in Settings when replacing an expired token.
3. Return to the API Step. Click Refresh credentials if you created or changed a credential in another tab.
4. Under Authentication, select the saved credential. Only active credentials can be selected.
5. Check Send credential as. Bearer and OAuth2 tokens default to an Authorization header; Basic auth defaults to Basic; API keys default to their saved header name or X-API-Key.
6. For services that require a raw token or key under a different header, select Custom header and enter the header name, such as X-Access-Token. This sends the raw value without a Bearer prefix. Basic auth does not support this option.
7. Click Send, inspect the response, and save the flow. Testing a write request can create a real external record.

Selecting None (no saved credential) clears the saved credential reference; it does not remove manually configured headers. A saved credential replaces any manual value under the same header name. Avoid duplicate authentication headers and never paste a private token into the ordinary Headers table.

If a selected credential is disabled or deleted, its selection remains visible with a warning and Send is unavailable. Enable it in Settings and refresh, choose another credential, or choose None. If the list cannot load, refresh it or sign in again. The server checks credential ownership and active status for every request, including previously saved flows.

Google Sheets testing

For a Google Sheets API request, save an authorized Google access token as Bearer token (or OAuth2 access token with token type Bearer). Select it in the API Step and keep the default Authorization option. Use the Sheets API endpoint, not the spreadsheet's browser sharing URL.

This is manual token authentication: it does not add Google sign-in, file selection, permission grants, or automatic token refresh. A spreadsheet upload or a Google Drive connection elsewhere does not authorize this request. Replace expired tokens through Rotate in Settings. Use fictional data for initial tests and verify the token has permission to the intended file.

Data flow

API Step connects quiz data to external systems and can bring external data back into the quiz.

Placeholders

Use placeholders in endpoint URLs, headers, query parameters, and raw body values:

• {{variable_key}}
• {{total_score}}

Example raw JSON body:

{
  "name": "{{full_name}}",
  "email": "{{email}}",
  "score": "{{total_score}}"
}

Use clean variable keys and test interpolation before publishing. If a request depends on lead data, make sure the Lead Capture step appears before the API Step.

Test with Send

Use Send in the builder to test the request configuration. If the body includes placeholders, the builder asks for test values first so you can validate interpolation before running.

After a test run, review:

• Status code
• Response body
• Response headers
• JSON paths available for capture mappings

Capture response values

Use Capture response to map API response fields into quiz variables.

Path format starts with response, for example:

• response.records[0].id
• response.data.user.email
• response.score
• response.recommendation.slug

Captured values can be reused in later steps, Jump Logic, Agent Steps, and outcome content.

Failure strategy

Not every API call needs to block the quiz.

• Continue silently when the API call is non-critical and the participant experience should not depend on the result.
• Capture response values when later copy or routing depends on the returned data.
• Define a failure destination when the quiz needs a clear fallback path.
• Use helpful recovery copy when an external service is unavailable.
• Test failure behavior before publishing when the API call is part of qualification, pricing, booking, or fulfillment.

Save results before an Agent summary

When an Agent needs saved activity history, place an API Step before the Agent. Your external service must provide the authorized history; adding an API Step does not create a Google Sheets connection automatically.

1. Collect the activity answers and ask the participant to confirm them.
2. Configure an HTTPS service that validates access, saves the confirmed activity and returns a save status plus a small set of relevant history metrics.
3. Map the returned save status and metrics into flow variables using Capture response. The summary depends on these values, so this request must complete before the Agent continues.
4. Give the Agent those captured values and instructions to describe only the supplied results. Calculate comparisons in the service rather than asking the Agent to infer missing history.
5. Configure a failure destination for an unsuccessful request. Explain when a save could not be confirmed; never show a successful-save message merely because the Agent responded.

Use a stable activity identifier and duplicate protection in the external service. A timeout can happen after a write succeeds, so a repeated request must not create a second activity record. Keep the saved record independent of whether the Agent later responds successfully.

For a spreadsheet-backed service, restrict the connection to the intended files and operations. Keep credentials server-side, return only the history needed by the next step, and verify the participant is allowed to access that history. Choosing a team or entering a jersey number alone does not authenticate a participant.

Test first-time participants, missing values, denied access, duplicate requests, timeouts and Agent failures with fictional records before using real participant data. Label sample history clearly; do not present it as actual progress.

Security notes

• API Step requests run server-side.
• Credentials and sensitive headers are not exposed to participants.
• Sensitive headers are redacted in diagnostics.
• Send only the data the external service needs.
• Avoid including unnecessary personal data in webhook payloads.
• Use HTTPS endpoints. API Step does not send requests to non-HTTPS endpoints.

Troubleshooting

API response quick checks

• 400 Bad Request: validate query parameters, body shape, and required fields.
• 401 Authentication required: verify the auth header format.
• 403 Invalid permissions: verify token scope, permissions, or workspace access.
• 404 Not Found: confirm the endpoint URL and route path.
• 409 Conflict: check whether the external service already has a matching record.
• 422 Invalid request body: validate JSON shape, field names, and required values.
• 429 Rate limited: reduce request frequency or check external service limits.
• 500+ Server error: test the external service directly and use a fallback route if needed.

Checklist:

1. Confirm Authorization: Bearer <token> format when bearer auth is required.
2. Confirm Content-Type: application/json when sending JSON.
3. Validate raw JSON syntax.
4. Confirm placeholders use {{variable_key}}.
5. Confirm required lead fields or variables are collected before this step.
6. Re-test in Postman or cURL when you need parity checks.

Tips

• Place API Step after the quiz has collected the data the request needs.
• Keep payloads focused and avoid sending unnecessary personal data.
• Use capture mappings only for values the flow will actually use.
• Add failure routing for critical requests.
• Test successful and failed responses before publishing.
• Document external endpoint ownership so future editors know who maintains the integration.