CompetitionsController API Documentation

Competitions API Documentation

This document provides documentation for the Competitions API endpoints available in the Points.Api system.

Table of Contents

• Authentication
• Endpoints
  • Calculate Points
  • Enter Competitions
  • Get Competition Details
  • Get Active Competitions
  • Get Active Wheel of Fortune Competitions
  • Get User's Competitions
  • Update Code Usage
  • Get One-Time Use Codes
  • Update Entry Details
  • Update Prizes Left
• Models
  • CompetitionEnterRequest
  • EnterCompetitionResponse
  • PartnerCompetitions
  • PartnerCompetitionsEntryList
  • PartnerCompetitionsDataEntryFieldValues

Authentication

All endpoints in this API require JWT Bearer authentication unless specified otherwise. Include a valid JWT token in the Authorization header of your requests.

Authorization: Bearer {your_jwt_token}

Endpoints

Calculate Points

Calculates points for competitions for a specific partner.

URL: /api/Competitions/Partner/{partnerId}/CalculatePoints

Method: PUT

Auth required: Yes (JWT Bearer)

URL Parameters:

• partnerId (long) - The ID of the partner

Success Response:

• Code: 200 OK
• Content: Empty response

Example Request:

PUT /api/Competitions/Partner/123/CalculatePoints HTTP/1.1
Host: your-api-domain.com
Authorization: Bearer {your_jwt_token}

Example Response:

{}

Enter Competitions

Enters a user into a competition.

URL: /api/Competitions/Partner/{partnerId}/user/{userId}

Method: POST

Auth required: Yes (JWT Bearer)

URL Parameters:

• partnerId (long) - The ID of the partner
• userId (long) - The ID of the user
• ids (boolean, query parameter) - If true, returns the entry ID and number of entries

Request Body:

• CompetitionEnterRequest object

Success Response:

• Code: 200 OK
• Content:
  • If ids is true: EnterCompetitionResponse object
  • If ids is false: Integer representing the number of entries

Example Request:

POST /api/Competitions/Partner/123/user/456?ids=true HTTP/1.1
Host: your-api-domain.com
Authorization: Bearer {your_jwt_token}
Content-Type: application/json

{
  "competitionId": 789,
  "prizeId": 101
}

Example Response (with ids=true):

{
  "entryId": 12345,
  "numberOfEntries": 1
}

Example Response (with ids=false):

1

Get Competition Details

Gets details of a specific competition.

URL: /api/Competitions/Partner/{partnerId}/id/{id}/user/{userId}

Method: GET

Auth required: No

URL Parameters:

• partnerId (long) - The ID of the partner
• id (long) - The ID of the competition
• userId (long) - The ID of the user

Success Response:

• Code: 200 OK
• Content: PartnerCompetitions object

Example Request:

GET /api/Competitions/Partner/123/id/789/user/456 HTTP/1.1
Host: your-api-domain.com

Example Response:

{
  "id": 789,
  "name": "Summer Challenge",
  "description": "Join our summer fitness challenge",
  "startDate": "2025-06-01T00:00:00Z",
  "endDate": "2025-08-31T23:59:59Z",
  "isActive": true,
  "isWof": false,
  "activityTypeId": 1,
  "pointsRequired": 100,
  "branding": {
    "backgroundColor": "#F5F5F5",
    "textColor": "#333333",
    "buttonColor": "#4CAF50",
    "buttonTextColor": "#FFFFFF"
  },
  "winLevels": [
    {
      "level": 1,
      "points": 500
    },
    {
      "level": 2,
      "points": 300
    },
    {
      "level": 3,
      "points": 100
    }
  ],
  "prizes": [
    {
      "id": 101,
      "name": "First Prize",
      "description": "Premium Fitness Watch",
      "imageUrl": "https://example.com/images/watch.jpg",
      "quantity": 1
    },
    {
      "id": 102,
      "name": "Second Prize",
      "description": "Fitness Apparel Set",
      "imageUrl": "https://example.com/images/apparel.jpg",
      "quantity": 5
    }
  ],
  "dataEntryFields": [
    {
      "id": 201,
      "name": "Email",
      "required": true,
      "fieldType": "text"
    },
    {
      "id": 202,
      "name": "Phone Number",
      "required": false,
      "fieldType": "text"
    }
  ]
}

Get Active Competitions

Gets all active competitions for a specific partner.

URL: /api/Competitions/Partner/{partnerId}

Method: GET

Auth required: Yes (JWT Bearer)

URL Parameters:

• partnerId (long) - The ID of the partner

Success Response:

• Code: 200 OK
• Content: Array of PartnerCompetitions objects

Example Request:

GET /api/Competitions/Partner/123 HTTP/1.1
Host: your-api-domain.com
Authorization: Bearer {your_jwt_token}

Example Response:

[
  {
    "id": 789,
    "name": "Summer Challenge",
    "description": "Join our summer fitness challenge",
    "startDate": "2025-06-01T00:00:00Z",
    "endDate": "2025-08-31T23:59:59Z",
    "isActive": true,
    "isWof": false,
    "activityTypeId": 1,
    "pointsRequired": 100,
    "prizes": [
      {
        "id": 101,
        "name": "First Prize",
        "description": "Premium Fitness Watch",
        "imageUrl": "https://example.com/images/watch.jpg",
        "quantity": 1
      }
    ]
  },
  {
    "id": 790,
    "name": "Weekly Steps Challenge",
    "description": "Get the most steps this week",
    "startDate": "2025-03-15T00:00:00Z",
    "endDate": "2025-03-22T23:59:59Z",
    "isActive": true,
    "isWof": false,
    "activityTypeId": 2,
    "pointsRequired": 50,
    "prizes": [
      {
        "id": 103,
        "name": "Gift Card",
        "description": "$50 Gift Card",
        "imageUrl": "https://example.com/images/giftcard.jpg",
        "quantity": 3
      }
    ]
  }
]

Get Active Wheel of Fortune Competitions

Gets all active Wheel of Fortune (WoF) competitions for a specific partner.

URL: /api/Competitions/Partner/{partnerId}/wof

Method: GET

Auth required: Yes (JWT Bearer)

URL Parameters:

• partnerId (long) - The ID of the partner

Success Response:

• Code: 200 OK
• Content: Array of PartnerCompetitions objects (with isWof=true)

Example Request:

GET /api/Competitions/Partner/123/wof HTTP/1.1
Host: your-api-domain.com
Authorization: Bearer {your_jwt_token}

Example Response:

[
  {
    "id": 791,
    "name": "Spin to Win",
    "description": "Spin the wheel for a chance to win prizes",
    "startDate": "2025-03-01T00:00:00Z",
    "endDate": "2025-04-30T23:59:59Z",
    "isActive": true,
    "isWof": true,
    "activityTypeId": null,
    "pointsRequired": 25,
    "prizes": [
      {
        "id": 104,
        "name": "Grand Prize",
        "description": "Vacation Package",
        "imageUrl": "https://example.com/images/vacation.jpg",
        "quantity": 1
      },
      {
        "id": 105,
        "name": "Consolation Prize",
        "description": "Discount Coupon",
        "imageUrl": "https://example.com/images/coupon.jpg",
        "quantity": 100
      }
    ]
  }
]

Get User's Competitions

Gets all competitions a user has entered for a specific partner.

URL: /api/Competitions/Partner/{partnerId}/user/{userId}

Method: GET

Auth required: Yes (JWT Bearer)

URL Parameters:

• partnerId (long) - The ID of the partner
• userId (long) - The ID of the user

Success Response:

• Code: 200 OK
• Content: Array of PartnerCompetitionsEntryList objects

Example Request:

GET /api/Competitions/Partner/123/user/456 HTTP/1.1
Host: your-api-domain.com
Authorization: Bearer {your_jwt_token}

Example Response:

[
  {
    "id": 12345,
    "entryDate": "2025-03-10T15:30:45Z",
    "placed": 2,
    "partnerCompetitions": {
      "id": 789,
      "name": "Summer Challenge",
      "description": "Join our summer fitness challenge",
      "startDate": "2025-06-01T00:00:00Z",
      "endDate": "2025-08-31T23:59:59Z",
      "isActive": true
    },
    "prizes": {
      "id": 101,
      "name": "First Prize",
      "description": "Premium Fitness Watch",
      "imageUrl": "https://example.com/images/watch.jpg"
    },
    "dataEntryValues": [
      {
        "id": 301,
        "dataEntryFields": {
          "id": 201,
          "name": "Email"
        },
        "value": "user@example.com"
      }
    ]
  }
]

Update Code Usage

Updates the usage status of a one-time use code for a prize.

URL: /api/Competitions/Partner/{partnerId}/user/{userId}/prize/{prizeId}/code/{code}

Method: POST

Auth required: Yes (JWT Bearer)

URL Parameters:

• partnerId (long) - The ID of the partner
• userId (long) - The ID of the user
• prizeId (long) - The ID of the prize
• code (string) - The one-time use code

Success Response:

• Code: 200 OK
• Content: Integer representing the result of the operation (typically 1 for success, 0 for failure)

Example Request:

POST /api/Competitions/Partner/123/user/456/prize/101/code/ABC123XYZ HTTP/1.1
Host: your-api-domain.com
Authorization: Bearer {your_jwt_token}

Example Response:

1

Get One-Time Use Codes

Gets a one-time use code for a prize and automatically marks it as used.

URL: /api/Competitions/Partner/{partnerId}/user/{userId}/prize/{prizeId}

Method: GET

Auth required: Yes (JWT Bearer)

URL Parameters:

• partnerId (long) - The ID of the partner
• userId (long) - The ID of the user
• prizeId (long) - The ID of the prize

Success Response:

• Code: 200 OK
• Content: String representing the one-time use code

Example Request:

GET /api/Competitions/Partner/123/user/456/prize/101 HTTP/1.1
Host: your-api-domain.com
Authorization: Bearer {your_jwt_token}

Example Response:

"ABC123XYZ"

Update Entry Details

Updates the data entry field values for a competition entry.

URL: /api/Competitions/Partner/{partnerId}/user/{userId}/entry/{id}

Method: POST

Auth required: Yes (JWT Bearer)

URL Parameters:

• partnerId (long) - The ID of the partner
• userId (long) - The ID of the user
• id (long) - The ID of the competition entry

Request Body:

• Array of PartnerCompetitionsDataEntryFieldValues objects

Success Response:

• Code: 200 OK
• Content: Integer representing the result of the operation (typically 1 for success, 0 for failure)

Example Request:

POST /api/Competitions/Partner/123/user/456/entry/12345 HTTP/1.1
Host: your-api-domain.com
Authorization: Bearer {your_jwt_token}
Content-Type: application/json

[
  {
    "id": 301,
    "dataEntryFields": {
      "id": 201,
      "name": "Email"
    },
    "value": "updated.email@example.com"
  },
  {
    "id": 302,
    "dataEntryFields": {
      "id": 202,
      "name": "Phone Number"
    },
    "value": "555-123-4567"
  }
]

Example Response:

1

Update Prizes Left

Updates the number of prizes left for a specific prize.

URL: /api/Competitions/Partner/{partnerId}/user/{userId}/prize/{prizeId}

Method: PATCH

Auth required: Yes (JWT Bearer)

URL Parameters:

• partnerId (long) - The ID of the partner
• userId (long) - The ID of the user
• prizeId (long) - The ID of the prize

Success Response:

• Code: 200 OK
• Content: Integer representing the result of the operation (typically 1 for success, 0 for failure)

Example Request:

PATCH /api/Competitions/Partner/123/user/456/prize/101 HTTP/1.1
Host: your-api-domain.com
Authorization: Bearer {your_jwt_token}

Example Response:

1

Models

CompetitionEnterRequest

The CompetitionEnterRequest model is used to enter a user into a competition.

Property	Type	Description
competitionId	long	The ID of the competition to enter
prizeId	long?	Optional ID of the prize associated with the entry

EnterCompetitionResponse

The EnterCompetitionResponse model contains information about a competition entry.

Property	Type	Description
entryId	long	The ID of the competition entry
numberOfEntries	int	The number of entries the user has in the competition

PartnerCompetitions

The PartnerCompetitions model contains information about a competition.

Property	Type	Description
id	long	Unique identifier for the competition
name	string	Name of the competition
description	string	Description of the competition
startDate	DateTime	Start date and time of the competition
endDate	DateTime	End date and time of the competition
isActive	boolean	Whether the competition is active
isWof	boolean	Whether the competition is a Wheel of Fortune type
activityTypeId	long?	Optional ID of the activity type associated with the competition
pointsRequired	int	Points required to enter the competition
branding	object	Branding information for the competition
winLevels	array	Levels and associated points for winning
prizes	array	Prizes available in the competition
dataEntryFields	array	Data entry fields required for the competition

PartnerCompetitionsEntryList

The PartnerCompetitionsEntryList model contains information about a user's entry in a competition.

Property	Type	Description
id	long	Unique identifier for the entry
entryDate	DateTime	Date and time of the entry
placed	int?	Optional placement of the user in the competition
partnerCompetitions	object	The competition the user entered
prizes	object	The prize associated with the entry
dataEntryValues	array	Values for the data entry fields

PartnerCompetitionsDataEntryFieldValues

The PartnerCompetitionsDataEntryFieldValues model contains values for data entry fields in a competition.

Property	Type	Description
id	long	Unique identifier for the data entry field value
dataEntryFields	object	The data entry field
value	string	The value entered by the user