Skip to content
/
Assign trigger source to...

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

Core Campaign Management

Core campaign CRUD operations with intelligent access detection. Handles campaign lifecycle management including creation, updates, activation, and querying with role-based access control.
Campaign Operations:

•
Campaign Discovery:
Public browsing of active campaigns without authentication

•
Advanced Filtering:
Query campaigns by tags, status, and custom criteria

•
Lifecycle Management:
Full campaign CRUD with proper state transitions

•
Environment Control:
Toggle campaigns between testnet and mainnet modes

•
Access Intelligence:
Automatic privilege detection for appropriate data exposure

Campaign Module

Get campaigns (Intelligent Access)

Request

Endpoint that adapts based on authentication: Public users get active campaigns with filtering, Business users get all campaigns (active+inactive) for their business only, Admin users get all campaigns with full filtering. Use pagination parameters (page & limit) for optimal performance - critical for large campaign datasets. Legacy support: returns array without params (deprecated - will be removed in future). Replaces GET /campaign and GET /campaign/admin

Security
authJWT or projectKey
Query
activeboolean

Filter by active status (Admin only: true=active, false=inactive, omit=all). Ignored for public/business access.

tagstring

Filter by tag

businessIdstring

Filter by business engagement (returns campaigns where business is engaged). Ignored for business access (auto-filtered to own business).

pagenumber

Page number (1-based). When provided with limit, enables DB-level pagination for optimal performance.

limitnumber

Items per page (default: 50, max: 10000)

sortBystring

Sort field

Enum"name""createdAt""startDate"
sortOrderstring

Sort direction

Enum"ASC""DESC"
includeArray of strings

Include related entities. Valid options: triggerSources, businesses. Use comma-separated for multiple.

curl -i -X GET \
  'https://docs.pers.ninja/_mock/swagger/campaigns?active=true&tag=string&businessId=string&page=0&limit=0&sortBy=name&sortOrder=ASC&include=string' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Campaigns retrieved based on access level

Bodyapplication/jsonArray [
idstringrequired

Campaign id

namestring or nullrequired

Campaign name

descriptionstring or nullrequired

Campaign description

beneficiaryAccountAddressstring or nullrequired

Campaign beneficiary account address

startDatestring or null(date-time)required

Campaign start date, default is the current date

endDatestring or null(date-time)required

Campaign end date

imageUrlstring or nullrequired

img url

externalUrlstring or nullrequired

Campaign url

isActivebooleanrequired

Campaign isActive

Default false
isTestnetboolean

Campaign isTestnet, this means that the campaign is running on testnet, not mainnet

Default false
createdAtstring(date-time)required

create date

Default "2026-03-12T10:57:54.230Z"
updatedAtstring or null(date-time)required

update date

Default null
ordernumberrequired

Campaign order

Default 1
tagsArray of stringsrequired

Campaign tags

Default []
countryCodeRestrictionsobject

Country code restrictions as an array of strings (e.g., ["NOT_ES", "FR"])

Example: ["NOT_ES","FR"]
triggerobject or nullrequired

Campaign trigger: what triggers the campaign, and what are the conditions for the trigger to be activated

trigger.​namestring

Campaign trigger name

trigger.​descriptionstring

Campaign trigger description

trigger.​maxPerDaynumber or null

DEPRECATED - use maxPerDayPerUser: Campaign trigger max per day

trigger.​maxPerDayPerUsernumber or null

Campaign trigger max per day per user

trigger.​maxPerUsernumber or null

Campaign trigger max per user

trigger.​minCooldownSecondsnumber or null

Campaign trigger min cooldown seconds

trigger.​maxGeoDistanceInMetersnumber or null

Campaign trigger max geo distance to Business in meters

trigger.​requiredUserInfostring or null

Campaign trigger required user info

trigger.​triggerTypestring

Campaign trigger type

Enum"CLAIM_BY_USER""CLAIM_BY_SYSTEM""CLAIM_BY_BUSINESS"
trigger.​maxMultipliernumber or null

Campaign trigger max multiplier

trigger.​completionThresholdnumber or null

Campaign trigger completion threshold. This indicates the number of completions required before the reward is granted

trigger.​maxTotalnumber or null

Campaign trigger max total completions across all users

trigger.​maxPerDayTotalnumber or null

Campaign trigger max total completions per day across all users

trigger.​maxPerSourcenumber or null

Maximum claims per trigger source for this campaign. Limits how many times each individual trigger source can be used.

trigger.​conditionsArray of objects(CampaignTriggerConditionDTO)

Campaign trigger conditions

trigger.​sourceLogicstring

Source logic type defining how multiple trigger sources combine to activate the flow

Default "any"
Value"any"
trigger.​idstringrequired

Campaign trigger id

tokenUnitsArray of objects(TokenUnitDTO)required
Array [
tokenUnits[][].​idstringrequired

Token unit id

tokenUnits[][].​tokenobjectrequired

TokenDTO object

tokenUnits[][].​token.​idstringrequired

Id of the token

tokenUnits[][].​token.​contractAddressstringrequired

Address of the token

tokenUnits[][].​token.​metadataArray of objects(TokenMetadataDTO)

Metadata of the token, this is optional and can be null in case of Point token

tokenUnits[][].​token.​abiobjectrequired

this is the abi of the contract, this is the interface of the contract to interact with it

tokenUnits[][].​token.​chainIdnumberrequired

this is the chain id of the chain where the token is deployed

tokenUnits[][].​token.​abiUrlobjectrequired

this is the url of the abi of the contract, to be used to fetch the abi of the contract

tokenUnits[][].​token.​namestring

this is the name of the token contract

tokenUnits[][].​token.​symbolstring

this is the symbol of the token contract, this is optional and can be null

tokenUnits[][].​token.​decimalsnumber

this is the decimals of the token. This is optional and only used for ERC20 tokens (Points)

tokenUnits[][].​token.​isActivebooleanrequired

This can be used to enable or disable the token

tokenUnits[][].​token.​isGallerybooleanrequired

This can be used to enable or disable the token for gallery

tokenUnits[][].​token.​typestringrequired

This is the underlying web3 native type of the token contract

Enum"ERC20""ERC1155""ERC721"
tokenUnits[][].​tokenMetadataIncrementalIdnumber or null

token metadata incremental id for the token unit, this is used to identify the specific token metadata that should be minted

tokenUnits[][].​amountnumberrequired

Token unit amount is the amount of tokens that the user will receive when aquiring the token unit

tokenUnits[][].​maxAmountnumber or null

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

]
businessEngagementsArray of objects(CampaignBusinessEngagementDTO)required
Array [
businessEngagements[][].​idstringrequired

id

businessEngagements[][].​shortDescriptionnumber or nullrequired

A short description of the business engagement with indications what to do etc

businessEngagements[][].​businessIdsArray of stringsrequired

Business IDs associated with this engagement. Use CampaignDTO.included.businesses for full entities.

businessEngagements[][].​campaignIdstringrequired

Campaign id

businessEngagements[][].​maxPerBusinessnumber or nullrequired

max per business, the maximum number of times a user can engage with the buisness in the campaign

businessEngagements[][].​maxPerDaynumber or nullrequired

max per day, the maximum number of times a user can engage with the buisness in the campaign per day

businessEngagements[][].​externalUrlstring or nullrequired

The external URL for the business engagement, e.g. a link to a website or app

businessEngagements[][].​businessesArray of arraysDeprecatedrequired

Businesses (DEPRECATED: use businessIds + CampaignDTO.included.businesses instead. Will be removed in Q2 2026)

Example: [{"id":"business-uuid-1"},{"id":"business-uuid-2"}]
]
triggerSourceIdsArray of arraysrequired

Trigger source IDs. Use to batch fetch or request via ?include=triggerSources

Example: ["trigger-uuid-1","trigger-uuid-2"]
includedobject or null

Included related entities. Only populated when include parameter is specified.

]
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": [ … ],
    "trigger": { … },
    "tokenUnits": [ … ],
    "businessEngagements": [ … ],
    "triggerSourceIds": [ … ],
    "included": { … }
  }
]

Create campaign (Admin)

Request

Create a new campaign. Admin-only operation. Replaces POST /campaign/admin/

Security
authJWT
Bodyapplication/jsonrequired
namestring

Campaign name

descriptionstring or null

Campaign description

beneficiaryAccountAddressstring or null

Campaign beneficiary account address

startDatestring or null(date-time)

Campaign start date

endDatestring or null(date-time)

Campaign end date

imageUrlstring or null

Campaign image URL

externalUrlstring or null

Campaign external URL

ordernumber or null

Campaign display order

countryCodeRestrictionsobject or null

Country code restrictions as an array of strings (e.g., ["NOT_ES", "FR"])

Example: ["NOT_ES","FR"]
curl -i -X POST \
  https://docs.pers.ninja/_mock/swagger/campaigns \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "string",
    "description": "string",
    "beneficiaryAccountAddress": "string",
    "startDate": "2019-08-24T14:15:22Z",
    "endDate": "2019-08-24T14:15:22Z",
    "imageUrl": "string",
    "externalUrl": "string",
    "order": 0,
    "countryCodeRestrictions": [
      "NOT_ES",
      "FR"
    ]
  }'

Responses

Campaign created successfully

Bodyapplication/json
idstringrequired

Campaign id

namestring or nullrequired

Campaign name

descriptionstring or nullrequired

Campaign description

beneficiaryAccountAddressstring or nullrequired

Campaign beneficiary account address

startDatestring or null(date-time)required

Campaign start date, default is the current date

endDatestring or null(date-time)required

Campaign end date

imageUrlstring or nullrequired

img url

externalUrlstring or nullrequired

Campaign url

isActivebooleanrequired

Campaign isActive

Default false
isTestnetboolean

Campaign isTestnet, this means that the campaign is running on testnet, not mainnet

Default false
createdAtstring(date-time)required

create date

Default "2026-03-12T10:57:54.230Z"
updatedAtstring or null(date-time)required

update date

Default null
ordernumberrequired

Campaign order

Default 1
tagsArray of stringsrequired

Campaign tags

Default []
countryCodeRestrictionsobject

Country code restrictions as an array of strings (e.g., ["NOT_ES", "FR"])

Example: ["NOT_ES","FR"]
triggerobject or nullrequired

Campaign trigger: what triggers the campaign, and what are the conditions for the trigger to be activated

trigger.​namestring

Campaign trigger name

trigger.​descriptionstring

Campaign trigger description

trigger.​maxPerDaynumber or null

DEPRECATED - use maxPerDayPerUser: Campaign trigger max per day

trigger.​maxPerDayPerUsernumber or null

Campaign trigger max per day per user

trigger.​maxPerUsernumber or null

Campaign trigger max per user

trigger.​minCooldownSecondsnumber or null

Campaign trigger min cooldown seconds

trigger.​maxGeoDistanceInMetersnumber or null

Campaign trigger max geo distance to Business in meters

trigger.​requiredUserInfostring or null

Campaign trigger required user info

trigger.​triggerTypestring

Campaign trigger type

Enum"CLAIM_BY_USER""CLAIM_BY_SYSTEM""CLAIM_BY_BUSINESS"
trigger.​maxMultipliernumber or null

Campaign trigger max multiplier

trigger.​completionThresholdnumber or null

Campaign trigger completion threshold. This indicates the number of completions required before the reward is granted

trigger.​maxTotalnumber or null

Campaign trigger max total completions across all users

trigger.​maxPerDayTotalnumber or null

Campaign trigger max total completions per day across all users

trigger.​maxPerSourcenumber or null

Maximum claims per trigger source for this campaign. Limits how many times each individual trigger source can be used.

trigger.​conditionsArray of objects(CampaignTriggerConditionDTO)

Campaign trigger conditions

trigger.​sourceLogicstring

Source logic type defining how multiple trigger sources combine to activate the flow

Default "any"
Value"any"
trigger.​idstringrequired

Campaign trigger id

tokenUnitsArray of objects(TokenUnitDTO)required
Array [
tokenUnits[][].​idstringrequired

Token unit id

tokenUnits[][].​tokenobjectrequired

TokenDTO object

tokenUnits[][].​token.​idstringrequired

Id of the token

tokenUnits[][].​token.​contractAddressstringrequired

Address of the token

tokenUnits[][].​token.​metadataArray of objects(TokenMetadataDTO)

Metadata of the token, this is optional and can be null in case of Point token

tokenUnits[][].​token.​abiobjectrequired

this is the abi of the contract, this is the interface of the contract to interact with it

tokenUnits[][].​token.​chainIdnumberrequired

this is the chain id of the chain where the token is deployed

tokenUnits[][].​token.​abiUrlobjectrequired

this is the url of the abi of the contract, to be used to fetch the abi of the contract

tokenUnits[][].​token.​namestring

this is the name of the token contract

tokenUnits[][].​token.​symbolstring

this is the symbol of the token contract, this is optional and can be null

tokenUnits[][].​token.​decimalsnumber

this is the decimals of the token. This is optional and only used for ERC20 tokens (Points)

tokenUnits[][].​token.​isActivebooleanrequired

This can be used to enable or disable the token

tokenUnits[][].​token.​isGallerybooleanrequired

This can be used to enable or disable the token for gallery

tokenUnits[][].​token.​typestringrequired

This is the underlying web3 native type of the token contract

Enum"ERC20""ERC1155""ERC721"
tokenUnits[][].​tokenMetadataIncrementalIdnumber or null

token metadata incremental id for the token unit, this is used to identify the specific token metadata that should be minted

tokenUnits[][].​amountnumberrequired

Token unit amount is the amount of tokens that the user will receive when aquiring the token unit

tokenUnits[][].​maxAmountnumber or null

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

]
businessEngagementsArray of objects(CampaignBusinessEngagementDTO)required
Array [
businessEngagements[][].​idstringrequired

id

businessEngagements[][].​shortDescriptionnumber or nullrequired

A short description of the business engagement with indications what to do etc

businessEngagements[][].​businessIdsArray of stringsrequired

Business IDs associated with this engagement. Use CampaignDTO.included.businesses for full entities.

businessEngagements[][].​campaignIdstringrequired

Campaign id

businessEngagements[][].​maxPerBusinessnumber or nullrequired

max per business, the maximum number of times a user can engage with the buisness in the campaign

businessEngagements[][].​maxPerDaynumber or nullrequired

max per day, the maximum number of times a user can engage with the buisness in the campaign per day

businessEngagements[][].​externalUrlstring or nullrequired

The external URL for the business engagement, e.g. a link to a website or app

businessEngagements[][].​businessesArray of arraysDeprecatedrequired

Businesses (DEPRECATED: use businessIds + CampaignDTO.included.businesses instead. Will be removed in Q2 2026)

Example: [{"id":"business-uuid-1"},{"id":"business-uuid-2"}]
]
triggerSourceIdsArray of arraysrequired

Trigger source IDs. Use to batch fetch or request via ?include=triggerSources

Example: ["trigger-uuid-1","trigger-uuid-2"]
includedobject or null

Included related entities. Only populated when include parameter is specified.

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": [ … ]
  }
}

Get campaign by ID

Request

Get single campaign details by ID. Available to public with project key. Replaces GET /campaign/{id}

Security
projectKey
Path
idstringrequired
Query
includeArray of strings

Include related entities. Valid options: triggerSources, businesses. Use comma-separated for multiple.

curl -i -X GET \
  'https://docs.pers.ninja/_mock/swagger/campaigns/{id}?include=string' \
  -H 'x-project-key: YOUR_API_KEY_HERE'

Responses

Campaign retrieved

Bodyapplication/json
idstringrequired

Campaign id

namestring or nullrequired

Campaign name

descriptionstring or nullrequired

Campaign description

beneficiaryAccountAddressstring or nullrequired

Campaign beneficiary account address

startDatestring or null(date-time)required

Campaign start date, default is the current date

endDatestring or null(date-time)required

Campaign end date

imageUrlstring or nullrequired

img url

externalUrlstring or nullrequired

Campaign url

isActivebooleanrequired

Campaign isActive

Default false
isTestnetboolean

Campaign isTestnet, this means that the campaign is running on testnet, not mainnet

Default false
createdAtstring(date-time)required

create date

Default "2026-03-12T10:57:54.230Z"
updatedAtstring or null(date-time)required

update date

Default null
ordernumberrequired

Campaign order

Default 1
tagsArray of stringsrequired

Campaign tags

Default []
countryCodeRestrictionsobject

Country code restrictions as an array of strings (e.g., ["NOT_ES", "FR"])

Example: ["NOT_ES","FR"]
triggerobject or nullrequired

Campaign trigger: what triggers the campaign, and what are the conditions for the trigger to be activated

trigger.​namestring

Campaign trigger name

trigger.​descriptionstring

Campaign trigger description

trigger.​maxPerDaynumber or null

DEPRECATED - use maxPerDayPerUser: Campaign trigger max per day

trigger.​maxPerDayPerUsernumber or null

Campaign trigger max per day per user

trigger.​maxPerUsernumber or null

Campaign trigger max per user

trigger.​minCooldownSecondsnumber or null

Campaign trigger min cooldown seconds

trigger.​maxGeoDistanceInMetersnumber or null

Campaign trigger max geo distance to Business in meters

trigger.​requiredUserInfostring or null

Campaign trigger required user info

trigger.​triggerTypestring

Campaign trigger type

Enum"CLAIM_BY_USER""CLAIM_BY_SYSTEM""CLAIM_BY_BUSINESS"
trigger.​maxMultipliernumber or null

Campaign trigger max multiplier

trigger.​completionThresholdnumber or null

Campaign trigger completion threshold. This indicates the number of completions required before the reward is granted

trigger.​maxTotalnumber or null

Campaign trigger max total completions across all users

trigger.​maxPerDayTotalnumber or null

Campaign trigger max total completions per day across all users

trigger.​maxPerSourcenumber or null

Maximum claims per trigger source for this campaign. Limits how many times each individual trigger source can be used.

trigger.​conditionsArray of objects(CampaignTriggerConditionDTO)

Campaign trigger conditions

trigger.​sourceLogicstring

Source logic type defining how multiple trigger sources combine to activate the flow

Default "any"
Value"any"
trigger.​idstringrequired

Campaign trigger id

tokenUnitsArray of objects(TokenUnitDTO)required
Array [
tokenUnits[][].​idstringrequired

Token unit id

tokenUnits[][].​tokenobjectrequired

TokenDTO object

tokenUnits[][].​token.​idstringrequired

Id of the token

tokenUnits[][].​token.​contractAddressstringrequired

Address of the token

tokenUnits[][].​token.​metadataArray of objects(TokenMetadataDTO)

Metadata of the token, this is optional and can be null in case of Point token

tokenUnits[][].​token.​abiobjectrequired

this is the abi of the contract, this is the interface of the contract to interact with it

tokenUnits[][].​token.​chainIdnumberrequired

this is the chain id of the chain where the token is deployed

tokenUnits[][].​token.​abiUrlobjectrequired

this is the url of the abi of the contract, to be used to fetch the abi of the contract

tokenUnits[][].​token.​namestring

this is the name of the token contract

tokenUnits[][].​token.​symbolstring

this is the symbol of the token contract, this is optional and can be null

tokenUnits[][].​token.​decimalsnumber

this is the decimals of the token. This is optional and only used for ERC20 tokens (Points)

tokenUnits[][].​token.​isActivebooleanrequired

This can be used to enable or disable the token

tokenUnits[][].​token.​isGallerybooleanrequired

This can be used to enable or disable the token for gallery

tokenUnits[][].​token.​typestringrequired

This is the underlying web3 native type of the token contract

Enum"ERC20""ERC1155""ERC721"
tokenUnits[][].​tokenMetadataIncrementalIdnumber or null

token metadata incremental id for the token unit, this is used to identify the specific token metadata that should be minted

tokenUnits[][].​amountnumberrequired

Token unit amount is the amount of tokens that the user will receive when aquiring the token unit

tokenUnits[][].​maxAmountnumber or null

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

]
businessEngagementsArray of objects(CampaignBusinessEngagementDTO)required
Array [
businessEngagements[][].​idstringrequired

id

businessEngagements[][].​shortDescriptionnumber or nullrequired

A short description of the business engagement with indications what to do etc

businessEngagements[][].​businessIdsArray of stringsrequired

Business IDs associated with this engagement. Use CampaignDTO.included.businesses for full entities.

businessEngagements[][].​campaignIdstringrequired

Campaign id

businessEngagements[][].​maxPerBusinessnumber or nullrequired

max per business, the maximum number of times a user can engage with the buisness in the campaign

businessEngagements[][].​maxPerDaynumber or nullrequired

max per day, the maximum number of times a user can engage with the buisness in the campaign per day

businessEngagements[][].​externalUrlstring or nullrequired

The external URL for the business engagement, e.g. a link to a website or app

businessEngagements[][].​businessesArray of arraysDeprecatedrequired

Businesses (DEPRECATED: use businessIds + CampaignDTO.included.businesses instead. Will be removed in Q2 2026)

Example: [{"id":"business-uuid-1"},{"id":"business-uuid-2"}]
]
triggerSourceIdsArray of arraysrequired

Trigger source IDs. Use to batch fetch or request via ?include=triggerSources

Example: ["trigger-uuid-1","trigger-uuid-2"]
includedobject or null

Included related entities. Only populated when include parameter is specified.

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": [ … ]
  }
}

Update campaign (Admin)

Request

Update an existing campaign. Admin-only operation. Replaces PUT /campaign/admin/{id}

Security
authJWT
Path
idstringrequired
Bodyapplication/jsonrequired
namestring

Campaign name

descriptionstring or null

Campaign description

beneficiaryAccountAddressstring or null

Campaign beneficiary account address

startDatestring or null(date-time)

Campaign start date

endDatestring or null(date-time)

Campaign end date

imageUrlstring or null

Campaign image URL

externalUrlstring or null

Campaign external URL

ordernumber or null

Campaign display order

countryCodeRestrictionsobject or null

Country code restrictions as an array of strings (e.g., ["NOT_ES", "FR"])

Example: ["NOT_ES","FR"]
curl -i -X PUT \
  'https://docs.pers.ninja/_mock/swagger/campaigns/{id}' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "string",
    "description": "string",
    "beneficiaryAccountAddress": "string",
    "startDate": "2019-08-24T14:15:22Z",
    "endDate": "2019-08-24T14:15:22Z",
    "imageUrl": "string",
    "externalUrl": "string",
    "order": 0,
    "countryCodeRestrictions": [
      "NOT_ES",
      "FR"
    ]
  }'

Responses

Campaign updated successfully

Bodyapplication/json
idstringrequired

Campaign id

namestring or nullrequired

Campaign name

descriptionstring or nullrequired

Campaign description

beneficiaryAccountAddressstring or nullrequired

Campaign beneficiary account address

startDatestring or null(date-time)required

Campaign start date, default is the current date

endDatestring or null(date-time)required

Campaign end date

imageUrlstring or nullrequired

img url

externalUrlstring or nullrequired

Campaign url

isActivebooleanrequired

Campaign isActive

Default false
isTestnetboolean

Campaign isTestnet, this means that the campaign is running on testnet, not mainnet

Default false
createdAtstring(date-time)required

create date

Default "2026-03-12T10:57:54.230Z"
updatedAtstring or null(date-time)required

update date

Default null
ordernumberrequired

Campaign order

Default 1
tagsArray of stringsrequired

Campaign tags

Default []
countryCodeRestrictionsobject

Country code restrictions as an array of strings (e.g., ["NOT_ES", "FR"])

Example: ["NOT_ES","FR"]
triggerobject or nullrequired

Campaign trigger: what triggers the campaign, and what are the conditions for the trigger to be activated

trigger.​namestring

Campaign trigger name

trigger.​descriptionstring

Campaign trigger description

trigger.​maxPerDaynumber or null

DEPRECATED - use maxPerDayPerUser: Campaign trigger max per day

trigger.​maxPerDayPerUsernumber or null

Campaign trigger max per day per user

trigger.​maxPerUsernumber or null

Campaign trigger max per user

trigger.​minCooldownSecondsnumber or null

Campaign trigger min cooldown seconds

trigger.​maxGeoDistanceInMetersnumber or null

Campaign trigger max geo distance to Business in meters

trigger.​requiredUserInfostring or null

Campaign trigger required user info

trigger.​triggerTypestring

Campaign trigger type

Enum"CLAIM_BY_USER""CLAIM_BY_SYSTEM""CLAIM_BY_BUSINESS"
trigger.​maxMultipliernumber or null

Campaign trigger max multiplier

trigger.​completionThresholdnumber or null

Campaign trigger completion threshold. This indicates the number of completions required before the reward is granted

trigger.​maxTotalnumber or null

Campaign trigger max total completions across all users

trigger.​maxPerDayTotalnumber or null

Campaign trigger max total completions per day across all users

trigger.​maxPerSourcenumber or null

Maximum claims per trigger source for this campaign. Limits how many times each individual trigger source can be used.

trigger.​conditionsArray of objects(CampaignTriggerConditionDTO)

Campaign trigger conditions

trigger.​sourceLogicstring

Source logic type defining how multiple trigger sources combine to activate the flow

Default "any"
Value"any"
trigger.​idstringrequired

Campaign trigger id

tokenUnitsArray of objects(TokenUnitDTO)required
Array [
tokenUnits[][].​idstringrequired

Token unit id

tokenUnits[][].​tokenobjectrequired

TokenDTO object

tokenUnits[][].​token.​idstringrequired

Id of the token

tokenUnits[][].​token.​contractAddressstringrequired

Address of the token

tokenUnits[][].​token.​metadataArray of objects(TokenMetadataDTO)

Metadata of the token, this is optional and can be null in case of Point token

tokenUnits[][].​token.​abiobjectrequired

this is the abi of the contract, this is the interface of the contract to interact with it

tokenUnits[][].​token.​chainIdnumberrequired

this is the chain id of the chain where the token is deployed

tokenUnits[][].​token.​abiUrlobjectrequired

this is the url of the abi of the contract, to be used to fetch the abi of the contract

tokenUnits[][].​token.​namestring

this is the name of the token contract

tokenUnits[][].​token.​symbolstring

this is the symbol of the token contract, this is optional and can be null

tokenUnits[][].​token.​decimalsnumber

this is the decimals of the token. This is optional and only used for ERC20 tokens (Points)

tokenUnits[][].​token.​isActivebooleanrequired

This can be used to enable or disable the token

tokenUnits[][].​token.​isGallerybooleanrequired

This can be used to enable or disable the token for gallery

tokenUnits[][].​token.​typestringrequired

This is the underlying web3 native type of the token contract

Enum"ERC20""ERC1155""ERC721"
tokenUnits[][].​tokenMetadataIncrementalIdnumber or null

token metadata incremental id for the token unit, this is used to identify the specific token metadata that should be minted

tokenUnits[][].​amountnumberrequired

Token unit amount is the amount of tokens that the user will receive when aquiring the token unit

tokenUnits[][].​maxAmountnumber or null

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

]
businessEngagementsArray of objects(CampaignBusinessEngagementDTO)required
Array [
businessEngagements[][].​idstringrequired

id

businessEngagements[][].​shortDescriptionnumber or nullrequired

A short description of the business engagement with indications what to do etc

businessEngagements[][].​businessIdsArray of stringsrequired

Business IDs associated with this engagement. Use CampaignDTO.included.businesses for full entities.

businessEngagements[][].​campaignIdstringrequired

Campaign id

businessEngagements[][].​maxPerBusinessnumber or nullrequired

max per business, the maximum number of times a user can engage with the buisness in the campaign

businessEngagements[][].​maxPerDaynumber or nullrequired

max per day, the maximum number of times a user can engage with the buisness in the campaign per day

businessEngagements[][].​externalUrlstring or nullrequired

The external URL for the business engagement, e.g. a link to a website or app

businessEngagements[][].​businessesArray of arraysDeprecatedrequired

Businesses (DEPRECATED: use businessIds + CampaignDTO.included.businesses instead. Will be removed in Q2 2026)

Example: [{"id":"business-uuid-1"},{"id":"business-uuid-2"}]
]
triggerSourceIdsArray of arraysrequired

Trigger source IDs. Use to batch fetch or request via ?include=triggerSources

Example: ["trigger-uuid-1","trigger-uuid-2"]
includedobject or null

Included related entities. Only populated when include parameter is specified.

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": [ … ]
  }
}

Delete campaign (Admin)

Request

Delete an existing campaign. Admin-only operation. Replaces DELETE /campaign/admin/{id}

Security
authJWT
Path
idstringrequired
curl -i -X DELETE \
  'https://docs.pers.ninja/_mock/swagger/campaigns/{id}' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Campaign deleted successfully

Bodyapplication/json
boolean
Response
application/json
true

Toggle campaign status (Admin)

Request

Toggle campaign active/inactive status. Admin-only operation. Replaces PUT /campaign/admin/{id}/activate

Security
authJWT
Path
idstringrequired
curl -i -X PUT \
  'https://docs.pers.ninja/_mock/swagger/campaigns/{id}/status' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Campaign status toggled successfully

Bodyapplication/json
idstringrequired

Campaign id

namestring or nullrequired

Campaign name

descriptionstring or nullrequired

Campaign description

beneficiaryAccountAddressstring or nullrequired

Campaign beneficiary account address

startDatestring or null(date-time)required

Campaign start date, default is the current date

endDatestring or null(date-time)required

Campaign end date

imageUrlstring or nullrequired

img url

externalUrlstring or nullrequired

Campaign url

isActivebooleanrequired

Campaign isActive

Default false
isTestnetboolean

Campaign isTestnet, this means that the campaign is running on testnet, not mainnet

Default false
createdAtstring(date-time)required

create date

Default "2026-03-12T10:57:54.230Z"
updatedAtstring or null(date-time)required

update date

Default null
ordernumberrequired

Campaign order

Default 1
tagsArray of stringsrequired

Campaign tags

Default []
countryCodeRestrictionsobject

Country code restrictions as an array of strings (e.g., ["NOT_ES", "FR"])

Example: ["NOT_ES","FR"]
triggerobject or nullrequired

Campaign trigger: what triggers the campaign, and what are the conditions for the trigger to be activated

trigger.​namestring

Campaign trigger name

trigger.​descriptionstring

Campaign trigger description

trigger.​maxPerDaynumber or null

DEPRECATED - use maxPerDayPerUser: Campaign trigger max per day

trigger.​maxPerDayPerUsernumber or null

Campaign trigger max per day per user

trigger.​maxPerUsernumber or null

Campaign trigger max per user

trigger.​minCooldownSecondsnumber or null

Campaign trigger min cooldown seconds

trigger.​maxGeoDistanceInMetersnumber or null

Campaign trigger max geo distance to Business in meters

trigger.​requiredUserInfostring or null

Campaign trigger required user info

trigger.​triggerTypestring

Campaign trigger type

Enum"CLAIM_BY_USER""CLAIM_BY_SYSTEM""CLAIM_BY_BUSINESS"
trigger.​maxMultipliernumber or null

Campaign trigger max multiplier

trigger.​completionThresholdnumber or null

Campaign trigger completion threshold. This indicates the number of completions required before the reward is granted

trigger.​maxTotalnumber or null

Campaign trigger max total completions across all users

trigger.​maxPerDayTotalnumber or null

Campaign trigger max total completions per day across all users

trigger.​maxPerSourcenumber or null

Maximum claims per trigger source for this campaign. Limits how many times each individual trigger source can be used.

trigger.​conditionsArray of objects(CampaignTriggerConditionDTO)

Campaign trigger conditions

trigger.​sourceLogicstring

Source logic type defining how multiple trigger sources combine to activate the flow

Default "any"
Value"any"
trigger.​idstringrequired

Campaign trigger id

tokenUnitsArray of objects(TokenUnitDTO)required
Array [
tokenUnits[][].​idstringrequired

Token unit id

tokenUnits[][].​tokenobjectrequired

TokenDTO object

tokenUnits[][].​token.​idstringrequired

Id of the token

tokenUnits[][].​token.​contractAddressstringrequired

Address of the token

tokenUnits[][].​token.​metadataArray of objects(TokenMetadataDTO)

Metadata of the token, this is optional and can be null in case of Point token

tokenUnits[][].​token.​abiobjectrequired

this is the abi of the contract, this is the interface of the contract to interact with it

tokenUnits[][].​token.​chainIdnumberrequired

this is the chain id of the chain where the token is deployed

tokenUnits[][].​token.​abiUrlobjectrequired

this is the url of the abi of the contract, to be used to fetch the abi of the contract

tokenUnits[][].​token.​namestring

this is the name of the token contract

tokenUnits[][].​token.​symbolstring

this is the symbol of the token contract, this is optional and can be null

tokenUnits[][].​token.​decimalsnumber

this is the decimals of the token. This is optional and only used for ERC20 tokens (Points)

tokenUnits[][].​token.​isActivebooleanrequired

This can be used to enable or disable the token

tokenUnits[][].​token.​isGallerybooleanrequired

This can be used to enable or disable the token for gallery

tokenUnits[][].​token.​typestringrequired

This is the underlying web3 native type of the token contract

Enum"ERC20""ERC1155""ERC721"
tokenUnits[][].​tokenMetadataIncrementalIdnumber or null

token metadata incremental id for the token unit, this is used to identify the specific token metadata that should be minted

tokenUnits[][].​amountnumberrequired

Token unit amount is the amount of tokens that the user will receive when aquiring the token unit

tokenUnits[][].​maxAmountnumber or null

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

]
businessEngagementsArray of objects(CampaignBusinessEngagementDTO)required
Array [
businessEngagements[][].​idstringrequired

id

businessEngagements[][].​shortDescriptionnumber or nullrequired

A short description of the business engagement with indications what to do etc

businessEngagements[][].​businessIdsArray of stringsrequired

Business IDs associated with this engagement. Use CampaignDTO.included.businesses for full entities.

businessEngagements[][].​campaignIdstringrequired

Campaign id

businessEngagements[][].​maxPerBusinessnumber or nullrequired

max per business, the maximum number of times a user can engage with the buisness in the campaign

businessEngagements[][].​maxPerDaynumber or nullrequired

max per day, the maximum number of times a user can engage with the buisness in the campaign per day

businessEngagements[][].​externalUrlstring or nullrequired

The external URL for the business engagement, e.g. a link to a website or app

businessEngagements[][].​businessesArray of arraysDeprecatedrequired

Businesses (DEPRECATED: use businessIds + CampaignDTO.included.businesses instead. Will be removed in Q2 2026)

Example: [{"id":"business-uuid-1"},{"id":"business-uuid-2"}]
]
triggerSourceIdsArray of arraysrequired

Trigger source IDs. Use to batch fetch or request via ?include=triggerSources

Example: ["trigger-uuid-1","trigger-uuid-2"]
includedobject or null

Included related entities. Only populated when include parameter is specified.

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": [ … ]
  }
}

Toggle campaign environment (Admin)

Request

Toggle campaign between testnet and mainnet environment. Admin-only operation. Replaces PUT /campaign/admin/{id}/environment

Security
authJWT
Path
idstringrequired
curl -i -X PUT \
  'https://docs.pers.ninja/_mock/swagger/campaigns/{id}/environment' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Campaign environment toggled successfully

Bodyapplication/json
idstringrequired

Campaign id

namestring or nullrequired

Campaign name

descriptionstring or nullrequired

Campaign description

beneficiaryAccountAddressstring or nullrequired

Campaign beneficiary account address

startDatestring or null(date-time)required

Campaign start date, default is the current date

endDatestring or null(date-time)required

Campaign end date

imageUrlstring or nullrequired

img url

externalUrlstring or nullrequired

Campaign url

isActivebooleanrequired

Campaign isActive

Default false
isTestnetboolean

Campaign isTestnet, this means that the campaign is running on testnet, not mainnet

Default false
createdAtstring(date-time)required

create date

Default "2026-03-12T10:57:54.230Z"
updatedAtstring or null(date-time)required

update date

Default null
ordernumberrequired

Campaign order

Default 1
tagsArray of stringsrequired

Campaign tags

Default []
countryCodeRestrictionsobject

Country code restrictions as an array of strings (e.g., ["NOT_ES", "FR"])

Example: ["NOT_ES","FR"]
triggerobject or nullrequired

Campaign trigger: what triggers the campaign, and what are the conditions for the trigger to be activated

trigger.​namestring

Campaign trigger name

trigger.​descriptionstring

Campaign trigger description

trigger.​maxPerDaynumber or null

DEPRECATED - use maxPerDayPerUser: Campaign trigger max per day

trigger.​maxPerDayPerUsernumber or null

Campaign trigger max per day per user

trigger.​maxPerUsernumber or null

Campaign trigger max per user

trigger.​minCooldownSecondsnumber or null

Campaign trigger min cooldown seconds

trigger.​maxGeoDistanceInMetersnumber or null

Campaign trigger max geo distance to Business in meters

trigger.​requiredUserInfostring or null

Campaign trigger required user info

trigger.​triggerTypestring

Campaign trigger type

Enum"CLAIM_BY_USER""CLAIM_BY_SYSTEM""CLAIM_BY_BUSINESS"
trigger.​maxMultipliernumber or null

Campaign trigger max multiplier

trigger.​completionThresholdnumber or null

Campaign trigger completion threshold. This indicates the number of completions required before the reward is granted

trigger.​maxTotalnumber or null

Campaign trigger max total completions across all users

trigger.​maxPerDayTotalnumber or null

Campaign trigger max total completions per day across all users

trigger.​maxPerSourcenumber or null

Maximum claims per trigger source for this campaign. Limits how many times each individual trigger source can be used.

trigger.​conditionsArray of objects(CampaignTriggerConditionDTO)

Campaign trigger conditions

trigger.​sourceLogicstring

Source logic type defining how multiple trigger sources combine to activate the flow

Default "any"
Value"any"
trigger.​idstringrequired

Campaign trigger id

tokenUnitsArray of objects(TokenUnitDTO)required
Array [
tokenUnits[][].​idstringrequired

Token unit id

tokenUnits[][].​tokenobjectrequired

TokenDTO object

tokenUnits[][].​token.​idstringrequired

Id of the token

tokenUnits[][].​token.​contractAddressstringrequired

Address of the token

tokenUnits[][].​token.​metadataArray of objects(TokenMetadataDTO)

Metadata of the token, this is optional and can be null in case of Point token

tokenUnits[][].​token.​abiobjectrequired

this is the abi of the contract, this is the interface of the contract to interact with it

tokenUnits[][].​token.​chainIdnumberrequired

this is the chain id of the chain where the token is deployed

tokenUnits[][].​token.​abiUrlobjectrequired

this is the url of the abi of the contract, to be used to fetch the abi of the contract

tokenUnits[][].​token.​namestring

this is the name of the token contract

tokenUnits[][].​token.​symbolstring

this is the symbol of the token contract, this is optional and can be null

tokenUnits[][].​token.​decimalsnumber

this is the decimals of the token. This is optional and only used for ERC20 tokens (Points)

tokenUnits[][].​token.​isActivebooleanrequired

This can be used to enable or disable the token

tokenUnits[][].​token.​isGallerybooleanrequired

This can be used to enable or disable the token for gallery

tokenUnits[][].​token.​typestringrequired

This is the underlying web3 native type of the token contract

Enum"ERC20""ERC1155""ERC721"
tokenUnits[][].​tokenMetadataIncrementalIdnumber or null

token metadata incremental id for the token unit, this is used to identify the specific token metadata that should be minted

tokenUnits[][].​amountnumberrequired

Token unit amount is the amount of tokens that the user will receive when aquiring the token unit

tokenUnits[][].​maxAmountnumber or null

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

]
businessEngagementsArray of objects(CampaignBusinessEngagementDTO)required
Array [
businessEngagements[][].​idstringrequired

id

businessEngagements[][].​shortDescriptionnumber or nullrequired

A short description of the business engagement with indications what to do etc

businessEngagements[][].​businessIdsArray of stringsrequired

Business IDs associated with this engagement. Use CampaignDTO.included.businesses for full entities.

businessEngagements[][].​campaignIdstringrequired

Campaign id

businessEngagements[][].​maxPerBusinessnumber or nullrequired

max per business, the maximum number of times a user can engage with the buisness in the campaign

businessEngagements[][].​maxPerDaynumber or nullrequired

max per day, the maximum number of times a user can engage with the buisness in the campaign per day

businessEngagements[][].​externalUrlstring or nullrequired

The external URL for the business engagement, e.g. a link to a website or app

businessEngagements[][].​businessesArray of arraysDeprecatedrequired

Businesses (DEPRECATED: use businessIds + CampaignDTO.included.businesses instead. Will be removed in Q2 2026)

Example: [{"id":"business-uuid-1"},{"id":"business-uuid-2"}]
]
triggerSourceIdsArray of arraysrequired

Trigger source IDs. Use to batch fetch or request via ?include=triggerSources

Example: ["trigger-uuid-1","trigger-uuid-2"]
includedobject or null

Included related entities. Only populated when include parameter is specified.

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": [ … ]
  }
}

Assign trigger source to campaign (Admin)

Request

Assign a trigger source to a specific campaign. Admin-only operation.

Security
authJWT
Path
idstringrequired
triggerSourceIdstringrequired
curl -i -X PUT \
  'https://docs.pers.ninja/_mock/swagger/campaigns/{id}/trigger-sources/{triggerSourceId}' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Trigger source assigned to campaign successfully

Bodyapplication/json
idstringrequired

Campaign id

namestring or nullrequired

Campaign name

descriptionstring or nullrequired

Campaign description

beneficiaryAccountAddressstring or nullrequired

Campaign beneficiary account address

startDatestring or null(date-time)required

Campaign start date, default is the current date

endDatestring or null(date-time)required

Campaign end date

imageUrlstring or nullrequired

img url

externalUrlstring or nullrequired

Campaign url

isActivebooleanrequired

Campaign isActive

Default false
isTestnetboolean

Campaign isTestnet, this means that the campaign is running on testnet, not mainnet

Default false
createdAtstring(date-time)required

create date

Default "2026-03-12T10:57:54.230Z"
updatedAtstring or null(date-time)required

update date

Default null
ordernumberrequired

Campaign order

Default 1
tagsArray of stringsrequired

Campaign tags

Default []
countryCodeRestrictionsobject

Country code restrictions as an array of strings (e.g., ["NOT_ES", "FR"])

Example: ["NOT_ES","FR"]
triggerobject or nullrequired

Campaign trigger: what triggers the campaign, and what are the conditions for the trigger to be activated

trigger.​namestring

Campaign trigger name

trigger.​descriptionstring

Campaign trigger description

trigger.​maxPerDaynumber or null

DEPRECATED - use maxPerDayPerUser: Campaign trigger max per day

trigger.​maxPerDayPerUsernumber or null

Campaign trigger max per day per user

trigger.​maxPerUsernumber or null

Campaign trigger max per user

trigger.​minCooldownSecondsnumber or null

Campaign trigger min cooldown seconds

trigger.​maxGeoDistanceInMetersnumber or null

Campaign trigger max geo distance to Business in meters

trigger.​requiredUserInfostring or null

Campaign trigger required user info

trigger.​triggerTypestring

Campaign trigger type

Enum"CLAIM_BY_USER""CLAIM_BY_SYSTEM""CLAIM_BY_BUSINESS"
trigger.​maxMultipliernumber or null

Campaign trigger max multiplier

trigger.​completionThresholdnumber or null

Campaign trigger completion threshold. This indicates the number of completions required before the reward is granted

trigger.​maxTotalnumber or null

Campaign trigger max total completions across all users

trigger.​maxPerDayTotalnumber or null

Campaign trigger max total completions per day across all users

trigger.​maxPerSourcenumber or null

Maximum claims per trigger source for this campaign. Limits how many times each individual trigger source can be used.

trigger.​conditionsArray of objects(CampaignTriggerConditionDTO)

Campaign trigger conditions

trigger.​sourceLogicstring

Source logic type defining how multiple trigger sources combine to activate the flow

Default "any"
Value"any"
trigger.​idstringrequired

Campaign trigger id

tokenUnitsArray of objects(TokenUnitDTO)required
Array [
tokenUnits[][].​idstringrequired

Token unit id

tokenUnits[][].​tokenobjectrequired

TokenDTO object

tokenUnits[][].​token.​idstringrequired

Id of the token

tokenUnits[][].​token.​contractAddressstringrequired

Address of the token

tokenUnits[][].​token.​metadataArray of objects(TokenMetadataDTO)

Metadata of the token, this is optional and can be null in case of Point token

tokenUnits[][].​token.​abiobjectrequired

this is the abi of the contract, this is the interface of the contract to interact with it

tokenUnits[][].​token.​chainIdnumberrequired

this is the chain id of the chain where the token is deployed

tokenUnits[][].​token.​abiUrlobjectrequired

this is the url of the abi of the contract, to be used to fetch the abi of the contract

tokenUnits[][].​token.​namestring

this is the name of the token contract

tokenUnits[][].​token.​symbolstring

this is the symbol of the token contract, this is optional and can be null

tokenUnits[][].​token.​decimalsnumber

this is the decimals of the token. This is optional and only used for ERC20 tokens (Points)

tokenUnits[][].​token.​isActivebooleanrequired

This can be used to enable or disable the token

tokenUnits[][].​token.​isGallerybooleanrequired

This can be used to enable or disable the token for gallery

tokenUnits[][].​token.​typestringrequired

This is the underlying web3 native type of the token contract

Enum"ERC20""ERC1155""ERC721"
tokenUnits[][].​tokenMetadataIncrementalIdnumber or null

token metadata incremental id for the token unit, this is used to identify the specific token metadata that should be minted

tokenUnits[][].​amountnumberrequired

Token unit amount is the amount of tokens that the user will receive when aquiring the token unit

tokenUnits[][].​maxAmountnumber or null

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

]
businessEngagementsArray of objects(CampaignBusinessEngagementDTO)required
Array [
businessEngagements[][].​idstringrequired

id

businessEngagements[][].​shortDescriptionnumber or nullrequired

A short description of the business engagement with indications what to do etc

businessEngagements[][].​businessIdsArray of stringsrequired

Business IDs associated with this engagement. Use CampaignDTO.included.businesses for full entities.

businessEngagements[][].​campaignIdstringrequired

Campaign id

businessEngagements[][].​maxPerBusinessnumber or nullrequired

max per business, the maximum number of times a user can engage with the buisness in the campaign

businessEngagements[][].​maxPerDaynumber or nullrequired

max per day, the maximum number of times a user can engage with the buisness in the campaign per day

businessEngagements[][].​externalUrlstring or nullrequired

The external URL for the business engagement, e.g. a link to a website or app

businessEngagements[][].​businessesArray of arraysDeprecatedrequired

Businesses (DEPRECATED: use businessIds + CampaignDTO.included.businesses instead. Will be removed in Q2 2026)

Example: [{"id":"business-uuid-1"},{"id":"business-uuid-2"}]
]
triggerSourceIdsArray of arraysrequired

Trigger source IDs. Use to batch fetch or request via ?include=triggerSources

Example: ["trigger-uuid-1","trigger-uuid-2"]
includedobject or null

Included related entities. Only populated when include parameter is specified.

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": [ … ]
  }
}

Remove trigger source from campaign (Admin)

Request

Remove a trigger source assignment from a specific campaign. Admin-only operation.

Security
authJWT
Path
idstringrequired
triggerSourceIdstringrequired
curl -i -X DELETE \
  'https://docs.pers.ninja/_mock/swagger/campaigns/{id}/trigger-sources/{triggerSourceId}' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Trigger source removed from campaign successfully

Bodyapplication/json
idstringrequired

Campaign id

namestring or nullrequired

Campaign name

descriptionstring or nullrequired

Campaign description

beneficiaryAccountAddressstring or nullrequired

Campaign beneficiary account address

startDatestring or null(date-time)required

Campaign start date, default is the current date

endDatestring or null(date-time)required

Campaign end date

imageUrlstring or nullrequired

img url

externalUrlstring or nullrequired

Campaign url

isActivebooleanrequired

Campaign isActive

Default false
isTestnetboolean

Campaign isTestnet, this means that the campaign is running on testnet, not mainnet

Default false
createdAtstring(date-time)required

create date

Default "2026-03-12T10:57:54.230Z"
updatedAtstring or null(date-time)required

update date

Default null
ordernumberrequired

Campaign order

Default 1
tagsArray of stringsrequired

Campaign tags

Default []
countryCodeRestrictionsobject

Country code restrictions as an array of strings (e.g., ["NOT_ES", "FR"])

Example: ["NOT_ES","FR"]
triggerobject or nullrequired

Campaign trigger: what triggers the campaign, and what are the conditions for the trigger to be activated

trigger.​namestring

Campaign trigger name

trigger.​descriptionstring

Campaign trigger description

trigger.​maxPerDaynumber or null

DEPRECATED - use maxPerDayPerUser: Campaign trigger max per day

trigger.​maxPerDayPerUsernumber or null

Campaign trigger max per day per user

trigger.​maxPerUsernumber or null

Campaign trigger max per user

trigger.​minCooldownSecondsnumber or null

Campaign trigger min cooldown seconds

trigger.​maxGeoDistanceInMetersnumber or null

Campaign trigger max geo distance to Business in meters

trigger.​requiredUserInfostring or null

Campaign trigger required user info

trigger.​triggerTypestring

Campaign trigger type

Enum"CLAIM_BY_USER""CLAIM_BY_SYSTEM""CLAIM_BY_BUSINESS"
trigger.​maxMultipliernumber or null

Campaign trigger max multiplier

trigger.​completionThresholdnumber or null

Campaign trigger completion threshold. This indicates the number of completions required before the reward is granted

trigger.​maxTotalnumber or null

Campaign trigger max total completions across all users

trigger.​maxPerDayTotalnumber or null

Campaign trigger max total completions per day across all users

trigger.​maxPerSourcenumber or null

Maximum claims per trigger source for this campaign. Limits how many times each individual trigger source can be used.

trigger.​conditionsArray of objects(CampaignTriggerConditionDTO)

Campaign trigger conditions

trigger.​sourceLogicstring

Source logic type defining how multiple trigger sources combine to activate the flow

Default "any"
Value"any"
trigger.​idstringrequired

Campaign trigger id

tokenUnitsArray of objects(TokenUnitDTO)required
Array [
tokenUnits[][].​idstringrequired

Token unit id

tokenUnits[][].​tokenobjectrequired

TokenDTO object

tokenUnits[][].​token.​idstringrequired

Id of the token

tokenUnits[][].​token.​contractAddressstringrequired

Address of the token

tokenUnits[][].​token.​metadataArray of objects(TokenMetadataDTO)

Metadata of the token, this is optional and can be null in case of Point token

tokenUnits[][].​token.​abiobjectrequired

this is the abi of the contract, this is the interface of the contract to interact with it

tokenUnits[][].​token.​chainIdnumberrequired

this is the chain id of the chain where the token is deployed

tokenUnits[][].​token.​abiUrlobjectrequired

this is the url of the abi of the contract, to be used to fetch the abi of the contract

tokenUnits[][].​token.​namestring

this is the name of the token contract

tokenUnits[][].​token.​symbolstring

this is the symbol of the token contract, this is optional and can be null

tokenUnits[][].​token.​decimalsnumber

this is the decimals of the token. This is optional and only used for ERC20 tokens (Points)

tokenUnits[][].​token.​isActivebooleanrequired

This can be used to enable or disable the token

tokenUnits[][].​token.​isGallerybooleanrequired

This can be used to enable or disable the token for gallery

tokenUnits[][].​token.​typestringrequired

This is the underlying web3 native type of the token contract

Enum"ERC20""ERC1155""ERC721"
tokenUnits[][].​tokenMetadataIncrementalIdnumber or null

token metadata incremental id for the token unit, this is used to identify the specific token metadata that should be minted

tokenUnits[][].​amountnumberrequired

Token unit amount is the amount of tokens that the user will receive when aquiring the token unit

tokenUnits[][].​maxAmountnumber or null

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

]
businessEngagementsArray of objects(CampaignBusinessEngagementDTO)required
Array [
businessEngagements[][].​idstringrequired

id

businessEngagements[][].​shortDescriptionnumber or nullrequired

A short description of the business engagement with indications what to do etc

businessEngagements[][].​businessIdsArray of stringsrequired

Business IDs associated with this engagement. Use CampaignDTO.included.businesses for full entities.

businessEngagements[][].​campaignIdstringrequired

Campaign id

businessEngagements[][].​maxPerBusinessnumber or nullrequired

max per business, the maximum number of times a user can engage with the buisness in the campaign

businessEngagements[][].​maxPerDaynumber or nullrequired

max per day, the maximum number of times a user can engage with the buisness in the campaign per day

businessEngagements[][].​externalUrlstring or nullrequired

The external URL for the business engagement, e.g. a link to a website or app

businessEngagements[][].​businessesArray of arraysDeprecatedrequired

Businesses (DEPRECATED: use businessIds + CampaignDTO.included.businesses instead. Will be removed in Q2 2026)

Example: [{"id":"business-uuid-1"},{"id":"business-uuid-2"}]
]
triggerSourceIdsArray of arraysrequired

Trigger source IDs. Use to batch fetch or request via ?include=triggerSources

Example: ["trigger-uuid-1","trigger-uuid-2"]
includedobject or null

Included related entities. Only populated when include parameter is specified.

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": [ … ]
  }
}

Campaign Tags

Operations

Campaign Tokens

Operations

Campaign Triggers

Operations

Campaign Engagements

Operations

Campaign Claims

Operations

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