> For the complete documentation index, see [llms.txt](https://api-docs.myhappyforce.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api-docs.myhappyforce.com/docs/api-reference/rewards.md).

# Rewards

## GET /api/v1/company/rewards/config

> Get the rewards configuration

```json
{"openapi":"3.1.0","info":{"title":"Happyforce API","version":"v1"},"tags":[],"servers":[{"url":"{url}","description":"API URL","variables":{"url":{"description":"API Environment","enum":["https://api.happyforce.com","https://staging.happyforce.com","http://localhost:9000"],"default":"https://api.happyforce.com"}}}],"security":[{"companyAPISessionId":[]}],"components":{"securitySchemes":{"companyAPISessionId":{"type":"apiKey","description":"SessionId","name":"SessionId","in":"header"}},"schemas":{"RewardsConfiguration":{"type":"object","description":"Per-company rewards configuration","properties":{"actionRules":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/RewardActionRule"}},"podium":{"$ref":"#/components/schemas/PodiumConfig"},"recognitionLimits":{"$ref":"#/components/schemas/RecognitionLimits"}}},"RewardActionRule":{"type":"object","properties":{"enabled":{"type":"boolean"},"points":{"type":"integer","format":"int32"},"dailyLimit":{"type":"integer","format":"int32"},"weeklyLimit":{"type":"integer","format":"int32"}}},"PodiumConfig":{"type":"object","properties":{"enabled":{"type":"boolean"},"firstPrize":{"type":"integer","format":"int32"},"secondPrize":{"type":"integer","format":"int32"},"thirdPrize":{"type":"integer","format":"int32"},"minParticipants":{"type":"integer","format":"int32"}}},"RecognitionLimits":{"type":"object","properties":{"maxSentPerWeek":{"type":"integer","format":"int32"},"noRepeatRecipientDays":{"type":"integer","format":"int32"},"maxReceivedPerSenderPerWeek":{"type":"integer","format":"int32"},"maxTeamSentPerWeek":{"type":"integer","format":"int32"}}}}},"paths":{"/api/v1/company/rewards/config":{"get":{"tags":["Rewards"],"summary":"Get the rewards configuration","operationId":"getRewardsConfig","responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/RewardsConfiguration"}}}}}}}}}
```

## PUT /api/v1/company/rewards/config

> Update the rewards configuration

```json
{"openapi":"3.1.0","info":{"title":"Happyforce API","version":"v1"},"tags":[],"servers":[{"url":"{url}","description":"API URL","variables":{"url":{"description":"API Environment","enum":["https://api.happyforce.com","https://staging.happyforce.com","http://localhost:9000"],"default":"https://api.happyforce.com"}}}],"security":[{"companyAPISessionId":[]}],"components":{"securitySchemes":{"companyAPISessionId":{"type":"apiKey","description":"SessionId","name":"SessionId","in":"header"}},"schemas":{"RewardsConfiguration":{"type":"object","description":"Per-company rewards configuration","properties":{"actionRules":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/RewardActionRule"}},"podium":{"$ref":"#/components/schemas/PodiumConfig"},"recognitionLimits":{"$ref":"#/components/schemas/RecognitionLimits"}}},"RewardActionRule":{"type":"object","properties":{"enabled":{"type":"boolean"},"points":{"type":"integer","format":"int32"},"dailyLimit":{"type":"integer","format":"int32"},"weeklyLimit":{"type":"integer","format":"int32"}}},"PodiumConfig":{"type":"object","properties":{"enabled":{"type":"boolean"},"firstPrize":{"type":"integer","format":"int32"},"secondPrize":{"type":"integer","format":"int32"},"thirdPrize":{"type":"integer","format":"int32"},"minParticipants":{"type":"integer","format":"int32"}}},"RecognitionLimits":{"type":"object","properties":{"maxSentPerWeek":{"type":"integer","format":"int32"},"noRepeatRecipientDays":{"type":"integer","format":"int32"},"maxReceivedPerSenderPerWeek":{"type":"integer","format":"int32"},"maxTeamSentPerWeek":{"type":"integer","format":"int32"}}}}},"paths":{"/api/v1/company/rewards/config":{"put":{"tags":["Rewards"],"summary":"Update the rewards configuration","operationId":"updateRewardsConfig","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RewardsConfiguration"}}},"required":true},"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/RewardsConfiguration"}}}}}}}}}
```

## PUT /api/v1/company/rewards/catalog/{itemId}

> Update a catalog item

```json
{"openapi":"3.1.0","info":{"title":"Happyforce API","version":"v1"},"tags":[],"servers":[{"url":"{url}","description":"API URL","variables":{"url":{"description":"API Environment","enum":["https://api.happyforce.com","https://staging.happyforce.com","http://localhost:9000"],"default":"https://api.happyforce.com"}}}],"security":[{"companyAPISessionId":[]}],"components":{"securitySchemes":{"companyAPISessionId":{"type":"apiKey","description":"SessionId","name":"SessionId","in":"header"}},"schemas":{"RewardCatalogItemRequest":{"type":"object","description":"Create or update a catalog item","properties":{"id":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"imageUrl":{"type":"string"},"cost":{"type":"integer","format":"int32"},"fulfillmentType":{"$ref":"#/components/schemas/RewardFulfillmentType"},"stock":{"type":"integer","format":"int32"},"maxRedemptionsPerEmployee":{"type":"integer","format":"int32"},"hierarchyIds":{"type":"array","items":{"type":"string"},"uniqueItems":true},"groupIds":{"type":"array","items":{"type":"string"},"uniqueItems":true},"validFrom":{"type":"string","format":"date-time"},"validTo":{"type":"string","format":"date-time"},"active":{"type":"boolean"}}},"RewardFulfillmentType":{"type":"string","description":"How a redeemed catalog item is fulfilled","enum":["MANUAL","DIGITAL_CODE"]},"RewardCatalogItem":{"type":"object","description":"A reward offered in the company catalog","properties":{"id":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"imageUrl":{"type":"string"},"cost":{"type":"integer","format":"int32"},"fulfillmentType":{"$ref":"#/components/schemas/RewardFulfillmentType"},"stock":{"type":"integer","format":"int32"},"availableCodeCount":{"type":"integer","format":"int32","description":"For DIGITAL_CODE items, how many unassigned codes remain (the real stock); null for MANUAL items"},"maxRedemptionsPerEmployee":{"type":"integer","format":"int32"},"validFrom":{"type":"string","format":"date-time"},"validTo":{"type":"string","format":"date-time"},"active":{"type":"boolean"},"archived":{"type":"boolean"}}}}},"paths":{"/api/v1/company/rewards/catalog/{itemId}":{"put":{"tags":["Rewards"],"summary":"Update a catalog item","operationId":"updateRewardsCatalogItem","parameters":[{"name":"itemId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RewardCatalogItemRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/RewardCatalogItem"}}}}}}}}}
```

## DELETE /api/v1/company/rewards/catalog/{itemId}

> Delete a catalog item (archived if it has redemptions)

```json
{"openapi":"3.1.0","info":{"title":"Happyforce API","version":"v1"},"tags":[],"servers":[{"url":"{url}","description":"API URL","variables":{"url":{"description":"API Environment","enum":["https://api.happyforce.com","https://staging.happyforce.com","http://localhost:9000"],"default":"https://api.happyforce.com"}}}],"security":[{"companyAPISessionId":[]}],"components":{"securitySchemes":{"companyAPISessionId":{"type":"apiKey","description":"SessionId","name":"SessionId","in":"header"}}},"paths":{"/api/v1/company/rewards/catalog/{itemId}":{"delete":{"tags":["Rewards"],"summary":"Delete a catalog item (archived if it has redemptions)","operationId":"deleteRewardsCatalogItem","parameters":[{"name":"itemId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}}}}}
```

## GET /api/v1/employee/rewards/redemptions

> List my redemptions

```json
{"openapi":"3.1.0","info":{"title":"Happyforce API","version":"v1"},"tags":[],"servers":[{"url":"{url}","description":"API URL","variables":{"url":{"description":"API Environment","enum":["https://api.happyforce.com","https://staging.happyforce.com","http://localhost:9000"],"default":"https://api.happyforce.com"}}}],"security":[{"employeeAPISessionId":[]}],"components":{"securitySchemes":{},"schemas":{"EmployeeRedemption":{"type":"object","properties":{"id":{"type":"string"},"rewardId":{"type":"string"},"cost":{"type":"integer","format":"int32"},"fulfillmentType":{"$ref":"#/components/schemas/RewardFulfillmentType"},"status":{"$ref":"#/components/schemas/RedemptionStatus"},"rejectionMessage":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"rewardTitle":{"type":"string","description":"Reward title, resolved even if the reward was archived"},"rewardImageUrl":{"type":"string","description":"Reward image, resolved even if the reward was archived"},"adminNote":{"type":"string","description":"HR note shown on approval/delivery, or the reject message"},"code":{"type":"string","description":"Plaintext code for a fulfilled DIGITAL_CODE redemption, or null"}}},"RewardFulfillmentType":{"type":"string","description":"How a redeemed catalog item is fulfilled","enum":["MANUAL","DIGITAL_CODE"]},"RedemptionStatus":{"type":"string","description":"Lifecycle state of a reward redemption","enum":["RESERVING","FAILED","PENDING","APPROVED","DELIVERED","REJECTED","CANCELLED","FULFILLED"]}}},"paths":{"/api/v1/employee/rewards/redemptions":{"get":{"tags":["Rewards"],"description":"List my redemptions","operationId":"getMyRedemptions","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/EmployeeRedemption"}}}}}}}}}}
```

## POST /api/v1/employee/rewards/redemptions

> Redeem a catalog item for points

```json
{"openapi":"3.1.0","info":{"title":"Happyforce API","version":"v1"},"tags":[],"servers":[{"url":"{url}","description":"API URL","variables":{"url":{"description":"API Environment","enum":["https://api.happyforce.com","https://staging.happyforce.com","http://localhost:9000"],"default":"https://api.happyforce.com"}}}],"security":[{"employeeAPISessionId":[]}],"components":{"securitySchemes":{},"schemas":{"RedeemRequest":{"type":"object","properties":{"rewardId":{"type":"string"},"idempotencyToken":{"type":"string"}}},"EmployeeRedemption":{"type":"object","properties":{"id":{"type":"string"},"rewardId":{"type":"string"},"cost":{"type":"integer","format":"int32"},"fulfillmentType":{"$ref":"#/components/schemas/RewardFulfillmentType"},"status":{"$ref":"#/components/schemas/RedemptionStatus"},"rejectionMessage":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"rewardTitle":{"type":"string","description":"Reward title, resolved even if the reward was archived"},"rewardImageUrl":{"type":"string","description":"Reward image, resolved even if the reward was archived"},"adminNote":{"type":"string","description":"HR note shown on approval/delivery, or the reject message"},"code":{"type":"string","description":"Plaintext code for a fulfilled DIGITAL_CODE redemption, or null"}}},"RewardFulfillmentType":{"type":"string","description":"How a redeemed catalog item is fulfilled","enum":["MANUAL","DIGITAL_CODE"]},"RedemptionStatus":{"type":"string","description":"Lifecycle state of a reward redemption","enum":["RESERVING","FAILED","PENDING","APPROVED","DELIVERED","REJECTED","CANCELLED","FULFILLED"]}}},"paths":{"/api/v1/employee/rewards/redemptions":{"post":{"tags":["Rewards"],"description":"Redeem a catalog item for points","operationId":"redeemReward","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RedeemRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmployeeRedemption"}}}}}}}}}
```

## GET /api/v1/company/rewards/catalog

> List catalog items (admin)

```json
{"openapi":"3.1.0","info":{"title":"Happyforce API","version":"v1"},"tags":[],"servers":[{"url":"{url}","description":"API URL","variables":{"url":{"description":"API Environment","enum":["https://api.happyforce.com","https://staging.happyforce.com","http://localhost:9000"],"default":"https://api.happyforce.com"}}}],"security":[{"companyAPISessionId":[]}],"components":{"securitySchemes":{"companyAPISessionId":{"type":"apiKey","description":"SessionId","name":"SessionId","in":"header"}},"schemas":{"RewardCatalogItem":{"type":"object","description":"A reward offered in the company catalog","properties":{"id":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"imageUrl":{"type":"string"},"cost":{"type":"integer","format":"int32"},"fulfillmentType":{"$ref":"#/components/schemas/RewardFulfillmentType"},"stock":{"type":"integer","format":"int32"},"availableCodeCount":{"type":"integer","format":"int32","description":"For DIGITAL_CODE items, how many unassigned codes remain (the real stock); null for MANUAL items"},"maxRedemptionsPerEmployee":{"type":"integer","format":"int32"},"validFrom":{"type":"string","format":"date-time"},"validTo":{"type":"string","format":"date-time"},"active":{"type":"boolean"},"archived":{"type":"boolean"}}},"RewardFulfillmentType":{"type":"string","description":"How a redeemed catalog item is fulfilled","enum":["MANUAL","DIGITAL_CODE"]}}},"paths":{"/api/v1/company/rewards/catalog":{"get":{"tags":["Rewards"],"summary":"List catalog items (admin)","operationId":"listRewardsCatalog","parameters":[{"name":"includeArchived","in":"query","required":false,"schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/RewardCatalogItem"}}}}}}}}}}
```

## POST /api/v1/company/rewards/catalog

> Create a catalog item

```json
{"openapi":"3.1.0","info":{"title":"Happyforce API","version":"v1"},"tags":[],"servers":[{"url":"{url}","description":"API URL","variables":{"url":{"description":"API Environment","enum":["https://api.happyforce.com","https://staging.happyforce.com","http://localhost:9000"],"default":"https://api.happyforce.com"}}}],"security":[{"companyAPISessionId":[]}],"components":{"securitySchemes":{"companyAPISessionId":{"type":"apiKey","description":"SessionId","name":"SessionId","in":"header"}},"schemas":{"RewardCatalogItemRequest":{"type":"object","description":"Create or update a catalog item","properties":{"id":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"imageUrl":{"type":"string"},"cost":{"type":"integer","format":"int32"},"fulfillmentType":{"$ref":"#/components/schemas/RewardFulfillmentType"},"stock":{"type":"integer","format":"int32"},"maxRedemptionsPerEmployee":{"type":"integer","format":"int32"},"hierarchyIds":{"type":"array","items":{"type":"string"},"uniqueItems":true},"groupIds":{"type":"array","items":{"type":"string"},"uniqueItems":true},"validFrom":{"type":"string","format":"date-time"},"validTo":{"type":"string","format":"date-time"},"active":{"type":"boolean"}}},"RewardFulfillmentType":{"type":"string","description":"How a redeemed catalog item is fulfilled","enum":["MANUAL","DIGITAL_CODE"]},"RewardCatalogItem":{"type":"object","description":"A reward offered in the company catalog","properties":{"id":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"imageUrl":{"type":"string"},"cost":{"type":"integer","format":"int32"},"fulfillmentType":{"$ref":"#/components/schemas/RewardFulfillmentType"},"stock":{"type":"integer","format":"int32"},"availableCodeCount":{"type":"integer","format":"int32","description":"For DIGITAL_CODE items, how many unassigned codes remain (the real stock); null for MANUAL items"},"maxRedemptionsPerEmployee":{"type":"integer","format":"int32"},"validFrom":{"type":"string","format":"date-time"},"validTo":{"type":"string","format":"date-time"},"active":{"type":"boolean"},"archived":{"type":"boolean"}}}}},"paths":{"/api/v1/company/rewards/catalog":{"post":{"tags":["Rewards"],"summary":"Create a catalog item","operationId":"createRewardsCatalogItem","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RewardCatalogItemRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/RewardCatalogItem"}}}}}}}}}
```

## POST /api/v1/company/rewards/catalog/{itemId}/codes

> Upload a batch of gift-card codes (CSV, one code per line)

```json
{"openapi":"3.1.0","info":{"title":"Happyforce API","version":"v1"},"tags":[],"servers":[{"url":"{url}","description":"API URL","variables":{"url":{"description":"API Environment","enum":["https://api.happyforce.com","https://staging.happyforce.com","http://localhost:9000"],"default":"https://api.happyforce.com"}}}],"security":[{"companyAPISessionId":[]}],"components":{"securitySchemes":{"companyAPISessionId":{"type":"apiKey","description":"SessionId","name":"SessionId","in":"header"}},"schemas":{"GiftCardBatchUploadResult":{"type":"object","properties":{"totalRows":{"type":"integer","format":"int32"},"accepted":{"type":"integer","format":"int32"},"duplicates":{"type":"integer","format":"int32"},"rejected":{"type":"integer","format":"int32"},"rows":{"type":"array","items":{"$ref":"#/components/schemas/RowResult"}}}},"RowResult":{"type":"object","properties":{"line":{"type":"integer","format":"int32"},"outcome":{"type":"string","enum":["ACCEPTED","DUPLICATE","REJECTED"]},"error":{"type":"string"}}}}},"paths":{"/api/v1/company/rewards/catalog/{itemId}/codes":{"post":{"tags":["Rewards"],"summary":"Upload a batch of gift-card codes (CSV, one code per line)","operationId":"uploadRewardsCodes","parameters":[{"name":"itemId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"}},"required":["file"]}}}},"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/GiftCardBatchUploadResult"}}}}}}}}}
```

## POST /api/v1/company/rewards/adjustments

> Manually adjust an employee's points

```json
{"openapi":"3.1.0","info":{"title":"Happyforce API","version":"v1"},"tags":[],"servers":[{"url":"{url}","description":"API URL","variables":{"url":{"description":"API Environment","enum":["https://api.happyforce.com","https://staging.happyforce.com","http://localhost:9000"],"default":"https://api.happyforce.com"}}}],"security":[{"companyAPISessionId":[]}],"components":{"securitySchemes":{"companyAPISessionId":{"type":"apiKey","description":"SessionId","name":"SessionId","in":"header"}},"schemas":{"PointsAdjustmentRequest":{"type":"object","description":"A manual points adjustment","properties":{"internalId":{"type":"integer","format":"int32"},"delta":{"type":"integer","format":"int64"},"reason":{"type":"string"}}}}},"paths":{"/api/v1/company/rewards/adjustments":{"post":{"tags":["Rewards"],"summary":"Manually adjust an employee's points","operationId":"adjustRewardsPoints","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PointsAdjustmentRequest"}}},"required":true},"responses":{"200":{"description":"OK"}}}}}}
```

## PATCH /api/v1/company/rewards/redemptions/{redemptionId}

> Approve, deliver, reject or cancel a redemption

```json
{"openapi":"3.1.0","info":{"title":"Happyforce API","version":"v1"},"tags":[],"servers":[{"url":"{url}","description":"API URL","variables":{"url":{"description":"API Environment","enum":["https://api.happyforce.com","https://staging.happyforce.com","http://localhost:9000"],"default":"https://api.happyforce.com"}}}],"security":[{"companyAPISessionId":[]}],"components":{"securitySchemes":{"companyAPISessionId":{"type":"apiKey","description":"SessionId","name":"SessionId","in":"header"}},"schemas":{"RedemptionTransitionRequest":{"type":"object","description":"Optional detail for a redemption transition","properties":{"reason":{"$ref":"#/components/schemas/RedemptionRejectionReason"},"message":{"type":"string"},"note":{"type":"string"}}},"RedemptionRejectionReason":{"type":"string","description":"Reason an admin rejected a redemption","enum":["NO_STOCK","CONDITIONS","DUPLICATE","OTHER"]},"Redemption":{"type":"object","description":"An employee's redemption of a catalog item","properties":{"id":{"type":"string"},"internalId":{"type":"integer","format":"int32"},"employeeName":{"type":"string"},"employeeArea":{"type":"string"},"employeeAvatarUrl":{"type":"string"},"rewardId":{"type":"string"},"rewardTitle":{"type":"string"},"cost":{"type":"integer","format":"int32"},"fulfillmentType":{"$ref":"#/components/schemas/RewardFulfillmentType"},"status":{"$ref":"#/components/schemas/RedemptionStatus"},"rejectionReason":{"$ref":"#/components/schemas/RedemptionRejectionReason"},"rejectionMessage":{"type":"string"},"deliveryNote":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"RewardFulfillmentType":{"type":"string","description":"How a redeemed catalog item is fulfilled","enum":["MANUAL","DIGITAL_CODE"]},"RedemptionStatus":{"type":"string","description":"Lifecycle state of a reward redemption","enum":["RESERVING","FAILED","PENDING","APPROVED","DELIVERED","REJECTED","CANCELLED","FULFILLED"]}}},"paths":{"/api/v1/company/rewards/redemptions/{redemptionId}":{"patch":{"tags":["Rewards"],"summary":"Approve, deliver, reject or cancel a redemption","operationId":"transitionRewardsRedemption","parameters":[{"name":"redemptionId","in":"path","required":true,"schema":{"type":"string"}},{"name":"action","in":"query","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RedemptionTransitionRequest"}}}},"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/Redemption"}}}}}}}}}
```

## GET /api/v1/employee/rewards/podium

> Monthly participation podium: top three (name+avatar only) plus my rank

```json
{"openapi":"3.1.0","info":{"title":"Happyforce API","version":"v1"},"tags":[],"servers":[{"url":"{url}","description":"API URL","variables":{"url":{"description":"API Environment","enum":["https://api.happyforce.com","https://staging.happyforce.com","http://localhost:9000"],"default":"https://api.happyforce.com"}}}],"security":[{"employeeAPISessionId":[]}],"components":{"securitySchemes":{},"schemas":{"RewardPodiumResponse":{"type":"object","description":"The last closed month and the in-progress (provisional) month","properties":{"closed":{"$ref":"#/components/schemas/RewardPodiumMonth"},"current":{"$ref":"#/components/schemas/RewardPodiumMonth"}}},"RewardPodiumMonth":{"type":"object","description":"A month's podium: top three by name+avatar+rank only (never points), plus the caller's own rank","properties":{"period":{"type":"string"},"provisional":{"type":"boolean"},"podium":{"type":"array","items":{"$ref":"#/components/schemas/RewardPodiumEntry"}},"me":{"$ref":"#/components/schemas/RewardPodiumMe"}}},"RewardPodiumEntry":{"type":"object","properties":{"employeeName":{"type":"string"},"avatarUrl":{"type":"string"},"rank":{"type":"integer","format":"int32"}}},"RewardPodiumMe":{"type":"object","properties":{"rank":{"type":"integer","format":"int32"}}}}},"paths":{"/api/v1/employee/rewards/podium":{"get":{"tags":["Rewards"],"description":"Monthly participation podium: top three (name+avatar only) plus my rank","operationId":"getRewardsPodium","parameters":[{"name":"period","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RewardPodiumResponse"}}}}}}}}}
```

## GET /api/v1/employee/rewards/history

> Get my points history

```json
{"openapi":"3.1.0","info":{"title":"Happyforce API","version":"v1"},"tags":[],"servers":[{"url":"{url}","description":"API URL","variables":{"url":{"description":"API Environment","enum":["https://api.happyforce.com","https://staging.happyforce.com","http://localhost:9000"],"default":"https://api.happyforce.com"}}}],"security":[{"employeeAPISessionId":[]}],"components":{"securitySchemes":{},"schemas":{"EmployeePointsLedgerEntry":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/PointsEntryType"},"actionType":{"$ref":"#/components/schemas/RewardActionType"},"points":{"type":"integer","format":"int32"},"day":{"type":"string","format":"date"},"createdAt":{"type":"string","format":"date-time"}}},"PointsEntryType":{"type":"string","description":"Kind of points-ledger movement","enum":["EARN","REDEEM","REFUND","ADJUST","PODIUM_BONUS"]},"RewardActionType":{"type":"string","description":"Action that may award reward points","enum":["HI_VOTE","VOTE_STREAK","SURVEY_COMPLETED","ENPS_VOTE","SCORES_VOTE","CHECKIN_VOTE","RECOGNITION_SENT","RECOGNITION_RECEIVED","RECOGNITION_TEAM_RECEIVED","SUGGESTION_SENT","SUGGESTION_ACCEPTED","COMMENT_ENGAGEMENT"]}}},"paths":{"/api/v1/employee/rewards/history":{"get":{"tags":["Rewards"],"description":"Get my points history","operationId":"getRewardsHistory","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/EmployeePointsLedgerEntry"}}}}}}}}}}
```

## GET /api/v1/employee/rewards/earn-actions

> The company's active reward actions and the points each one awards

```json
{"openapi":"3.1.0","info":{"title":"Happyforce API","version":"v1"},"tags":[],"servers":[{"url":"{url}","description":"API URL","variables":{"url":{"description":"API Environment","enum":["https://api.happyforce.com","https://staging.happyforce.com","http://localhost:9000"],"default":"https://api.happyforce.com"}}}],"security":[{"employeeAPISessionId":[]}],"components":{"securitySchemes":{},"schemas":{"RewardEarnAction":{"type":"object","properties":{"actionType":{"$ref":"#/components/schemas/RewardActionType"},"points":{"type":"integer","format":"int32"},"anonymity":{"$ref":"#/components/schemas/RewardAnonymity","description":"Whether this way of earning points is attributable to you: ANONYMOUS, NON_ANONYMOUS, or INHERITED (depends on the underlying feedback's configuration)"}}},"RewardActionType":{"type":"string","description":"Action that may award reward points","enum":["HI_VOTE","VOTE_STREAK","SURVEY_COMPLETED","ENPS_VOTE","SCORES_VOTE","CHECKIN_VOTE","RECOGNITION_SENT","RECOGNITION_RECEIVED","RECOGNITION_TEAM_RECEIVED","SUGGESTION_SENT","SUGGESTION_ACCEPTED","COMMENT_ENGAGEMENT"]},"RewardAnonymity":{"type":"string","description":"Whether an earn action is attributable to the employee","enum":["ANONYMOUS","NON_ANONYMOUS","INHERITED"]}}},"paths":{"/api/v1/employee/rewards/earn-actions":{"get":{"tags":["Rewards"],"description":"The company's active reward actions and the points each one awards","operationId":"getRewardsEarnActions","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/RewardEarnAction"}}}}}}}}}}
```

## GET /api/v1/employee/rewards/catalog

> Browse the reward catalog visible to me

```json
{"openapi":"3.1.0","info":{"title":"Happyforce API","version":"v1"},"tags":[],"servers":[{"url":"{url}","description":"API URL","variables":{"url":{"description":"API Environment","enum":["https://api.happyforce.com","https://staging.happyforce.com","http://localhost:9000"],"default":"https://api.happyforce.com"}}}],"security":[{"employeeAPISessionId":[]}],"components":{"securitySchemes":{},"schemas":{"EmployeeRewardCatalogItem":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"imageUrl":{"type":"string"},"cost":{"type":"integer","format":"int32"},"fulfillmentType":{"$ref":"#/components/schemas/RewardFulfillmentType"},"stock":{"type":"integer","format":"int32"},"maxPerEmployee":{"type":"integer","format":"int32","description":"Max redemptions per employee, or null for no limit"},"redeemedCount":{"type":"integer","format":"int32","description":"How many times the calling employee has already redeemed this reward"}}},"RewardFulfillmentType":{"type":"string","description":"How a redeemed catalog item is fulfilled","enum":["MANUAL","DIGITAL_CODE"]}}},"paths":{"/api/v1/employee/rewards/catalog":{"get":{"tags":["Rewards"],"description":"Browse the reward catalog visible to me","operationId":"getRewardsCatalog","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/EmployeeRewardCatalogItem"}}}}}}}}}}
```

## GET /api/v1/employee/rewards/balance

> Get my points balance

```json
{"openapi":"3.1.0","info":{"title":"Happyforce API","version":"v1"},"tags":[],"servers":[{"url":"{url}","description":"API URL","variables":{"url":{"description":"API Environment","enum":["https://api.happyforce.com","https://staging.happyforce.com","http://localhost:9000"],"default":"https://api.happyforce.com"}}}],"security":[{"employeeAPISessionId":[]}],"components":{"securitySchemes":{},"schemas":{"EmployeePointsBalance":{"type":"object","properties":{"balance":{"type":"integer","format":"int64"},"lifetimeEarned":{"type":"integer","format":"int64"},"monthlyEarned":{"type":"object","additionalProperties":{"type":"integer","format":"int32"}}}}}},"paths":{"/api/v1/employee/rewards/balance":{"get":{"tags":["Rewards"],"description":"Get my points balance","operationId":"getRewardsBalance","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmployeePointsBalance"}}}}}}}}}
```

## GET /api/v1/company/rewards/stats

> Aggregated rewards analytics

```json
{"openapi":"3.1.0","info":{"title":"Happyforce API","version":"v1"},"tags":[],"servers":[{"url":"{url}","description":"API URL","variables":{"url":{"description":"API Environment","enum":["https://api.happyforce.com","https://staging.happyforce.com","http://localhost:9000"],"default":"https://api.happyforce.com"}}}],"security":[{"companyAPISessionId":[]}],"components":{"securitySchemes":{"companyAPISessionId":{"type":"apiKey","description":"SessionId","name":"SessionId","in":"header"}},"schemas":{"RewardsStats":{"type":"object","description":"Aggregated rewards analytics","properties":{"insufficient":{"type":"boolean"},"anonymityThreshold":{"type":"integer","format":"int32"},"pointsIssued":{"type":"integer","format":"int64"},"pointsIssuedDeltaPct":{"type":"integer","format":"int32"},"pointsRedeemed":{"type":"integer","format":"int64"},"redemptionsCount":{"type":"integer","format":"int32"},"pointsInCirculation":{"type":"integer","format":"int64"},"flow":{"type":"array","items":{"$ref":"#/components/schemas/RewardsStatsFlow"}},"pointsByAction":{"type":"array","items":{"$ref":"#/components/schemas/RewardsStatsActionPoints"}},"topRewards":{"type":"array","items":{"$ref":"#/components/schemas/RewardsStatsTopReward"}},"participation":{"$ref":"#/components/schemas/RewardsStatsParticipation"}}},"RewardsStatsFlow":{"type":"object","properties":{"period":{"type":"string"},"issued":{"type":"integer","format":"int64"},"redeemed":{"type":"integer","format":"int64"},"inCirculation":{"type":"integer","format":"int64"}}},"RewardsStatsActionPoints":{"type":"object","properties":{"actionType":{"$ref":"#/components/schemas/RewardActionType"},"points":{"type":"integer","format":"int64"}}},"RewardActionType":{"type":"string","description":"Action that may award reward points","enum":["HI_VOTE","VOTE_STREAK","SURVEY_COMPLETED","ENPS_VOTE","SCORES_VOTE","CHECKIN_VOTE","RECOGNITION_SENT","RECOGNITION_RECEIVED","RECOGNITION_TEAM_RECEIVED","SUGGESTION_SENT","SUGGESTION_ACCEPTED","COMMENT_ENGAGEMENT"]},"RewardsStatsTopReward":{"type":"object","properties":{"rewardId":{"type":"string"},"title":{"type":"string"},"count":{"type":"integer","format":"int32"},"pointsRedeemed":{"type":"integer","format":"int64"}}},"RewardsStatsParticipation":{"type":"object","properties":{"weeksBefore":{"type":"integer","format":"int32"},"weeksAfter":{"type":"integer","format":"int32"},"hiBefore":{"type":"integer","format":"int32"},"hiAfter":{"type":"integer","format":"int32"},"surveyBefore":{"type":"integer","format":"int32"},"surveyAfter":{"type":"integer","format":"int32"},"series":{"type":"array","items":{"$ref":"#/components/schemas/RewardsStatsWeekPoint"}}}},"RewardsStatsWeekPoint":{"type":"object","properties":{"week":{"type":"string"},"hi":{"type":"integer","format":"int32"},"survey":{"type":"integer","format":"int32"}}}}},"paths":{"/api/v1/company/rewards/stats":{"get":{"tags":["Rewards"],"summary":"Aggregated rewards analytics","operationId":"getRewardsStats","parameters":[{"name":"period","in":"query","required":false,"schema":{"type":"string"}},{"name":"hierarchyId","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/RewardsStats"}}}}}}}}}
```

## GET /api/v1/company/rewards/redemptions

> List redemptions, optionally by status

```json
{"openapi":"3.1.0","info":{"title":"Happyforce API","version":"v1"},"tags":[],"servers":[{"url":"{url}","description":"API URL","variables":{"url":{"description":"API Environment","enum":["https://api.happyforce.com","https://staging.happyforce.com","http://localhost:9000"],"default":"https://api.happyforce.com"}}}],"security":[{"companyAPISessionId":[]}],"components":{"securitySchemes":{"companyAPISessionId":{"type":"apiKey","description":"SessionId","name":"SessionId","in":"header"}},"schemas":{"RedemptionStatus":{"type":"string","description":"Lifecycle state of a reward redemption","enum":["RESERVING","FAILED","PENDING","APPROVED","DELIVERED","REJECTED","CANCELLED","FULFILLED"]},"Redemption":{"type":"object","description":"An employee's redemption of a catalog item","properties":{"id":{"type":"string"},"internalId":{"type":"integer","format":"int32"},"employeeName":{"type":"string"},"employeeArea":{"type":"string"},"employeeAvatarUrl":{"type":"string"},"rewardId":{"type":"string"},"rewardTitle":{"type":"string"},"cost":{"type":"integer","format":"int32"},"fulfillmentType":{"$ref":"#/components/schemas/RewardFulfillmentType"},"status":{"$ref":"#/components/schemas/RedemptionStatus"},"rejectionReason":{"$ref":"#/components/schemas/RedemptionRejectionReason"},"rejectionMessage":{"type":"string"},"deliveryNote":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"RewardFulfillmentType":{"type":"string","description":"How a redeemed catalog item is fulfilled","enum":["MANUAL","DIGITAL_CODE"]},"RedemptionRejectionReason":{"type":"string","description":"Reason an admin rejected a redemption","enum":["NO_STOCK","CONDITIONS","DUPLICATE","OTHER"]}}},"paths":{"/api/v1/company/rewards/redemptions":{"get":{"tags":["Rewards"],"summary":"List redemptions, optionally by status","operationId":"listRewardsRedemptions","parameters":[{"name":"status","in":"query","required":false,"schema":{"$ref":"#/components/schemas/RedemptionStatus"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Redemption"}}}}}}}}}}
```

## GET /api/v1/company/rewards/ledger

> List an employee's points ledger

```json
{"openapi":"3.1.0","info":{"title":"Happyforce API","version":"v1"},"tags":[],"servers":[{"url":"{url}","description":"API URL","variables":{"url":{"description":"API Environment","enum":["https://api.happyforce.com","https://staging.happyforce.com","http://localhost:9000"],"default":"https://api.happyforce.com"}}}],"security":[{"companyAPISessionId":[]}],"components":{"securitySchemes":{"companyAPISessionId":{"type":"apiKey","description":"SessionId","name":"SessionId","in":"header"}},"schemas":{"PointsLedgerEntry":{"type":"object","description":"A points-ledger movement","properties":{"type":{"$ref":"#/components/schemas/PointsEntryType"},"actionType":{"$ref":"#/components/schemas/RewardActionType"},"points":{"type":"integer","format":"int32"},"day":{"type":"string","format":"date"},"reason":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}},"PointsEntryType":{"type":"string","description":"Kind of points-ledger movement","enum":["EARN","REDEEM","REFUND","ADJUST","PODIUM_BONUS"]},"RewardActionType":{"type":"string","description":"Action that may award reward points","enum":["HI_VOTE","VOTE_STREAK","SURVEY_COMPLETED","ENPS_VOTE","SCORES_VOTE","CHECKIN_VOTE","RECOGNITION_SENT","RECOGNITION_RECEIVED","RECOGNITION_TEAM_RECEIVED","SUGGESTION_SENT","SUGGESTION_ACCEPTED","COMMENT_ENGAGEMENT"]}}},"paths":{"/api/v1/company/rewards/ledger":{"get":{"tags":["Rewards"],"summary":"List an employee's points ledger","operationId":"getRewardsLedger","parameters":[{"name":"internalId","in":"query","required":true,"schema":{"type":"integer","format":"int32"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PointsLedgerEntry"}}}}}}}}}}
```
