Guides

How to get forms responses

While the Cortex Fan Data Platform includes features which utilise forms data, there may be a need to get forms data for use in a third party tool.

There are three ways to get forms responses:

  1. Download a CSV from the Cortex platform
  2. Get forms responses via API
  3. Get forms responses via webhook

These methods are explained below.

Download a CSV from the Cortex platform

In the Cortex platform, open the form for which you want to download responses. Switch to the _Responses tab, at the top of the screen. From there you can download all responses to the form.

Get forms responses via API

This API is protected by a requirement for an API key, and that API key must be generated by Cortex staff. So, if you haven't taken this step already, the first step is to contact Cortex and request an API key for the GET forms responses endpoint.

Requirements

In order to fetch article summaries, the following request headers are required:

  1. X-APP-ID
    Purpose: Identifies the application making the API request.
    Description: This header contains the unique identifier associated with the application initiating the API call. It helps the server recognise and authorise requests from specific applications.
  2. X-API-KEY
    Purpose: Authenticates and authorises the API request.
    Description: This header carries the API key associated with the application, serving as a secure way to verify the identity of the requester and control access to the API resources.
  3. X-CLIENT-ID
    Purpose: Specifies the Cortex client making the API request.
    Description: It provides additional context for the server to apply the appropriate authentication mechanisms.

Additionally, API calls must be made from a server-side platform. The end-user or web browser should
not be fetching forms responses, as this may lead to security vulnerabilities and practical issues.

The forms responses API call

The API construct to fetch forms responses looks like this:

💻

GET {base URL}/v1/external/forms/{form-id}/responses

In which:

{base URL} is the URL shown below, depending on environment used.

{form-id} is the identifier of the individual form for which responses are required. This can be obtained from the Cortex platform, or via API.


Get forms responses via webhook

On form submission, Cortex forwards the captured data via POST to a configured receiver URL. Only one response is sent at a time and delivery order is not guaranteed.

This webhook can be configured in Cortex. For setup instructions, see Webhooks.

Event

The webhook fires on the forms.submission event. The full form response is included in the request body.

If the Cortex team previously issued you webhook credentials, we recommend migrating to a self-managed webhook. See Migrating from legacy webhooks below.

Retries and Timeouts

Webhook requests that timeout, respond with a non-2xx status code, or otherwise fail will be retried using an exponential back-off strategy until they are eventually discarded after too many attempts.

Migrating from legacy webhooks

If your integration was configured by the Cortex team and uses X-APP-ID and X-API-KEY header authentication, follow these steps to migrate to a self-managed webhook.

  1. In Cortex, go to Settings > Webhooks and create a new webhook endpoint pointing to the same receiver URL.
  2. Copy the generated secret before leaving the creation screen.
  3. Update your endpoint to validate the X-Cortex-Signature header instead of X-APP-ID and X-API-KEY. See Webhooks for verification steps and code examples.
  4. The event type is now forms.submission, delivered in the payload envelope event field rather than as a separate header.
  5. Test with a live form submission and confirm signature validation passes.
  6. Once satisfied, contact the Cortex team to disable the legacy webhook.

Updated 3 days ago