Skip to content
/
Reward Claims Processing

PERS-api Documentation (2.2.2)

PERS API Documentation

This RESTful API enables seamless integration of Web3 loyalty, token management, and engagement features into your applications.

Usage Guidelines:

  • RESTful Design: Resources are accessed via standard HTTP methods (GET, POST, PUT, DELETE) with predictable, resource-oriented URLs.
  • Authentication: Secure access is enforced via Bearer Tokens (JWT) and Project Keys (defining the Tenant context).
  • Data Format: All requests and responses utilize standard JSON formatting.

Explore the modules below for detailed endpoint specifications, schemas, and testing capabilities.

Download OpenAPI description
swagger.json
swagger.yaml
Overview
Languages
Servers
Mock server
https://docs.pers.ninja/_mock/swagger
https://api.pers.ninja/v2

Tenants

Operations

Admins

Operations

Tokens

Operations

Campaigns

Operations

Campaign Tags

Operations

Campaign Tokens

Operations

Campaign Triggers

Operations

Campaign Engagements

Operations

Campaign Claims

Operations

Reward Claims Processing

Multi-level reward claim processing with comprehensive security features and audit trails. Handles reward distribution with full security features.
Security Features:

•
Multi-Level Access:
USER, BUSINESS, SYSTEM, ADMIN claim processing levels

•
Security Monitoring:
IP tracking and behavioral analysis for security

•
Audit Tracking:
Complete transaction history and activity logs

•
Context Attribution:
User and business context preservation for tracking

•
Claim Verification:
Multi-step verification process for high-value rewards

Access Levels:

•
USER:
Direct customer reward claims with user authentication

•
BUSINESS:
B2B reward processing with business context attribution

•
SYSTEM:
Automated claims processing via secure API integration

•
ADMIN:
Complete administrative oversight and manual claim processing

Create campaign claim

Request

Process campaign reward claims using role-based detection. Supports all claim types: system, business, and user claims through a single endpoint.

Security
projectKey or authJWT
Bodyapplication/jsonrequired

Campaign claim request. Use CampaignClaimRequestDTO for user claims or CampaignClaimBusinessRequestDTO structure for business/system claims.

triggerSourceIdstring

The trigger source ID (NEW - preferred). Use this for trigger-specific claims (QR codes, NFC tags, geofences, etc.). Takes precedence over campaignId if both are provided.

metadataobject

The campaign metadata associated with the claim.

multipliernumber

The campaign multiplier that will be applied to the reward. This determines the final reward amount (reward * multiplier). Default is 1.0

latitudenumber

User's current latitude for location-based validation. Required when CampaignTrigger has maxGeoDistanceInMeters configured. System validates user is within allowed distance from TriggerSource location (coordsLatitude) or Business location fallback.

longitudenumber

User's current longitude for location-based validation. Required when CampaignTrigger has maxGeoDistanceInMeters configured. System validates user is within allowed distance from TriggerSource location (coordsLongitude) or Business location fallback.

userIdentifierstring

The user identifier, e.g. email or external id. This is used to identify the user making the claim, if not provided in request context

userInfoobject

User information required by the campaign trigger. Only needed if CampaignTrigger.requiredUserInfo is set AND the user profile does not already have these fields stored. Provide fields specified in CampaignTrigger.requiredUserInfo (e.g., email, phoneNumber, firstName, lastName, dateOfBirth, etc.). Backend validates that required fields are either already stored or provided here.

Example: {"email":"user@example.com","phoneNumber":"+1234567890","firstName":"John"}
businessIdstring

DEPRECATED: Use with triggerSource instead. Business identifier - provides additional context and validation for the claim. Will be removed in Q2 2026

campaignIdstring

DEPRECATED: The campaign ID. Still supported for backward compatibility, but use triggerSourceId for new implementations. If both campaignId and triggerSourceId are provided, triggerSourceId takes precedence. NOTE: If campaign has trigger sources configured, triggerSourceId becomes required and campaignId alone will result in an error. Will be removed in Q2 2026

curl -i -X POST \
  https://docs.pers.ninja/_mock/swagger/campaigns/claims \
  -H 'Content-Type: application/json' \
  -H 'x-project-key: YOUR_API_KEY_HERE' \
  -d '{
    "triggerSourceId": "string",
    "metadata": {},
    "multiplier": 0,
    "latitude": 0,
    "longitude": 0,
    "userIdentifier": "string",
    "userInfo": {
      "email": "user@example.com",
      "phoneNumber": "+1234567890",
      "firstName": "John"
    },
    "businessId": "string",
    "campaignId": "string"
  }'

Responses

Campaign claim processed successfully

Bodyapplication/json
idstringrequired

The id of the campaign user claim

createdAtobjectrequired

The date the campaign user claim was created

userIdstringrequired

User ID who claimed the campaign

campaignIdstringrequired

Campaign ID that was claimed

businessIdstring or null

Business ID associated with this claim (if applicable)

triggerSourceIdstring or null

Trigger Source ID that was used for this claim (e.g., specific QR code, NFC tag, etc.)

userCountryCodestring or nullrequired

Country code of the user claiming the campaign

statusstringrequired

Status of the claim processing (PENDING, PROCESSING, COMPLETED, FAILED)

Enum"PENDING""PROCESSING""COMPLETED""FAILED"
messagestring or null

Status or error message for the claim

includedobject or null

Included related entities. Only populated when include parameter is specified. Contains campaign, user, business, triggerSource, and/or transactions entities based on requested relations.

userobjectDeprecatedrequired

User object (DEPRECATED: use userId instead. Only contains {id} during migration. Will be removed in Q2 2026)

Example: {"id":"user-uuid-123"}
campaignobjectDeprecatedrequired

Campaign object (DEPRECATED: use campaignId instead. Only contains {id} during migration. Will be removed in Q2 2026)

Example: {"id":"campaign-uuid-123"}
businessobjectDeprecated

Business object (DEPRECATED: use businessId instead. Only contains {id} during migration. Will be removed in Q2 2026)

Example: {"id":"business-uuid-123"}
Response
application/json
{
  "id": "string",
  "createdAt": {},
  "userId": "string",
  "campaignId": "string",
  "businessId": "string",
  "triggerSourceId": "string",
  "user": {
    "id": "user-uuid-123"
  },
  "campaign": {
    "id": "campaign-uuid-123"
  },
  "business": {
    "id": "business-uuid-123"
  },
  "userCountryCode": "string",
  "status": "PENDING",
  "message": "string",
  "included": {
    "campaign": { … },
    "user": { … },
    "business": { … },
    "triggerSource": { … },
    "transactions": [ … ]
  }
}

Get campaign claims with advanced filtering

Request

Get campaign claims with comprehensive filtering options. Use pagination parameters (page & limit) for optimal performance - critical for high-volume campaigns. Legacy support: returns array without params (deprecated - will be removed in future).

  • campaignId: Filter by specific campaign (optional)
  • userId: Filter by specific user ID (admin only)
  • businessId: Filter by specific business ID (admin only)
  • include: Optionally include related entities (campaign, user, business, transactions)

Access Control:

  • Users: See only their own claims, campaignId optional
  • Business: See only claims associated with their business account, campaignId optional
  • Admin: Can filter by any combination of parameters or see all claims

Security Notes:

  • Users cannot access userId or businessId parameters (automatically filtered)
  • Business accounts automatically filter to their own businessId regardless of parameter
  • Admin has full access to all filtering options
Security
projectKey or authJWT
Query
campaignIdstring

Filter by specific campaign ID

userIdstring

Filter by specific user ID (admin only)

businessIdstring

Filter by specific business ID (admin only)

includeArray of strings

Include related entities: campaign, user, business, triggerSource, transactions (comma-separated)

pagenumber

Page number (1-based)

limitnumber

Items per page

curl -i -X GET \
  'https://docs.pers.ninja/_mock/swagger/campaigns/claims?campaignId=string&userId=string&businessId=string&include=string&page=0&limit=0' \
  -H 'x-project-key: YOUR_API_KEY_HERE'

Responses

Campaign claims retrieved successfully

Bodyapplication/jsonArray [
idstringrequired

The id of the campaign user claim

createdAtobjectrequired

The date the campaign user claim was created

userIdstringrequired

User ID who claimed the campaign

campaignIdstringrequired

Campaign ID that was claimed

businessIdstring or null

Business ID associated with this claim (if applicable)

triggerSourceIdstring or null

Trigger Source ID that was used for this claim (e.g., specific QR code, NFC tag, etc.)

userCountryCodestring or nullrequired

Country code of the user claiming the campaign

statusstringrequired

Status of the claim processing (PENDING, PROCESSING, COMPLETED, FAILED)

Enum"PENDING""PROCESSING""COMPLETED""FAILED"
messagestring or null

Status or error message for the claim

includedobject or null

Included related entities. Only populated when include parameter is specified. Contains campaign, user, business, triggerSource, and/or transactions entities based on requested relations.

userobjectDeprecatedrequired

User object (DEPRECATED: use userId instead. Only contains {id} during migration. Will be removed in Q2 2026)

Example: {"id":"user-uuid-123"}
campaignobjectDeprecatedrequired

Campaign object (DEPRECATED: use campaignId instead. Only contains {id} during migration. Will be removed in Q2 2026)

Example: {"id":"campaign-uuid-123"}
businessobjectDeprecated

Business object (DEPRECATED: use businessId instead. Only contains {id} during migration. Will be removed in Q2 2026)

Example: {"id":"business-uuid-123"}
]
Response
application/json
[
  {
    "id": "string",
    "createdAt": {},
    "userId": "string",
    "campaignId": "string",
    "businessId": "string",
    "triggerSourceId": "string",
    "user": { … },
    "campaign": { … },
    "business": { … },
    "userCountryCode": "string",
    "status": "PENDING",
    "message": "string",
    "included": { … }
  }
]

Get my campaign claims (Convenience)

Request

Convenience endpoint for authenticated users to retrieve their own campaign claims.

Equivalent to GET /campaign-claims but with required authentication and automatic filtering to current user context. Use pagination parameters (page & limit) for optimal performance - recommended for active users. Legacy support: returns array without params (deprecated - will be removed in future).

Features:

  • Automatic user context (no userId parameter needed)
  • Optional campaign filtering
  • Requires user authentication
  • Simplified response structure
  • Optional entity inclusion (campaign, user, business, transactions)

Usage Examples:

  • GET /campaign-claims/me (all claims for authenticated user)
  • GET /campaign-claims/me?campaignId=123 (user claims for specific campaign)
  • GET /campaign-claims/me?include=campaign,transactions (with related entities)
Security
authJWT
Query
campaignIdstring

Filter by specific campaign ID

includeArray of strings

Include related entities: campaign, user, business, triggerSource, transactions (comma-separated)

pagenumber

Page number (1-based)

limitnumber

Items per page

curl -i -X GET \
  'https://docs.pers.ninja/_mock/swagger/campaigns/claims/me?campaignId=string&include=string&page=0&limit=0' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

User campaign claims retrieved successfully

Bodyapplication/jsonArray [
idstringrequired

The id of the campaign user claim

createdAtobjectrequired

The date the campaign user claim was created

userIdstringrequired

User ID who claimed the campaign

campaignIdstringrequired

Campaign ID that was claimed

businessIdstring or null

Business ID associated with this claim (if applicable)

triggerSourceIdstring or null

Trigger Source ID that was used for this claim (e.g., specific QR code, NFC tag, etc.)

userCountryCodestring or nullrequired

Country code of the user claiming the campaign

statusstringrequired

Status of the claim processing (PENDING, PROCESSING, COMPLETED, FAILED)

Enum"PENDING""PROCESSING""COMPLETED""FAILED"
messagestring or null

Status or error message for the claim

includedobject or null

Included related entities. Only populated when include parameter is specified. Contains campaign, user, business, triggerSource, and/or transactions entities based on requested relations.

userobjectDeprecatedrequired

User object (DEPRECATED: use userId instead. Only contains {id} during migration. Will be removed in Q2 2026)

Example: {"id":"user-uuid-123"}
campaignobjectDeprecatedrequired

Campaign object (DEPRECATED: use campaignId instead. Only contains {id} during migration. Will be removed in Q2 2026)

Example: {"id":"campaign-uuid-123"}
businessobjectDeprecated

Business object (DEPRECATED: use businessId instead. Only contains {id} during migration. Will be removed in Q2 2026)

Example: {"id":"business-uuid-123"}
]
Response
application/json
[
  {
    "id": "string",
    "createdAt": {},
    "userId": "string",
    "campaignId": "string",
    "businessId": "string",
    "triggerSourceId": "string",
    "user": { … },
    "campaign": { … },
    "business": { … },
    "userCountryCode": "string",
    "status": "PENDING",
    "message": "string",
    "included": { … }
  }
]

Redemptions

Operations

Purchases

Operations

Businesses

Operations

Transactions

Operations

Users

Operations

Balances

Operations

Files

Operations

Web3 Chains

Operations

Contracts

Operations

Auth

Operations

Root

Operations

Well-known

Operations

Trigger Sources

Operations

Business Types

Operations

Redemption Types

Operations

Redemption Redeems

Operations

Redemption Tokens

Operations

API Keys

Operations