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

• 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

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}

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:

{}

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

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"
    }
  ]
}

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
      }
    ]
  }
]

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
      }
    ]
  }
]

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": "[email protected]"
      }
    ]
  }
]

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

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"

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": "[email protected]"
  },
  {
    "id": 302,
    "dataEntryFields": {
      "id": 202,
      "name": "Phone Number"
    },
    "value": "555-123-4567"
  }
]

Example Response:

1

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

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

The EnterCompetitionResponse model contains information about a competition entry.

The PartnerCompetitions model contains information about a competition.

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

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