Overview

Once an API call has been made, for a player or players as described in API call specifications for players and teams it returns a JSON response of fields and values for use in the creation of your web or app content. This page tabulates the JSON data in the response.

Tabulation of JSON provided by the players API

Field	What to expect in the JSON	Typical use cases
`id`	String. Mandatory.	A unique identifier for the player. It is intended for developer use only and would not normally be visible to fans.
`forename`	String. Mandatory, and free text in Cortex.	Display the player’s first or given name.
`surname`	String. Mandatory, and free text in Cortex.	Display the player’s last or family name.
`alias`	String. Optional, and free text in Cortex. If left blank in Cortex then this field will be omitted in the JSON.	Used as the primary identifier for the player where `forename` followed by `surname` would not be suitable. For example, Edson Arantes do Nascimento is better known as Pelé, and therefore the alias would be Pelé. Expected logic is therefore to use `alias` where available; otherwise, use `forename` `surname` as the primary identifier. Alternatively, depending on design and client requirements, the `alias` field could be used to show a nickname alongside the `forename` and `surname`.
`headshot`	Object including two fields - `altText` and `imageUrl`. See breakdown below. If no image URL is added in Cortex then `null` will be provided.	Display the primary image of the player.
`headshot` > `imageUrl`	String. Optional in Cortex, with URL validation including that http:// or https:// must be included. Users are encouraged to use an image URL.	URL for the primary image of the player.
`headshot` > `altText`	String. Generated automatically, and therefore should always be provided. Logic is to use `alias` where available; and where alias is not available, use `forename` `surname`.	Alt text for the primary image of the player.
`slug`	String. Mandatory, and free text in Cortex but with validation to ensure there are no spaces, upper case letters, or special characters. Additionally, a uniqueness constraint is applied, so that no two players will have the same slug. Where content is multilingual, this uniqueness constraint applies per language.	Typically this would be used to form the last part of the URL on which the player profile will be displayed. For example where the slug value is `pele`, the URL may be `https://www.example.com/en/players/pele` This could be used in conjunction with the slug provided as part of the team and/or position. For example the team slug may be `new-york-cosmos-first-team`, and the position slug may be `forwards`, giving the URL `https://www.example.com/en/players/new-york-cosmos-first-team/forwards/pele`
`biography`	String. Optional, and free text in Cortex. Expect text to be provided in markdown format. In Cortex, a text editor is provided with buttons such as bold, italic, links, and more, which will all add markdown to the string. If left blank in Cortex then this field will be omitted in the JSON.	Typically this would be used as the biographical text. Note that, in addition to `biography`, there is `content` which is described below. These two fields may be used for similar use cases. Depending on design and client requirements, you may chose to support one or both of these fields. For example: - Where requirements are for a single body of biographical text, and text-only with no other content types (image, video etc), it makes sense to use the `biography` field as it is most prominent in Cortex. - Where biographical text needs to include other content types (image, video, etc), in among the text, use `content`. - Where there are two bodies of biographical text on the page, you might choose to use `biography` for one and `content` for the other. A typical example being: `biography` used as a short summary shown in the page hero, and `content` used for long-form text shown in a separate section.
`content`	Array of objects, where each object represents a content block. Each will include an `id`, representing the ID for that individual block; a `contentType`, representing the type of block; and additional fields depending on the type of block. Possible values for `contentType` will match those used elsewhere in the InCrowd CMS, with the full list being `IMAGE`; `TEXT`; `VIDEO`; `GALLERY`; `PROMO`; `QUOTE`; `CLOUD_MATRIX`; `RELATED_CONTENT`; `POLL`; `ADVERT`; `COLLECTION`; `CUSTOM`; `FEED`; `BUTTON`; `FORM`; and `LIVE_BLOG`. For a full breakdown of the fields and expected use cases of each block, see JSON response table for articles and pages If no blocks are added in Cortex, then this field will be omitted in the JSON.	Biographical content. See note above under `biography`. Additional use cases may be achieved with this feature, particularly via the custom block.
`language`	String. Mandatory. Where the account does not use multilingual features, `en` will be provided. The value will be a code, applying the BCP-47 standard, representing the language or locale of the player content, as set in Cortex. Where a player includes multilingual content, the API will provide the language variant specified in the API call, if available. If no such variant is available, then the API will include a variant matching any fallback languages specified in the API call, if available. Fallback languages may include `default`, so that if no other match is available, then the API will include a variant matching the default locale, set per player in Cortex.	This may be used to place content in the correct multilingual webpage.
`linkedIds`	An object which may include data providers and their internal data IDs. The format for linked IDs is as follows: `<br/>{ "text": "Pele Smith", <br/>"sourceSystem": "OPTA_FOOTBALL_PLAYER", <br/>"sourceSystemId": "645136" }<br/>` If left empty in Cortex, an empty array will be provided in the JSON.	To pull data from other sources. For example, you might want to display, within the player profile, a list of articles, or statistical information, associated to the same linked ID as specified in the player. Additionally, this may work in the other direction. Information from the player profile could be pulled into other components where this ID is known. For example, the headshot from the players service could be used in a match centre.
`accolades`	Array of objects, where each object may contain a `label`, `description` and `count`. See breakdown below. If no accolades are added in Cortex, an empty array will be provided in the JSON.	Display awards and accolades such as trophies or personal achievements won by the player.
`accolades` > `label`	String. Mandatory, and free text in Cortex.	Since this is the only mandatory field of an accolade, it should be used as the primary text or name of the accolade, if your platform is supporting the accolades feature. For example Player of the year
`accolades` > `description`	String. Optional, and free text in Cortex. If left blank in Cortex then this field will be omitted in the JSON.	Description would normally be text shown secondary to the label. Depending on design, it may well be omitted altogether. For example Player of the year 2023/24 season
`accolades` > `count`	Number. Optional, and any number can be provided as long as it is 0 or greater. If left blank in Cortex then `null` will be provided.	Depending on design, you may wish to use the accolades feature to show repeating achievements with a number to represent the times won by the player. For example Grand slams x 4
`merchandise`	Array of objects, where each object may contain`imageUrl`, `linkUrl` and `text`. See breakdown below. Since only `linkUrl` is mandatory, you will need to handle the following scenarios: - `linkUrl` only is provided - `linkUrl` and `imageUrl` are both provided - `linkUrl` and `text` are both provided - `linkUrl, imageUrl` and `text` are all provided If no merchandises are added in Cortex, an empty array will be provided in the JSON.	Display links to retail journeys associated with the player. For example to purchase a replica shirt or jersey featuring the player’s name. Where `linkUrl`, `imageUrl` and `text` are all provided, you might choose to use the value in `text` as alt-text for the image, or display it, depending on design.
`merchandise` > `imageUrl`	String. Optional, with URL validation in Cortex including that http:// or https:// must be included. Users are encouraged to use an image URL. If left blank in Cortex then this field will be omitted in the JSON.	Show an image as the link or alongside it, or ignore this field altogether, depending on design.
`merchandise` > `linkUrl`	String. Mandatory, with URL validation in Cortex including that http:// or https:// must be included.	The destination URL of the retail link.
`merchandise` > `text`	String. Optional, and free text in Cortex. If left blank in Cortex then this field will be omitted in the JSON.	Show text as the link or alongside it, or ignore this field altogether, depending on design. Where `imageUrl` and `text` are both provided, you might choose to ignore the text, or to use it as alt text for the image.
`socials`	Array of objects, where each object may contain a `handle`, `provider` and `url`. See breakdown below. If no socials are added in Cortex, an empty array will be provided in the JSON.	Display links to the player’s social accounts.
`socials` > `handle`	String. Optional, and free text in Cortex. If left blank in Cortex then this field will be omitted in the JSON.	Display the player’s handle.
`socials` > `provider`	String. Mandatory, and selected from a dropdown in Cortex. Possible values are `FACEBOOK`, `REDDIT`, `TWITTER`, `YOUTUBE`, `TWITCH`, `INSTAGRAM`, `THREADS`, `TIKTOK`, and `OTHER`.	Display an icon to indicate the social media platform. If any of the possible values are not going to be supported on your platform, you might choose to filter out any `socials` object with an unsupported `provider`.
`socials` > `url`	String. Mandatory, and free text but with URL validation in Cortex, including that http:// or https:// must be included.	Destination URL for the link to the player’s social account.
`sponsors`	Array of objects, where each object may contain `imageUrl`, `linkUrl` and `text`. See breakdown below. In Cortex it is mandatory that one of `imageUrl` and `text` is provided. Therefore you will need to handle the following scenarios: - `imageUrl` only is provided - `text` only is provided - `imageUrl` and `text` are both provided - `imageUrl` and `linkUrl` are both provided - `text` and `linkUrl` are both provided - `linkUrl`, `imageUrl` and `text` are all provided If no sponsors are added in Cortex, an empty array will be provided in the JSON.	Display a sponsor or sponsors of the player.
`sponsors` > `imageUrl`	String. Optional where there is a value for `text`, otherwise it’s mandatory. URL validation in Cortex including that http:// or https:// must be included. Users are encouraged to use an image URL. If left blank in Cortex then this field will be omitted in the JSON.	Display the sponsor logo or other image representing the sponsor.
`sponsors` > `linkUrl`	String. Optional, with URL validation in Cortex including that http:// or https:// must be included. If left blank in Cortex then this field will be omitted in the JSON.	Destination URL for a link to the sponsor’s website.
`sponsors` > `text`	String. Optional where there is a value for `imageUrl`, otherwise it’s mandatory. Free text in Cortex. If left blank in Cortex then this field will be omitted in the JSON.	Display the name of the sponsor, if no `imageUrl` is provided; or where both `imageUrl` and `text` are provided, use as alt-text for the image. Alternatively, you may wish to display the text in addition to the image, depending on design.
`attributes`	Object which may include `team`, `position`, `captain`, `dateOfBirth`, `debutDate`, `height`, `loanStatus`, `nationality`, `signedDate`, `squadNumber`, or `weight`. These are described in more detail below. In Cortex these attributes are not shown by default but can be added in by the user. As a developer, you can save empty attribute fields as part of a template in Cortex, to help Cortex users to understand which attributes are supported in your website or app. If no attributes are added in Cortex, an empty object will be provided in the JSON.	Attributes are a collection of player details which are fairly common to display on player profiles, but by no means universal. For example weight may be of interest to rugby or boxing fans, but less interesting to fans of golf.
`attributes` > `team`	Object including `name`, `slug` and `linkedIds`. See breakdown below. Mandatory, and selected from a dropdown in Cortex. Possible values are defined by the Cortex user in a centralised list, in the settings menu of the Players section of Cortex. If left blank then it is omitted in the JSON. Where content is multilingual, the team will be provided in a language or locale to match the language in which the player is provided, if available. If no such team variant is available, the default variant of the team will be provided instead. The language variants of each team, including the default, are set in Cortex, when creating or editing a team.	Indicate the team or squad that the player represents, and/or show the players in a section filtered to that team or squad.
`attributes` > `team` > `name`	String. Mandatory, and free text.	Display as the team name.
`attributes` > `team` > `slug`	String Mandatory, and free text but with validation to ensure there are no spaces, upper case letters, or special characters. Additionally, a uniqueness constraint is applied, so that no two teams will have the same slug. Where content is multilingual, this uniqueness constraint applies per language.	Use as a unique identifier in order to show the players in a section filtered to that team or squad.
`attributes` > `team >` `linkedIds`	Object which may include data providers and their internal data IDs. It is optional, and if no linked ID is added then the field will be omitted. The format for linked IDs is as follows: `<br/>{ "text": "Inter Miami CF",<br/>"sourceSystem": "OPTA_FOOTBALL_TEAM",<br/>"sourceSystemId": "t14880" }<br/>` If left empty in Cortex, an empty array will be provided in the JSON.	To pull data from other sources. For example, you might want to display, within the player profile, a link to a team page, articles pertaining to that team, or statistical information. Additionally, this may work in the other direction. For example, on a team page, you may want to pull-in players that are associated to a team with the corresponding team ID.
`attributes` > `position`	Object including `name` and `slug`. See breakdown below. Mandatory, and selected from a dropdown in Cortex. Possible values are defined by the Cortex user in a centralised list, in the settings menu of the Players section of Cortex. If left blank then it is omitted in the JSON. Where content is multilingual, the position will be provided in a language or locale to match the language in which the player is provided, if available. If no such position variant is available, the default variant of the position will be provided instead. The language variants of each team, including the default, are set in Cortex, when creating or editing a team.	Indicate the position that the player plays in, and/or show the players in a section filtered to that position.
`attributes` > `position` > `name`	String. Mandatory, and free text.	Display as the position name.
`attributes` > `position` > `slug`	String. Mandatory, and free text but with validation to ensure there are no spaces, upper case letters, or special characters. Additionally, a uniqueness constraint is applied, so that no two teams will have the same slug. Where content is multilingual, this uniqueness constraint applies per language.	Use as a unique identifier in order to show the players in a section filtered to that position.
`attributes` > `dateOfBirth`	Date. Optional, and provided in the format YYYY-MM-DD. If left blank in Cortex then this field will be omitted in the JSON. Where content is multilingual, the value provided by this field will be consistent across all language variants.	Display the player’s date of birth.
`attributes` > `debutDate`	Date. Optional, and provided in the format YYYY-MM-DD. If left blank in Cortex then this field will be omitted in the JSON. Where content is multilingual, the value provided by this field will be consistent across all language variants.	Display the date the player made their first competitive appearance. For team or club websites, this might be their first appearance for that team or club; whereas for single-player competitions this may be their first competitive appearance generally.
`attributes` > `height`	Number. Optional, with validation to ensure that it is at least 1. If left blank in Cortex then this field will be omitted in the JSON. Where content is multilingual, the value provided by this field will be consistent across all language variants. Note that Cortex users are asked to enter in cm, so depending on design some conversion may be required.	Display the player’s height.
`attributes` > `loanStatus`	String. Optional, and selected from a dropdown in Cortex. Possible values may be either `InOnLoan` or `OutOnLoan`. If left blank in Cortex then this field will be omitted in the JSON. Where content is multilingual, the value provided by this field will be consistent across all language variants.	For team or club scenarios, indicate that the player is in on loan (playing for this club but contracted elsewhere) or out on loan (contracted to this club but currently playing elsewhere). Depending on requirements, you may wish to flag a player as being on loan, display on loan players in a separate section, or hide them altogether. In some cases, different behaviour may be desired for those players who are in on loan vs out on loan.
`attributes` > `nationality`	String. Optional, and selected from a dropdown in Cortex. Possible values are codes using either ISO 3166-1 alpha-2 codes for countries (e.g. BR for Brazil), or one of four ISO 3166-2 codes for subdivisions of the United Kingdom (GB-ENG, GB-NIR, GB-SCT, or GB-WLS). If left blank in Cortex then this field will be omitted in the JSON. Where content is multilingual, the value provided by this field will be consistent across all language variants.	Display the player’s nationality. Bear in mind that there may be a discrepancy between the player’s legal nationality and the national team they represent. We find that best practice is normally to use the latter (their national team), but preferred behaviour may differ from sport to sport or client to client.
`attributes` > `signedDate`	Date. Optional, and provided in the format YYYY-MM-DD. If left blank in Cortex then this field will be omitted in the JSON. Where content is multilingual, the value provided by this field will be consistent across all language variants.	For team or club use cases, display the date the player signed for that team or club.
`attributes` > `squadNumber`	String. Optional, and free text in Cortex. If left blank in Cortex then this field will be omitted in the JSON. Where content is multilingual, the value provided by this field will be consistent across all language variants. Note: It is intentional that this is a string field rather than a number. This is because there are some sports where a player may have 00, 01, etc as their squad number.	Display the player’s squad/shirt/jersey number.
`attributes` > `weight`	Number. Optional, with validation to ensure that it is at least 1.e. If left blank in Cortex then this field will be omitted in the JSON. Where content is multilingual, the value provided by this field will be consistent across all language variants. Note that Cortex users are asked to enter in kg, so depending on design some conversion may be required.	Display the player’s weight.
`customAttributes`	Includes objects where the key, as well as the fields `label`, `type`, and `value` are all set by the Cortex user. - The key will always be in camel case as it is validated as such in Cortex. - `label` is free text with no validation. - `type` is provided as a string but can only be one of `number`, `boolean`, `date`, `string` or `media` (in which c. - `value` may be a number, boolean, date or string, depending on the selection made in the `type` field. Where `type` is `media`, the `value` will be a URL for a media file. In Cortex these attributes are not shown by default but can be added in by the user. As a developer, you can save empty custom attribute fields as part of a template, to help Cortex users to understand which custom attributes are supported in your website or app, and the correct format for these. Where content is multilingual, `customAttributes` will be consistent across all language variants. If no custom attributes are added in Cortex, an empty object will be provided in the JSON.	Generally speaking, the use cases of custom attributes may vary greatly from one project to another. The feature is designed to power fan-facing features not achievable by existing fields. For example, if a design included a space for the player’s favourite pre-match song, this could be achieved via custom attributes. In terms of the individual fields: - The key is intended for developer use only, in order to distinguish one custom attribute from another. Since it will be in camelCase, it would normally not be suitable to display to fans. - `label` could be used where the field label should be displayed to fans. For example it might say “Favourite song:” - `type` is mostly useful within Cortex as it defines what kind of input field will be displayed to the Cortex user for the `value` field. It may also be useful to developers as an indicator of what to expect from the `value` field. - `value` would normally be the key piece of information shown to fans. In the example used above, it would be the title of the player’s favourite song.