Token entity id
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
Overview
Languages
Servers
Mock server
https://docs.pers.ninja/_mock/swagger
https://api.pers.ninja/v2
Token unit management for campaign reward distribution. Defines specific token rewards that users receive when campaign participation conditions are met.
Reward Configuration:
•
Token Association:
Link specific token types and amounts to campaigns
•
Reward Rules:
Define token distribution rules and conditions
•
Multi-Token Support:
Configure multiple token types per campaign
•
Reward Calculation:
Set fixed or variable token amounts based on actions
•
Distribution Management:
Control how and when tokens are distributed to users
Request
Add a new token unit to campaign for reward distribution. Admin-only operation. Replaces POST /campaign/admin/{id}/token-units
Security
authJWT
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
- Mock serverhttps://docs.pers.ninja/_mock/swagger/campaigns/{campaignId}/tokens
- https://api.pers.ninja/v2/campaigns/{campaignId}/tokens
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X POST \
'https://docs.pers.ninja/_mock/swagger/campaigns/{campaignId}/tokens' \
-H 'Authorization: Bearer <YOUR_JWT_HERE>' \
-H 'Content-Type: application/json' \
-d '{
"tokenId": "string",
"tokenEntityId": "string",
"tokenMetadataIncrementalId": 0,
"amount": 0,
"maxAmount": 0
}'Campaign token unit created successfully
Campaign isTestnet, this means that the campaign is running on testnet, not mainnet
Default false
Country code restrictions as an array of strings (e.g., ["NOT_ES", "FR"])
Example: ["NOT_ES","FR"]
Campaign trigger: what triggers the campaign, and what are the conditions for the trigger to be activated
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 per day across all users
Maximum claims per trigger source for this campaign. Limits how many times each individual trigger source can be used.
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 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
Array [
A short description of the business engagement with indications what to do etc
Business IDs associated with this engagement. Use CampaignDTO.included.businesses for full entities.
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
The external URL for the business engagement, e.g. a link to a website or app
Businesses (DEPRECATED: use businessIds + CampaignDTO.included.businesses instead. Will be removed in Q2 2026)
Example: [{"id":"business-uuid-1"},{"id":"business-uuid-2"}]
Trigger source IDs. Use to batch fetch or request via ?include=triggerSources
Example: ["trigger-uuid-1","trigger-uuid-2"]
Response
application/json
{ "id": "string", "name": "string", "description": "string", "beneficiaryAccountAddress": "string", "startDate": "2019-08-24T14:15:22Z", "endDate": "2019-08-24T14:15:22Z", "imageUrl": "string", "externalUrl": "string", "isActive": false, "isTestnet": false, "createdAt": "2026-03-12T10:57:54.230Z", "updatedAt": null, "order": 1, "tags": [], "countryCodeRestrictions": [ "NOT_ES", "FR" ], "trigger": { "name": "string", "description": "string", "maxPerDay": 0, "maxPerDayPerUser": 0, "maxPerUser": 0, "minCooldownSeconds": 0, "maxGeoDistanceInMeters": 0, "requiredUserInfo": "string", "triggerType": "CLAIM_BY_USER", "maxMultiplier": 0, "completionThreshold": 0, "maxTotal": 0, "maxPerDayTotal": 0, "maxPerSource": 0, "conditions": [ … ], "sourceLogic": "any", "id": "string" }, "tokenUnits": [ [ … ] ], "businessEngagements": [ [ … ] ], "triggerSourceIds": [ "trigger-uuid-1", "trigger-uuid-2" ], "included": { "triggerSources": [ … ], "businesses": [ … ] } }
Request
Update an existing token unit in campaign. Admin-only operation. Replaces PUT /campaign/admin/{id}/token-units/{tokenUnitId}
Security
authJWT
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
- Mock serverhttps://docs.pers.ninja/_mock/swagger/campaigns/{campaignId}/tokens/{tokenUnitId}
- https://api.pers.ninja/v2/campaigns/{campaignId}/tokens/{tokenUnitId}
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X PUT \
'https://docs.pers.ninja/_mock/swagger/campaigns/{campaignId}/tokens/{tokenUnitId}' \
-H 'Authorization: Bearer <YOUR_JWT_HERE>' \
-H 'Content-Type: application/json' \
-d '{
"tokenId": "string",
"tokenEntityId": "string",
"tokenMetadataIncrementalId": 0,
"amount": 0,
"maxAmount": 0
}'Campaign token unit updated successfully
Campaign isTestnet, this means that the campaign is running on testnet, not mainnet
Default false
Country code restrictions as an array of strings (e.g., ["NOT_ES", "FR"])
Example: ["NOT_ES","FR"]
Campaign trigger: what triggers the campaign, and what are the conditions for the trigger to be activated
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 per day across all users
Maximum claims per trigger source for this campaign. Limits how many times each individual trigger source can be used.
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 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
Array [
A short description of the business engagement with indications what to do etc
Business IDs associated with this engagement. Use CampaignDTO.included.businesses for full entities.
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
The external URL for the business engagement, e.g. a link to a website or app
Businesses (DEPRECATED: use businessIds + CampaignDTO.included.businesses instead. Will be removed in Q2 2026)
Example: [{"id":"business-uuid-1"},{"id":"business-uuid-2"}]
Trigger source IDs. Use to batch fetch or request via ?include=triggerSources
Example: ["trigger-uuid-1","trigger-uuid-2"]
Response
application/json
{ "id": "string", "name": "string", "description": "string", "beneficiaryAccountAddress": "string", "startDate": "2019-08-24T14:15:22Z", "endDate": "2019-08-24T14:15:22Z", "imageUrl": "string", "externalUrl": "string", "isActive": false, "isTestnet": false, "createdAt": "2026-03-12T10:57:54.230Z", "updatedAt": null, "order": 1, "tags": [], "countryCodeRestrictions": [ "NOT_ES", "FR" ], "trigger": { "name": "string", "description": "string", "maxPerDay": 0, "maxPerDayPerUser": 0, "maxPerUser": 0, "minCooldownSeconds": 0, "maxGeoDistanceInMeters": 0, "requiredUserInfo": "string", "triggerType": "CLAIM_BY_USER", "maxMultiplier": 0, "completionThreshold": 0, "maxTotal": 0, "maxPerDayTotal": 0, "maxPerSource": 0, "conditions": [ … ], "sourceLogic": "any", "id": "string" }, "tokenUnits": [ [ … ] ], "businessEngagements": [ [ … ] ], "triggerSourceIds": [ "trigger-uuid-1", "trigger-uuid-2" ], "included": { "triggerSources": [ … ], "businesses": [ … ] } }
- Mock serverhttps://docs.pers.ninja/_mock/swagger/campaigns/{campaignId}/tokens/{tokenUnitId}
- https://api.pers.ninja/v2/campaigns/{campaignId}/tokens/{tokenUnitId}
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X DELETE \
'https://docs.pers.ninja/_mock/swagger/campaigns/{campaignId}/tokens/{tokenUnitId}' \
-H 'Authorization: Bearer <YOUR_JWT_HERE>'Campaign token unit removed successfully
Campaign isTestnet, this means that the campaign is running on testnet, not mainnet
Default false
Country code restrictions as an array of strings (e.g., ["NOT_ES", "FR"])
Example: ["NOT_ES","FR"]
Campaign trigger: what triggers the campaign, and what are the conditions for the trigger to be activated
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 per day across all users
Maximum claims per trigger source for this campaign. Limits how many times each individual trigger source can be used.
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 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
Array [
A short description of the business engagement with indications what to do etc
Business IDs associated with this engagement. Use CampaignDTO.included.businesses for full entities.
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
The external URL for the business engagement, e.g. a link to a website or app
Businesses (DEPRECATED: use businessIds + CampaignDTO.included.businesses instead. Will be removed in Q2 2026)
Example: [{"id":"business-uuid-1"},{"id":"business-uuid-2"}]
Trigger source IDs. Use to batch fetch or request via ?include=triggerSources
Example: ["trigger-uuid-1","trigger-uuid-2"]
Response
application/json
{ "id": "string", "name": "string", "description": "string", "beneficiaryAccountAddress": "string", "startDate": "2019-08-24T14:15:22Z", "endDate": "2019-08-24T14:15:22Z", "imageUrl": "string", "externalUrl": "string", "isActive": false, "isTestnet": false, "createdAt": "2026-03-12T10:57:54.230Z", "updatedAt": null, "order": 1, "tags": [], "countryCodeRestrictions": [ "NOT_ES", "FR" ], "trigger": { "name": "string", "description": "string", "maxPerDay": 0, "maxPerDayPerUser": 0, "maxPerUser": 0, "minCooldownSeconds": 0, "maxGeoDistanceInMeters": 0, "requiredUserInfo": "string", "triggerType": "CLAIM_BY_USER", "maxMultiplier": 0, "completionThreshold": 0, "maxTotal": 0, "maxPerDayTotal": 0, "maxPerSource": 0, "conditions": [ … ], "sourceLogic": "any", "id": "string" }, "tokenUnits": [ [ … ] ], "businessEngagements": [ [ … ] ], "triggerSourceIds": [ "trigger-uuid-1", "trigger-uuid-2" ], "included": { "triggerSources": [ … ], "businesses": [ … ] } }