Process campaign reward claims using role-based detection. Supports all claim types: system, business, and user claims through a single endpoint.
- Get my campaign claims (Convenience)
Reward Claims Processing
Create campaign claim
Get campaign claims with advanced filtering
Get my campaign claims (C...
PERS-api Documentation (2.0.12)
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
Overview
Languages
Servers
Mock server
https://docs.pers.ninja/_mock/swagger
Production API
https://api.pers.ninja/v2
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
Bodyapplication/jsonrequired
Campaign claim request. Use CampaignClaimRequestDTO for user claims or CampaignClaimBusinessRequestDTO structure for business/system claims.
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.
The campaign multiplier that will be applied to the reward. This determines the final reward amount (reward * multiplier). Default is 1.0
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
DEPRECATED: Use with triggerSource instead.Business identifier - provides additional context and validation for the claim.
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.
- Mock serverhttps://docs.pers.ninja/_mock/swagger/campaigns/claims
- Production APIhttps://api.pers.ninja/v2/campaigns/claims
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
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": {},
"businessId": "string",
"campaignId": "string"
}'Campaign claim processed successfully
User
Universal identifier email for deterministic operations. Generated from B2B inputs (email, externalId) for wallet salt generation and external integrations.
Example: "user123@user.pers.internal"
Current active signing account ID for external wallet operations
User-owned counterfactual smart contract wallets that can receive tokens
Owner type for polymorphic ownership
Value{"USER":"user","BUSINESS":"business","TENANT":"tenant","SYSTEM":"system","EXTERNAL":"external"}
Example: "user"
Type of internal wallet
Value{"CUSTODIAL":"custodial","NON_CUSTODIAL":"non-custodial"}
Current status of the wallet
Value{"PENDING":"pending","ACTIVE":"active","SUSPENDED":"suspended","ARCHIVED":"archived"}
ID of signing account that owns this internal wallet
The campaign that the user is claiming
Campaign start date, default is the current date
Campaign isTestnet, this means that the campaign is running on testnet, not mainnet
Default false
Campaign trigger: what triggers the campaign, and what are the conditions for the trigger to be activated
DEPRECATED - use maxPerDayPerUser: Campaign trigger max per day
Campaign trigger max geo distance to Business in meters
Campaign trigger type
Enum"CLAIM_BY_USER""CLAIM_BY_SYSTEM""CLAIM_BY_BUSINESS"
Campaign trigger completion threshold. This indicates the number of completions required before the reward is granted
Campaign trigger max total completions across all users
Campaign trigger max total completions per day across all users
Campaign trigger conditions
Source logic type defining how multiple trigger sources combine to activate the flow
Default "any"
Value"any"
Array [
TokenDTO object
Metadata of the token, this is optional and can be null in case of Point token
this is the abi of the contract, this is the interface of the contract to interact with it
this is the chain id of the chain where the token is deployed
this is the url of the abi of the contract, to be used to fetch the abi of the contract
this is the symbol of the token contract, this is optional and can be null
this is the decimals of the token. This is optional and only used for ERC20 tokens (Points)
This can be used to enable or disable the token
This can be used to enable or disable the token for gallery
token metadata incremental id for the token unit, this is used to identify the specific token metadata that should be minted
Token unit amount is the amount of tokens that the user will receive when aquiring the token unit
Token unit max amount, this is the maximum amount of tokens that the user can receive when aquiring the token unit. This is relevant e.g. in campaigns where a user may receive token units per revenue spent etc
Campaign businesses: what businesses are involved in the campaign
A short description of the business engagement with indications what to do etc
businesses
The id of the business, this is unique and will be used to identify the business.
The email of the business, this is unique and will be used to identify the business.
The address of the business, this is the address that will be shown to the public.
The legal name of the business, this is the name that will be used for legal purposes.
The display name of the business, this is the name that will be shown to the public.
The description of the business, this is the description that will be shown to the public.
The short description of the business, this is the description that will be shown to the public.
The website of the business, this is the website that will be shown to the public.
The image of the business, this is the image that will be shown to the public.
The address of the business, this is the address that will be shown to the public.
The city of the business, this is the city that will be shown to the public.
The postal code of the business, this is the postal code that will be shown to the public.
The latitude of the business, this is the latitude that will be shown to the public.
The longitude of the business, this is the longitude that will be shown to the public.
The business type of the business, this is the business type that will be shown to the public.
The status of the business, this is the status that will be shown to the public.
The ability to mint token for the business, this is the ability that will be shown to the public.
The ability to charge token for the business, this is the ability that will be shown to the public.
The ability to manage users for the business, this is the ability that will be shown to the public.
max per business, the maximum number of times a user can engage with the buisness in the campaign
max per day, the maximum number of times a user can engage with the buisness in the campaign per day
Country code restrictions as an array of strings (e.g., ["NOT_ES", "FR"])
Example: ["NOT_ES","FR"]
Array [
Type of the trigger source
Enum"QR_CODE""API_WEBHOOK"
Example: "QR_CODE"
Human-readable name for the trigger source
Example: "Main Entrance QR Code"
Optional description explaining this trigger source
Example: "QR code located at the main entrance for visitor check-in"
Type-specific configuration and settings
Example: {"tokenConfig":{"tokenId":"1"}}
Reference to the business that owns this trigger source. Optional - can be tenant-wide trigger sources
Example: "business-uuid-123"
Unique identifier for the trigger source
Example: "source-12345"
Whether this trigger source is currently active. Inactive sources won't trigger any flows
Example: true
Usage analytics and statistics for this trigger source
Timestamp when the trigger source was created
Example: "2024-01-01T12:00:00.000Z"
Timestamp when the trigger source was last updated
Example: "2024-01-10T12:00:00.000Z"
Response
application/json
{ "id": "string", "createdAt": {}, "user": { "id": "string", "email": {}, "identifierEmail": "user123@user.pers.internal", "firstName": {}, "lastName": {}, "externalId": {}, "accountAddress": {}, "instagramAccountId": {}, "googleAccountName": {}, "customData": {}, "publicProfile": {}, "isActive": true, "currentSigningAccountId": {}, "wallets": [ … ] }, "campaign": { "name": "string", "description": "string", "beneficiaryAccountAddress": "string", "startDate": "2019-08-24T14:15:22Z", "endDate": "2019-08-24T14:15:22Z", "imageUrl": "string", "externalUrl": "string", "id": "string", "isActive": false, "isTestnet": false, "trigger": { … }, "tokenUnits": [ … ], "businessEngagements": [ … ], "createdAt": "2026-01-14T09:56:20.954Z", "updatedAt": null, "order": 1, "tags": [], "countryCodeRestrictions": [ … ], "triggerSources": [ … ] }, "userCountryCode": "string", "business": { "id": "string", "email": {}, "accountAddress": {}, "businessLegalName": {}, "displayName": {}, "description": {}, "shortDescription": {}, "websiteUrl": {}, "imageUrl": {}, "streetAddress": {}, "city": {}, "postalCode": {}, "coordsLatitude": {}, "coordsLongitude": {}, "businessType": { … }, "isActive": true, "canMintToken": true, "canChargeToken": true, "canManageUsers": true, "canReceiveDonation": true } }
Request
Get campaign claims with comprehensive filtering options: - campaignId: Filter by specific campaign (optional) - userId: Filter by specific user ID (admin only) - businessId: Filter by specific business ID (admin/business context)
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
- Mock serverhttps://docs.pers.ninja/_mock/swagger/campaigns/claims
- Production APIhttps://api.pers.ninja/v2/campaigns/claims
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X GET \
'https://docs.pers.ninja/_mock/swagger/campaigns/claims?campaignId=string&userId=string&businessId=string' \
-H 'x-project-key: YOUR_API_KEY_HERE'Campaign claims retrieved successfully
User
Universal identifier email for deterministic operations. Generated from B2B inputs (email, externalId) for wallet salt generation and external integrations.
Example: "user123@user.pers.internal"
Current active signing account ID for external wallet operations
User-owned counterfactual smart contract wallets that can receive tokens
Owner type for polymorphic ownership
Value{"USER":"user","BUSINESS":"business","TENANT":"tenant","SYSTEM":"system","EXTERNAL":"external"}
Example: "user"
Type of internal wallet
Value{"CUSTODIAL":"custodial","NON_CUSTODIAL":"non-custodial"}
Current status of the wallet
Value{"PENDING":"pending","ACTIVE":"active","SUSPENDED":"suspended","ARCHIVED":"archived"}
ID of signing account that owns this internal wallet
The campaign that the user is claiming
Campaign start date, default is the current date
Campaign isTestnet, this means that the campaign is running on testnet, not mainnet
Default false
Campaign trigger: what triggers the campaign, and what are the conditions for the trigger to be activated
DEPRECATED - use maxPerDayPerUser: Campaign trigger max per day
Campaign trigger max geo distance to Business in meters
Campaign trigger type
Enum"CLAIM_BY_USER""CLAIM_BY_SYSTEM""CLAIM_BY_BUSINESS"
Campaign trigger completion threshold. This indicates the number of completions required before the reward is granted
Campaign trigger max total completions across all users
Campaign trigger max total completions per day across all users
Campaign trigger conditions
Source logic type defining how multiple trigger sources combine to activate the flow
Default "any"
Value"any"
Array [
TokenDTO object
Metadata of the token, this is optional and can be null in case of Point token
this is the abi of the contract, this is the interface of the contract to interact with it
this is the chain id of the chain where the token is deployed
this is the url of the abi of the contract, to be used to fetch the abi of the contract
this is the symbol of the token contract, this is optional and can be null
this is the decimals of the token. This is optional and only used for ERC20 tokens (Points)
This can be used to enable or disable the token
This can be used to enable or disable the token for gallery
token metadata incremental id for the token unit, this is used to identify the specific token metadata that should be minted
Token unit amount is the amount of tokens that the user will receive when aquiring the token unit
Token unit max amount, this is the maximum amount of tokens that the user can receive when aquiring the token unit. This is relevant e.g. in campaigns where a user may receive token units per revenue spent etc
Campaign businesses: what businesses are involved in the campaign
A short description of the business engagement with indications what to do etc
businesses
The id of the business, this is unique and will be used to identify the business.
The email of the business, this is unique and will be used to identify the business.
The address of the business, this is the address that will be shown to the public.
The legal name of the business, this is the name that will be used for legal purposes.
The display name of the business, this is the name that will be shown to the public.
The description of the business, this is the description that will be shown to the public.
The short description of the business, this is the description that will be shown to the public.
The website of the business, this is the website that will be shown to the public.
The image of the business, this is the image that will be shown to the public.
The address of the business, this is the address that will be shown to the public.
The city of the business, this is the city that will be shown to the public.
The postal code of the business, this is the postal code that will be shown to the public.
The latitude of the business, this is the latitude that will be shown to the public.
The longitude of the business, this is the longitude that will be shown to the public.
The business type of the business, this is the business type that will be shown to the public.
The status of the business, this is the status that will be shown to the public.
The ability to mint token for the business, this is the ability that will be shown to the public.
The ability to charge token for the business, this is the ability that will be shown to the public.
The ability to manage users for the business, this is the ability that will be shown to the public.
max per business, the maximum number of times a user can engage with the buisness in the campaign
max per day, the maximum number of times a user can engage with the buisness in the campaign per day
Country code restrictions as an array of strings (e.g., ["NOT_ES", "FR"])
Example: ["NOT_ES","FR"]
Array [
Type of the trigger source
Enum"QR_CODE""API_WEBHOOK"
Example: "QR_CODE"
Human-readable name for the trigger source
Example: "Main Entrance QR Code"
Optional description explaining this trigger source
Example: "QR code located at the main entrance for visitor check-in"
Type-specific configuration and settings
Example: {"tokenConfig":{"tokenId":"1"}}
Reference to the business that owns this trigger source. Optional - can be tenant-wide trigger sources
Example: "business-uuid-123"
Unique identifier for the trigger source
Example: "source-12345"
Whether this trigger source is currently active. Inactive sources won't trigger any flows
Example: true
Usage analytics and statistics for this trigger source
Timestamp when the trigger source was created
Example: "2024-01-01T12:00:00.000Z"
Timestamp when the trigger source was last updated
Example: "2024-01-10T12:00:00.000Z"
Response
application/json
[ { "id": "string", "createdAt": {}, "user": { … }, "campaign": { … }, "userCountryCode": "string", "business": { … } } ]
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.
Features:
- Automatic user context (no userId parameter needed)
- Optional campaign filtering
- Requires user authentication
- Simplified response structure
Usage Examples:
- GET /campaign-claims/me (all claims for authenticated user)
- GET /campaign-claims/me?campaignId=123 (user claims for specific campaign)
Security
authJWT
- Mock serverhttps://docs.pers.ninja/_mock/swagger/campaigns/claims/me
- Production APIhttps://api.pers.ninja/v2/campaigns/claims/me
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X GET \
'https://docs.pers.ninja/_mock/swagger/campaigns/claims/me?campaignId=string' \
-H 'Authorization: Bearer <YOUR_JWT_HERE>'User campaign claims retrieved successfully
User
Universal identifier email for deterministic operations. Generated from B2B inputs (email, externalId) for wallet salt generation and external integrations.
Example: "user123@user.pers.internal"
Current active signing account ID for external wallet operations
User-owned counterfactual smart contract wallets that can receive tokens
Owner type for polymorphic ownership
Value{"USER":"user","BUSINESS":"business","TENANT":"tenant","SYSTEM":"system","EXTERNAL":"external"}
Example: "user"
Type of internal wallet
Value{"CUSTODIAL":"custodial","NON_CUSTODIAL":"non-custodial"}
Current status of the wallet
Value{"PENDING":"pending","ACTIVE":"active","SUSPENDED":"suspended","ARCHIVED":"archived"}
ID of signing account that owns this internal wallet
The campaign that the user is claiming
Campaign start date, default is the current date
Campaign isTestnet, this means that the campaign is running on testnet, not mainnet
Default false
Campaign trigger: what triggers the campaign, and what are the conditions for the trigger to be activated
DEPRECATED - use maxPerDayPerUser: Campaign trigger max per day
Campaign trigger max geo distance to Business in meters
Campaign trigger type
Enum"CLAIM_BY_USER""CLAIM_BY_SYSTEM""CLAIM_BY_BUSINESS"
Campaign trigger completion threshold. This indicates the number of completions required before the reward is granted
Campaign trigger max total completions across all users
Campaign trigger max total completions per day across all users
Campaign trigger conditions
Source logic type defining how multiple trigger sources combine to activate the flow
Default "any"
Value"any"
Array [
TokenDTO object
Metadata of the token, this is optional and can be null in case of Point token
this is the abi of the contract, this is the interface of the contract to interact with it
this is the chain id of the chain where the token is deployed
this is the url of the abi of the contract, to be used to fetch the abi of the contract
this is the symbol of the token contract, this is optional and can be null
this is the decimals of the token. This is optional and only used for ERC20 tokens (Points)
This can be used to enable or disable the token
This can be used to enable or disable the token for gallery
token metadata incremental id for the token unit, this is used to identify the specific token metadata that should be minted
Token unit amount is the amount of tokens that the user will receive when aquiring the token unit
Token unit max amount, this is the maximum amount of tokens that the user can receive when aquiring the token unit. This is relevant e.g. in campaigns where a user may receive token units per revenue spent etc
Campaign businesses: what businesses are involved in the campaign
A short description of the business engagement with indications what to do etc
businesses
The id of the business, this is unique and will be used to identify the business.
The email of the business, this is unique and will be used to identify the business.
The address of the business, this is the address that will be shown to the public.
The legal name of the business, this is the name that will be used for legal purposes.
The display name of the business, this is the name that will be shown to the public.
The description of the business, this is the description that will be shown to the public.
The short description of the business, this is the description that will be shown to the public.
The website of the business, this is the website that will be shown to the public.
The image of the business, this is the image that will be shown to the public.
The address of the business, this is the address that will be shown to the public.
The city of the business, this is the city that will be shown to the public.
The postal code of the business, this is the postal code that will be shown to the public.
The latitude of the business, this is the latitude that will be shown to the public.
The longitude of the business, this is the longitude that will be shown to the public.
The business type of the business, this is the business type that will be shown to the public.
The status of the business, this is the status that will be shown to the public.
The ability to mint token for the business, this is the ability that will be shown to the public.
The ability to charge token for the business, this is the ability that will be shown to the public.
The ability to manage users for the business, this is the ability that will be shown to the public.
max per business, the maximum number of times a user can engage with the buisness in the campaign
max per day, the maximum number of times a user can engage with the buisness in the campaign per day
Country code restrictions as an array of strings (e.g., ["NOT_ES", "FR"])
Example: ["NOT_ES","FR"]
Array [
Type of the trigger source
Enum"QR_CODE""API_WEBHOOK"
Example: "QR_CODE"
Human-readable name for the trigger source
Example: "Main Entrance QR Code"
Optional description explaining this trigger source
Example: "QR code located at the main entrance for visitor check-in"
Type-specific configuration and settings
Example: {"tokenConfig":{"tokenId":"1"}}
Reference to the business that owns this trigger source. Optional - can be tenant-wide trigger sources
Example: "business-uuid-123"
Unique identifier for the trigger source
Example: "source-12345"
Whether this trigger source is currently active. Inactive sources won't trigger any flows
Example: true
Usage analytics and statistics for this trigger source
Timestamp when the trigger source was created
Example: "2024-01-01T12:00:00.000Z"
Timestamp when the trigger source was last updated
Example: "2024-01-10T12:00:00.000Z"
Response
application/json
[ { "id": "string", "createdAt": {}, "user": { … }, "campaign": { … }, "userCountryCode": "string", "business": { … } } ]