Introduction

The Cortex Forms product includes a fan-facing front end component, with customisable styling, which can be embedded into any website or app using a brief javascript embed code, as explained in How to embed a form. However, there may be a need for something more bespoke, so this article explains how to create a custom forms component.

Endpoints

Base URL (production-standard): https://forms.cortextech.io

Base URL (production-USA): https://forms.cortextech.us

General form actions:

/v1/{clientId}/forms

Method	Description	Parameters
GET	Get a list of forms for a given client	tags, publish from, publish to, linked IDs

Actions relating to a specific form:

/v1/{clientId}/forms/{id}

Method	Description	Parameters
GET	Get a specific form	N/A
POST	Submit answers to a form	N/A

Response

Base

Key	Data Type	Required	Notes
id	string	Y	Unique identifier per form, generated by the backend on form creation.
clientId	string	Y	Unique identifier for the client, as per client in Cortex.
title	string	Y	The title of the form.
description	string	Y	Space to write a more detailed description of the form.
language	string	Y	Represents the language in which the form is created.
publishFrom	string? (rfc3339)	N	The date the form should be "published" from.
publishTo	string? (rfc3339)	N	The date the form should be available to. Any submitted answers will not be saved from this point onward.
tags	string array	Y	Tags associated with the form, can be used for searching.
linkedIds	linkedId array (see below)	Y	A list of associated IDs related to the form, identical to other Cortex systems, this will be an ID relating an external data provider such as Opta, and will allow for searching.
createdDetails	editor (see below)	N	Information relating to the Cortex user that created the form. Generated by backend on form submission.
lastEdited	editor (see below)	N	Information relating to the Cortex user that last edited the form. Generated by backend on form submission.
sections	field array (see below)	Y	Fields are grouped by section, a user must fill in one section's fields before they can see the next. Currently, there will only be one section, and it is not possible to create additional sections via Cortex. This has been included to accommodate potential future development, which at time of writing is not scheduled.
heroMedia	heroMedia (see below)	N	Content block to render at the top of the form. Follows the same logic as hero content in other Cortex systems.
success	success (see below)	Y	Contains information about what actions to perform once the form has been submitted.
displayOptions	display Options (see below)	Y	Display options for fan-facing forms.
submitButton	submitButton	N	Represents the submit button configuration for fan-facing forms.
theme	Theme	N	Represents the theme.

linkedId

Key	Data Type	Required	Notes
text	string	Y	Textual representation of the linked ID (used for rendering in Cortex)
sourceSystem	string	Y	The data source of the linked ID, e.g. OPTA_FOOTBALL = football team from Opta's feeds
sourceSystemId	string	Y	The ID of the linked item in the data source's system

editor

Note due to privacy, the only information returned from the API will be the date field, all other fields will not be displayed and are purely for internal use.

Key	Data Type	Required	Notes
date	datetime	Y	The date this user interacted with this object. NOTE- this is the only field that is visible via the API, all other fields are internal only.

field

Key	Data type	Required	Notes
id	string	Y	Each field needs a unique key in order to link up the conditional logic shown later. This will need to be defined by frontend.
index	uint	Y	One-based (i.e. starting from one) indexing of fields, which persists across sections.
label	string	Y	The title of the field, should be the question.
description	string	N	The description of the field, should be some form of elaboration on the question
linkUrl	string	N	If the field has an external link associated with it, the URL will be provided here
linkText	string	N	If the external link is to wrapped in text, it will be provided here
type	string	Y	Specifies the type of input to display to the user. When the type includes subtypes, both the type and subtype are provided. The subtype should be used to determine the specific field type to present to the user.
subtype	string	Y (if the type has a subtype)
metadata	metadata (see below)	N	Metadata relating to the data capture

type

Field types	Subtype	Description	Notes
shorttext	n/a	Represents a short text input field, typically with a limited character count.
longtext	n/a	Represents a multi-line text input field, suitable for longer descriptions or comments.
client_preference	n/a	Represents a field for capturing client preferences, which could vary in format based on specific requirements or context.	Preferences, and their options, are set centrally in the Cortex platform outside of Forms. The preferences service has use cases in other Cortex products, particularly SSO. Hence, the same preference questions can be displayed in a form as in an SSO registration.
choice		Represents a field for providing a selection of choices or options, allowing users to pick one or more selections from a predefined list.
	checkbox	Represents a checkbox input field, allowing users to select multiple options.
	radio	Represents a radio button input field, allowing users to select only one option from a list.
	select	Represents a dropdown select input field, allowing users to choose one option from a list.
account_detail		Represents a field for capturing detailed information related to a fan’s account or contact information. Note: If an authentication token is present, any submitted values associated with these field types will be overwritten by the corresponding values in the token claims. Therefore it is recommended to prefill and disable or hide these fields if a token is present.
	email	Represents a field for entering an email address.
	first_name	Represents a field for entering a first name.
	last_name	Represents a field for entering a last name.

metadata

Key	Data type	Required	Notes
value	Depends on field type (see below)	N	(see below)
validation	validation (see below)	N	Logic relating to validating the input
conditions	node array (see below)	N	If the rendering of this field is reliant on an answer provided in a previous question, the conditions are stored here.

validation

Key	Data type	Required	Notes
required	boolean	N	`true` indicates an answer is required for this field
min	Depends on field type. (see below)	N	(see below)
max	Depends on field type. (see below)	N	(see below)
regexPattern	string	N	Should a regular expression pattern be applied to the submitted input? If so, the regex can be entered in Cortex and will be provided here.
type	string	N	(see possible values below)

Type validation rules

Key	Notes	Examples
email	A syntactically valid email address is expected.	[email protected]
number	A valid number is expected. Decimals (the radix character must be a period), positive and negative numbers are all considered valid. Thousand separated numbers are not supported.	1234 +1234 -1234 1.234
phone	A phone number, in E.164 international format, is expected.	+442031379873 +4420 3137 9873 +44(0)2031379873

Per field type validation rules

Field types	Subtypes	Validation rules	Validation data type	User input data type	Notes
shorttext, longtext	n/a	min, max	int	string	Require the provided string to be equal, less than or greater than the minimum and maximum values respectively in length.
choice	checkbox, select	min, max	array	array (equal to or a subset of the metadata value)	Require a minimum or maximum number of selected choices.
account_detail	email			string	Expects a syntactically valid email address.
client_preference	n/a			int	Expects a valid preference ID

Validation error codes

Error code	Field types	Description
`invalid_type`	All	Value does not meet expected data type.
`invalid_value`	choice (any subtype)	If validating against an array of values (e.g. possible checkbox options), returned if the value(s) are not contained in the submitted array.
`missing_required_field`	All	Required field is missing a value, or is an empty array or an empty string.
`min_length_required`	shorttext, longtext, choice (where subtype is checkbox)	If value is a string, the value is less than `metadata.validation.min` in length. If the value is an array, the value has less than `metadata.validation.min` elements.
`min_value_required`	shorttext (where validation type is set to number)	Number value is less than `metadata.validation.min`.
`max_length_exceeded`	shorttext, longtext, choice (where subtype is checkbox)	If value is a string, the value is greater than `metadata.validation.max` in length. If the value is an array, the value has greater than `metadata.validation.max` elements.
`max_value_exceeded`	shorttext, where validation type is set to number	Number value is greater than `metadata.validation.max`.
`regex_pattern_match_error`	shorttext	String value does not match regex pattern.
`invalid_email_address`	shorttext (where validation type is set to email), account_detail (where subtype is email)	String value is not a syntactically valid email address.
`invalid_phone_number`	shorttext (where validation type is set to phone)	String value is not a valid international phone number.

node

Key	Data type	Required	Notes
type	string	Y	Indicates the action this node should perform, current values: `AND`: all child nodes should return true `OR`: only one of the child nodes should return true `EVAL`: evaluate this node directly (no need to drill down to children)
key	string	N	If EVAL this should be the key of the related field previously defined.
value	object	N	If EVAL this should be the expected value of the field. Note this can be a string, integer, boolear or array of items.
operator	string	N	If EVAL the comparator operation to perform between key and value.

Example conditions:

Answer to previous question is "Vegetarian". In this case, if the user has supplied "Vegetarian" as the answer of question 1, render this question:
```
{
  "conditions": [
    {
      "type": "EVAL",
      "key": "question1",
      "value": "Vegetarian",
      "operator": "EQUAL"
    }
  ]
}
```

OR example answer to previous question is Vegetarian OR Vegan.

{
  "conditions": [
    {
      "type": "OR",
      "nodes": [
        {
          "type": "EVAL",
          "key": "question1",
          "value": "Vegetarian",
          "operator": "EQUAL"
        },
        {
          "type": "EVAL",
          "key": "question1",
          "value": "Vegan",
          "operator": "EQUAL"
        }
      ]
    }
  ]
}

AND example the answer to question 1 must be Vegetarian and the answer to question 2 must be Vegan

{
  "conditions": [
    {
      "type": "AND",
      "nodes": [
        {
          "type": "EVAL",
          "key": "question1",
          "value": "Vegetarian",
          "operator": "EQUAL"
        },
        {
          "type": "EVAL",
          "key": "question2",
          "value": "Vegan",
          "operator": "EQUAL"
        }
      ]
    }
  ]
}

heroMedia

Key	Data Type	Required	Notes
content	content	N	`contentType` may be `IMAGE` or `VIDEO`. If `contentType: "IMAGE"`, `imageUrl` will be provided. If `contentType: "VIDEO"`, then `sourceSystem: "YOUTUBE"`, `link` and `sourceSystemId` will all be provided.

success

Key	Data Type	Required	Notes
action	string	Y	The action to perform when the form is successfully submitted, can be: content, link.
linkUrl	string	N	The URL to redirect the user to if action is defined as "link", or to display as a link if action is "content".
linkText	string	N	The link text to display if action is defined as "link" and a linkUrl is provided.
paragraph	string	N	Display a success message on submission.
content	content	N	If the action is "content", the content block to render. This is the standard content block model used elsewhere in Cortex systems. Currently, possible contentTypes include "IMAGE" and "VIDEO".

displayOptions

Key	Data Type	Required	Notes
hideTitle	boolean	N	Flag to toggle title visibility in fan-facing forms.

submitButton

Field	Type	Required	Description
label	string	N	Text to display as the submit button e.g. "Enter competition".

theme

Field	Type	Description
titleFont	Font	See explanation below.
captionFont	Font	See explanation below.
captionFontColor	string	Value provided as a hexadecimal code e.g. `#000000"`.
backgroundColor	string	Value provided as a hexadecimal code e.g. `"#000000"`.
backgroundBorderColor	string	Value provided as a hexadecimal code e.g. `"#000000"`.
backgroundRadius	string	Value can be one of `"SHARP"`, or `"SMOOTH"`
buttonFont	Font	Object including name, size, url, and allCaps. See explanation below.
buttonFontColor	string	Value provided as a hexadecimal code e.g. `"#000000"`.
buttonBackgroundColor	string	Value provided as a hexadecimal code e.g. `"#000000"`.
buttonBorderColor	string	Value provided as a hexadecimal code e.g. `"#000000"`.
buttonRadius	string	Value can be one of `"SHARP"`, `"SMOOTH"`, or `"PILL"`
questionLabelFont	Font	See explanation below.
responseFont	Font	See explanation below.
selectedField Color	string	Value provided as a hexadecimal code e.g. `"#000000"`.
unselectedField Color	string	Value provided as a hexadecimal code e.g. `"#000000`".
errorColor	string	Value provided as a hexadecimal code e.g. `"#000000"`.
questionLabelFontColor	string	Value provided as a hexadecimal code e.g. `"#000000"`.
responseFontColor	string	Value provided as a hexadecimal code e.g. `"#000000"`.

Font

Field	Type	Description
name	string
size	integer
url	string
allCaps	boolean

Answer

Base

Key	Data Type	Required	Notes
fields	field array (see below)	Y	The answers for each field are stored here.

field

Key	Data Type	Required	Notes
id	string	Y	The key of the field when the form was generated.
value	string	Y	The submitted response to the field, by the user.