Documentation

Calling external APIs

When and Why to Use

Use this to make outbound HTTP requests to approved external APIs during a survey. This is useful for:

Personalizing content based on real-time data
Validating input or IDs
Logging or syncing responses to external systems

⚠️ Note: All external domains must be allow-listed by MX8 Labs prior to use.

Configuration Options

Parameter	Type	Required	Default	Description
`url`	`str`	yes	-	Full endpoint URL (must be allow-listed). May contain a `{respondent_id}` placeholder
`method`	`str`	yes	-	HTTP method: "GET" or "POST" (case-insensitive)
`data`	`Dict`	no	`None`	Form data sent in the body of `POST` requests
`params`	`Dict`	no	`None`	URL query parameters for `GET` requests
`headers`	`Dict`	no	`None`	Additional HTTP headers (e.g. auth tokens)
`timeout`	`int`	no	`10`	Request timeout in seconds

Example Code

response = s.call_api(
    url="https://api.myservice.com/userinfo/{respondent_id}",
    method="GET",
    params={"fields": "segment"},
    headers={"Authorization": "Bearer xyz123"},
)

For a POST request:

s.call_api(
    url="https://api.myscorer.com/evaluate",
    method="POST",
    data={"answers": user_answers},
)

Notes

Only allow-listed domains will work - contact MX8 Labs to add new domains
Any {respondent_id} placeholder in the url is replaced with the current respondent's ID before the request is made
call_api returns the response body as a StringResponse, which you can capture and use in follow-up logic
Only HTTP 200 responses are accepted — a disallowed domain or any other response status raises a SurveyValidationError
Simulation and other machine-generated runs skip the network request and return an empty StringResponse, so simulated respondents never hit your API