Contract
- Raiko Pajur
Table of Contents
Contract
What is Contract? Contract is the real-life representation of a relation between Competitor and Person e.g. Persons in Teams' squad, Persons training Persons, Dogs, Horses, Players, Doubles Partnerships, etc.
A Contract can be proposed through the Fixtures API v2 on endpoint /v2/contracts
In order to create a Contract first you need to have both Competitor and Person created.
A Contract will be considered as duplicate when all of the properties GSS Person Id, GSS Competitor Id and PersonRole match any of the already existing Contracts in the GSS system.
A Contract can be requested through the Fixtures API v2 on endpoint /v2/competitors/{gss_competitor_type}/{gss_competitor_id}/contracts and /v2/persons/{gss_person_id}/contracts
When to use
A Contract can be used to associated a Person and a Competitor in specific manner e.g. To add Persons to the Squad of a Team, or to add Person on a Player.
How to use
The Contract entity can be used to extract the all the contracts (a.k.a relation between Persons and Competitors) and vice versa by calling either /v2/competitors/{gss_competitor_type}/{gss_competitor_id}/contracts or /v2/persons/{gss_person_id}/contracts endpoints on Fixtures API v2.
Example workflow
GET GSS Teams from Fixtures API v2
curl --location --request GET 'https://ci.fixtures.api.geniussports.com/v2/competitors/teams' \ --header 'x-api-key: <<api_key>>' \ --header 'Content-Type: application/json' \ --header 'Authorization: <<id_token>>' \ --data-raw ''Successful response would be with status code 200 and JSON data in format:
{ "page": 0, "pageSize": 0, "totalItems": 0, "items": [ { "metadataProperties": [ { "name": "string", "value": "string" } ], "id": 0, // GSS Team Id "name": "string", // GSS Team Name "sport": { "Id": 0, // Defines what competitors and in what fixtures, seasons, rounds the team can be used "Name": "string", "ref": "/sports/{id}" // Endpoint on which Sport is available }, "locality": { "Id": 0, // GSS Locality Id the locality from where the referee is "Name": "string", "ref": "/localities/{id}" // Endpoint on which the Locality is available }, "player": { "id": 0, // The GSS Id of the corresponding player for this person "name": "string", // The name of the corresponding player for this person "ref": "string" // Endpoint on which the corresponding player is available }, "genderType": "string", // The gender of the Team (defines in which seasons it can be used (e.g. season with gendertype Male cannot include teams with gender type Female) "competitorStatusType": "string", // Defines whether the player can be used in teams or in fixtures. It can only be used if the status is set to 'Active' "createdOn": "2021-11-29T11:02:48.077Z", "modifiedOn": "2021-11-29T11:02:48.077Z", "venue": { "Id": 0, // Possible venue considered as home venue "Name": "string", "Ref": "/venues/{Id}" } } ], "self": "string", "previous": "string", "next": "string", "first": "string", "last": "string" }GET Active Contract for any of the retrieved GSS Team Ids:
curl --location --request GET 'https://ci.fixtures.api.geniussports.com/v2/competitors/teams/{gss_team_id}/contracts' \ --header 'x-api-key: <<api_key>>' \ --header 'Content-Type: application/json' \ --header 'Authorization: <<id_token>>' \ --data-raw ''Successful response would be with status code 200 and JSON data in format:
Read Data Points
Field | Type | Nullable | Description |
|---|---|---|---|
id | int64|unsigned |
| The numeric identifier of the Contract |
sport | SportEmbed |
| The numeric identifier, name and a reference of the Sport for which the contract was created |
person | object|PersonEmbed |
| The Person to which the contract is created |
isActive | boolean |
| Defines whether the Contract is active or not. It also defines rules about lineups. Whether the Person to which the Contract is created can be used as Lineup for the Competitor or not. |
personRole | string|in: PlaysFor, TrainedBy, BredBy, OwnedBy, RiddenBy |
| Defines the person role in the Contract: 0 - OwnedBy → Owned by defines relation where the Person owns the Team, Dog, Horse, etc. 1 - PlaysFor → Plays for defines relation where the Person plays for a Team. 3 - Trainedby → Trained by defines relation where the Team, Dog, Horse, Player, Doubles Partnership are trained by a Person 5 - RiddenBy → Ridden by defines relation where the Person is a jockey of a Horse 6 - BredBy → Bred by defines relation where the Horse, Dog is bred by a Person |
createdOn | timestamp |
| The timestamp when the data entity was created |
modifiedOn | timestamp |
| The timestamp when the data entity was last updated |
updatesCount | int32|unsigned |
| The amount of times the data entity was updated |
Create/ Update Data Points
Field | Type | Required For Create | Required For Update | Description |
|---|---|---|---|---|
id | int64|unsigned |
|
| The numeric identifier of the Contract |
personId | int64|unsigned |
|
| The Person Id to which the Contract will be create |
competitorId | int64|unsigned |
|
| The Competitor Id to which the Contract will be created. |
personRole | int32|in: 0, 1, 3, 5, 6 |
|
| 0 - OwnedBy → Owned by defines relation where the Person owns the Team, Dog, Horse, etc. 1 - PlaysFor → Plays for defines relation where the Person plays for a Team. 3 - Trainedby → Trained by defines relation where the Team, Dog, Horse, Player, Doubles Partnership are trained by a Person 5 - RiddenBy → Ridden by defines relation where the Person is a jockey of a Horse 6 - BredBy → Bred by defines relation where the Horse, Dog is bred by a Person |
isActive | boolean |
|
| Defines whether the Contract is active. If the contract is active then the Person to which the Contract is can be used in Lineups if such exist. The IsActive property is set to true by default on creation. The contract is auto-updated by Person IsActive property. For more info open Person page on section Important |
Validations
Description | On Create | On Update | Response Code | Contains Conflict Header | Error Message |
|---|---|---|---|---|---|
Contract must exist |
|
| 400 |
| Not found. Missing Contract entity with id: {proposed id} |
Contract must not exist |
|
| 409 |
| Conflict detected! Contracts {proposed person id} -> {proposed competitor id} already exists! Try update of contract with id {existing contract id} or check whether the ids are correct. |
Competitor and Person must have valid gender combination |
|
| 400 |
| Person and competitor must be from the same gender when contract is PlaysFor (2) unless Competitor Gender is set to Mixed! Current Competitor Gender: {current competitor gender}; Current Person gender: {current person gender} |
Person must exist |
|
| 400 |
| Not found. Missing Person entity with id: {proposed person id} |
Person must be active |
|
| 400 |
| Only persons which are active are allowed to be connected with competitor via contract or to be part of double partnerships! |
Person must have the sport associated |
|
| 400 |
| Person cannot be used in sport {proposed sport id} as the sports associated with the person are: {sport ids separated by ', '} |
Competitor must exist |
|
| 400 |
| Not found. Missing Competitor entity with id: {proposed competitor id} |
Competitor must be active |
|
| 400 |
| Only competitor with status type Active are allowed to be connected with person via contract! |
Competitor person role type is valid combination in format Competitor → roles: Team → PlaysFor, TrainedBy, OwnedBy Horse → OwnedBy, BredBy, TrainedBy, RiddenBy Dog → OwnedBy, BredBy, TrainedBy Player → TrainedBy |
|
| 400 |
| Invalid competitor role type for contract between Person and Competitor: Valid combinations between competitor type and person role type are: {valid person role combinations in format “competitorType => roles separated by ', ' “}. Current pair: {competitorType of the proposed competitor} -> {proposed person role}. |