Skip to content

BucketsController API Documentation

Jump to bottom
Lee Sambridge edited this page Jul 14, 2025 · 5 revisions

Buckets API Documentation

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

Table of Contents

Authentication

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

Authorization: Bearer {your_jwt_token}

Endpoints

Get Points Buckets

Retrieves all point buckets for a specific partner.

URL: /api/Buckets/{partnerId}

Method: GET

Auth required: Yes (JWT Bearer)

URL Parameters:

  • partnerId (long) - The ID of the partner

Success Response:

Example Request:

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

Example Response:

[
  {
    "id": 1,
    "name": "Fitness",
    "description": "Points earned from fitness activities",
    "points": 100
  },
  {
    "id": 2,
    "name": "Wellness",
    "description": "Points earned from wellness activities",
    "points": 50
  }
]

Update Points Buckets

Updates an existing point bucket for a specific partner.

URL: /api/Buckets/{partnerId}

Method: PATCH

Auth required: Yes (JWT Bearer)

URL Parameters:

  • partnerId (long) - The ID of the partner

Request Body: PointBucket object

Success Response:

  • Code: 200 OK
  • Content: Result object indicating success

Example Request:

PATCH /api/Buckets/123 HTTP/1.1
Host: your-api-domain.com
Authorization: Bearer {your_jwt_token}
Content-Type: application/json

{
  "id": 1,
  "bucketName": "Fitness Plus",
  "description": "Enhanced points earned from fitness activities",
  "expiryDate": "2026-01-01T00:00:00Z",
  "showInUi": true,
  "pointBucketsActivityTypes": [
    {
      "id": 101,
      "name": "Running",
      "active": true,
      "activityTypeId": 1,
      "showOnEarnPointsPage": true,
      "earnPointsRedirectUrl": "https://example.com/earn/running",
      "earnPointsExtraInfo": "Earn points for every kilometer you run",
      "earnPointsImageUrl": "https://example.com/images/running.jpg",
      "allowToBeUsedForTimeStreak": true,
      "earnPointsCmsContent": "<div>Run to earn points!</div>",
      "expireInDaysOfCollecting": 30,
      "displayPointValue": 10.0,
      "pointValue": 10.0
    },
    {
      "id": 102,
      "name": "Cycling",
      "active": true,
      "activityTypeId": 2,
      "showOnEarnPointsPage": true,
      "earnPointsRedirectUrl": "https://example.com/earn/cycling",
      "earnPointsExtraInfo": "Earn points for every kilometer you cycle",
      "earnPointsImageUrl": "https://example.com/images/cycling.jpg",
      "allowToBeUsedForTimeStreak": true,
      "earnPointsCmsContent": "<div>Cycle to earn points!</div>",
      "expireInDaysOfCollecting": 30,
      "displayPointValue": 5.0,
      "pointValue": 5.0
    }
  ]
}

Example Response:

{
  "isSuccess": true,
  "statusCode": 200,
  "message": "Bucket updated successfully"
}

Create Points Buckets

Creates a new point bucket for a specific partner.

URL: /api/Buckets/{partnerId}

Method: POST

Auth required: Yes (JWT Bearer)

URL Parameters:

  • partnerId (long) - The ID of the partner

Request Body: PointBucket object

Success Response:

  • Code: 201 Created
  • Content: Result object indicating success

Example Request:

POST /api/Buckets/123 HTTP/1.1
Host: your-api-domain.com
Authorization: Bearer {your_jwt_token}
Content-Type: application/json

{
  "bucketName": "Nutrition",
  "description": "Points earned from nutrition tracking",
  "expiryDate": "2026-01-01T00:00:00Z",
  "showInUi": true,
  "pointBucketsActivityTypes": [
    {
      "active": true,
      "id": 5,
      "name": "Meal Logging",
      "activityTypeId": null
    },
    {
      "active": true,
      "id": 6,
      "name": "Water Intake",
      "activityTypeId": null
    }
  ]
}

Example Response:

{
  "isSuccess": true,
  "statusCode": 201,
  "message": "Bucket created successfully"
}

Models

PointBucket

The PointBucket model represents a bucket that can hold specific types of points.

Field Type Description
id long The unique identifier for the bucket
bucketName string The name of the bucket (required)
description string A description of the bucket (optional)
expiryDate string (date-time) The expiration date of the bucket (optional)
showInUi boolean Whether to show the bucket in the UI (default: true)
pointBucketsActivityTypes List The list of activity types associated with this bucket

PointBucketResponse

The PointBucketResponse model represents a simplified view of a point bucket, typically used in responses.

Field Type Description
id long The unique identifier for the bucket
name string The name of the bucket (default: empty string)
description string A description of the bucket (default: empty string)
points integer The number of points in the bucket (default: 0)

ActivityTypeSmallResponse

The ActivityTypeSmallResponse model represents a simplified view of an activity type.

Field Type Description
id long Unique identifier for the activity
name string Name of the activity (max length: 500 characters)
active boolean Whether the activity is active (default: true)
activityTypeId long? Optional reference to a parent activity type
showOnEarnPointsPage boolean Whether to display this activity on the earn points page
earnPointsRedirectUrl string URL to redirect to for earning points (optional)
earnPointsExtraInfo string Additional information about earning points (optional)
earnPointsImageUrl string URL to an image representing the activity (optional)
allowToBeUsedForTimeStreak boolean Whether this activity can be used for time streak calculations
earnPointsCmsContent string CMS content for the earn points display (optional)
expireInDaysOfCollecting long? Number of days after which collected points expire (optional)
displayPointValue decimal The point value to display to users (default: 0)
pointValue decimal The actual point value awarded (default: 0)

Terms and Conditions | Privacy Policy | Acceptable Use Policy | Cookie Policy

Clone this wiki locally