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.

• Standard environment: https://forms.cortextech.io
• US environment: https://forms.cortextech.us

{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

The forms responses webhook must be set up by Cortex staff. So, if you haven't taken this step already, the first step is to contact Cortex and request setup of the forms responses webhook, specifying your receiver URL to which data should be sent.

Once set up, on form submission, Cortex will forward the captured data via webhook to a configured address (the receiver URL). Only one form response at a time will be forwarded, and the order of forwarded messages cannot be guaranteed.

Authentication

Included in the POST request's header are several authentication headers (see below). These credentials MUST be verified using a constant-time method to confirm the sender's identity (i.e. the request originates from Cortex). Any requests that fail your checks must be discarded.

Origin Authentication Headers

• X-APP-ID
• X-API-KEY

Both are configured by Cortex and will be confirmed when the webhook is enabled.

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.