Campaign Claims

BUSINESS CRITICAL: Multi-level reward claim processing with comprehensive fraud prevention and audit trails. Handles actual reward distribution with full financial security and compliance features.

**Critical Security Features:**

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

• **Fraud Prevention:** IP tracking and behavioral analysis for security

• **Audit Compliance:** Complete transaction history for regulatory requirements

• **Financial Attribution:** User and business context preservation for accounting

• **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

System claim reward (Critical Financial)

Request

Process automated reward claims via system API. BUSINESS CRITICAL - handles real financial transactions. Requires valid tenant system API key. Replaces POST /campaign/system/claim

Security

projectKey and businessApiKey

Bodyapplication/jsonrequired

campaignIdstringrequired

The campaign id

conditionsDataobject

The campaign condition data

multipliernumber

The campaign multiplier that will be applied to the reward. Default is 1.0

businessIdstring

Business identifier

latitudenumber

geolocation latitude

longitudenumber

geolocation longitude

userIdentifierstring

The user identifier

startDatestring(date-time)

The start date of the claim

endDatestring(date-time)

The end date of the claim

idstring

The id of the user

emailstring

The email of the user

instagramAccountIdstring

The instagramAccountId of the user

externalIdstring

The externalId of the user

curl -i -X POST \
  https://docs.pers.ninja/_mock/swagger/campaign-claims/system \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -H 'x-project-key: YOUR_API_KEY_HERE' \
  -d '{
    "campaignId": "string",
    "conditionsData": {},
    "multiplier": 0,
    "businessId": "string",
    "latitude": 0,
    "longitude": 0,
    "userIdentifier": "string",
    "startDate": "2019-08-24T14:15:22Z",
    "endDate": "2019-08-24T14:15:22Z",
    "id": "string",
    "email": "string",
    "instagramAccountId": "string",
    "externalId": "string"
  }'

Responses

System reward claim processed successfully

Bodyapplication/json

idstringrequired

The id of the campaign user claim

createdAtobjectrequired

The date the campaign user claim was created

userobjectrequired

user.idstringrequired

user.emailobject

user.firstNameobject or nullrequired

User first name

user.lastNameobject or nullrequired

User last name

user.externalIdobject or nullrequired

User external id

user.instagramAccountIdobject or nullrequired

Instagram account id

user.googleAccountNameobject or nullrequired

Google account name

user.customDataobjectrequired

Custom data

user.publicProfileobject or nullrequired

Public profile data

user.isActivebooleanrequired

Is active

user.currentSigningAccountIdobject

Current active signing account ID for external wallet operations

user.walletsArray of objects(WalletDTO)required

User-owned counterfactual smart contract wallets that can receive tokens

user.wallets[].idstringrequired

Unique identifier for the internal wallet

user.wallets[].ownerTypenumberrequired

Owner type for polymorphic ownership

Value{"USER":"user","BUSINESS":"business","TENANT":"tenant","SYSTEM":"system","EXTERNAL":"external"}

Example: "user"

user.wallets[].ownerIdstringrequired

Owner ID for polymorphic ownership

Example: "user_123"

user.wallets[].walletManagementTypenumberrequired

Type of internal wallet

Value{"CUSTODIAL":"custodial","NON_CUSTODIAL":"non-custodial"}

user.wallets[].addressstringrequired

CREATE2 generated address that can receive tokens

user.wallets[].chainIdnumberrequired

Blockchain network chain identifier

user.wallets[].statusnumberrequired

Current status of the wallet

Value{"PENDING":"pending","ACTIVE":"active","SUSPENDED":"suspended","ARCHIVED":"archived"}

user.wallets[].saltstringrequired

CREATE2 salt used for deterministic address generation

user.wallets[].ownerSigningAccountIdobject or null

ID of signing account that owns this internal wallet

user.wallets[].tagsArray of stringsrequired

Tags associated with the wallet for categorization

user.wallets[].createdAtstring(date-time)required

Timestamp when the wallet was created

user.wallets[].updatedAtstring(date-time)required

Timestamp when the wallet was last updated

user.accountAddressobject or nullDeprecatedrequired

User account address

campaignobjectrequired

campaign.namestring or nullrequired

Campaign name

campaign.descriptionstring or nullrequired

Campaign description

campaign.beneficiaryAccountAddressstring or nullrequired

Campaign beneficiary account address

campaign.startDatestring or null(date-time)required

Campaign start date, default is the current date

campaign.endDatestring or null(date-time)required

Campaign end date

campaign.imageUrlstring or nullrequired

img url

campaign.externalUrlstring or nullrequired

Campaign url

campaign.idstringrequired

Campaign id

campaign.isActivebooleanrequired

Campaign isActive

Default false

campaign.isTestnetboolean

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

Default false

campaign.triggerobject or nullrequired

campaign.trigger.namestringrequired

Campaign trigger name

campaign.trigger.descriptionstring

Campaign trigger description

campaign.trigger.maxPerDaynumber or null

Campaign trigger max per day

campaign.trigger.maxPerUsernumber or null

Campaign trigger max per user

campaign.trigger.minCooldownSecondsnumber or null

Campaign trigger min cooldown seconds

campaign.trigger.maxGeoDistanceInMetersnumber or null

Campaign trigger max geo distance to Business in meters

campaign.trigger.requiredUserInfostring

Campaign trigger required user info

Enum"id""email""instagramAccountId""externalId""firstName""lastName""accountAddress""publicProfile""customData""isActive"

campaign.trigger.triggerTypestring

Campaign trigger type

Enum"CLAIM_BY_USER""CLAIM_BY_SYSTEM""CLAIM_BY_BUSINESS"

campaign.trigger.maxMultipliernumber or null

Campaign trigger max multiplier

campaign.trigger.completionThresholdnumber or null

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

campaign.trigger.idstringrequired

Campaign trigger id

campaign.trigger.conditionsArray of objects(CampaignTriggerConditionDTO)required

Campaign trigger conditions

campaign.trigger.conditions[].conditionTypestringrequired

Trigger condition type

Enum"EQUALS""NOT_EQUALS""GREATER_THAN""LESS_THAN""CONTAINS""IS_PART_OF"

campaign.trigger.conditions[].valueobjectrequired

Trigger condition value

campaign.trigger.conditions[].keystringrequired

Trigger condition key

campaign.trigger.conditions[].idstringrequired

campaign.tokenUnitsArray of objects(TokenUnitDTO)required

Array [

campaign.tokenUnits[][].idstringrequired

Token unit id

campaign.tokenUnits[][].tokenobjectrequired

campaign.tokenUnits[][].token.idstringrequired

Id of the token

campaign.tokenUnits[][].token.contractAddressstringrequired

Address of the token

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

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

campaign.tokenUnits[][].token.abiobjectrequired

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

campaign.tokenUnits[][].token.chainIdnumberrequired

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

campaign.tokenUnits[][].token.abiUrlobjectrequired

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

campaign.tokenUnits[][].token.namestring

this is the name of the token contract

campaign.tokenUnits[][].token.symbolstring

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

campaign.tokenUnits[][].token.decimalsnumber

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

campaign.tokenUnits[][].token.isActivebooleanrequired

This can be used to enable or disable the token

campaign.tokenUnits[][].token.isGallerybooleanrequired

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

campaign.tokenUnits[][].token.typestringrequired

This is the underlying web3 native type of the token contract

Enum"ERC20""ERC1155""ERC721"

campaign.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

campaign.tokenUnits[][].amountnumberrequired

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

campaign.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

]

campaign.businessEngagementsArray of objects(CampaignBusinessEngagementDTO)required

Campaign businesses: what businesses are involved in the campaign

campaign.businessEngagements[].idstringrequired

id

campaign.businessEngagements[].shortDescriptionnumber or nullrequired

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

campaign.businessEngagements[].businessesArray of objects(BusinessDTO)required

businesses

campaign.businessEngagements[].businesses[].idstringrequired

The id of the business, this is unique and will be used to identify the business.

campaign.businessEngagements[].businesses[].emailobject or nullrequired

The email of the business, this is unique and will be used to identify the business.

campaign.businessEngagements[].businesses[].accountAddressobject or nullrequired

The address of the business, this is the address that will be shown to the public.

campaign.businessEngagements[].businesses[].businessLegalNameobject or nullrequired

The legal name of the business, this is the name that will be used for legal purposes.

campaign.businessEngagements[].businesses[].displayNameobject or nullrequired

The display name of the business, this is the name that will be shown to the public.

campaign.businessEngagements[].businesses[].descriptionobject or nullrequired

The description of the business, this is the description that will be shown to the public.

campaign.businessEngagements[].businesses[].shortDescriptionobject or nullrequired

The short description of the business, this is the description that will be shown to the public.

campaign.businessEngagements[].businesses[].websiteUrlobject or nullrequired

The website of the business, this is the website that will be shown to the public.

campaign.businessEngagements[].businesses[].imageUrlobject or nullrequired

The image of the business, this is the image that will be shown to the public.

campaign.businessEngagements[].businesses[].streetAddressobject or nullrequired

The address of the business, this is the address that will be shown to the public.

campaign.businessEngagements[].businesses[].cityobject or nullrequired

The city of the business, this is the city that will be shown to the public.

campaign.businessEngagements[].businesses[].postalCodeobject or nullrequired

The postal code of the business, this is the postal code that will be shown to the public.

campaign.businessEngagements[].businesses[].coordsLatitudeobject or nullrequired

The latitude of the business, this is the latitude that will be shown to the public.

campaign.businessEngagements[].businesses[].coordsLongitudeobject or nullrequired

The longitude of the business, this is the longitude that will be shown to the public.

campaign.businessEngagements[].businesses[].businessTypeobject or nullrequired

campaign.businessEngagements[].businesses[].businessType.idnumber

Business type id

campaign.businessEngagements[].businesses[].businessType.namestring or nullrequired

Business type name

campaign.businessEngagements[].businesses[].businessType.descriptionstring or nullrequired

Business type description

campaign.businessEngagements[].businesses[].businessType.codestring or nullrequired

Business type code

campaign.businessEngagements[].businesses[].businessType.iconUrlstring or nullrequired

Business type icon url

campaign.businessEngagements[].businesses[].isActivebooleanrequired

The status of the business, this is the status that will be shown to the public.

campaign.businessEngagements[].businesses[].canMintTokenbooleanrequired

The ability to mint token for the business, this is the ability that will be shown to the public.

campaign.businessEngagements[].businesses[].canChargeTokenbooleanrequired

The ability to charge token for the business, this is the ability that will be shown to the public.

campaign.businessEngagements[].businesses[].canManageUsersbooleanrequired

The ability to manage users for the business, this is the ability that will be shown to the public.

campaign.businessEngagements[].businesses[].canReceiveDonationbooleanrequired

The ability to receive donation for the business, this is the ability that will be shown to the public.

campaign.businessEngagements[].campaignIdstringrequired

Campaign id

campaign.businessEngagements[].maxPerBusinessnumber or nullrequired

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

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

campaign.businessEngagements[].externalUrlstring or nullrequired

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

campaign.createdAtstring(date-time)required

create date

Default "2025-10-22T19:05:50.493Z"

campaign.updatedAtstring or null(date-time)required

update date

Default null

campaign.ordernumberrequired

Campaign order

Default 1

campaign.tagsArray of stringsrequired

Campaign tags

Default []

campaign.countryCodeRestrictionsobject

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

Example: ["NOT_ES","FR"]

userCountryCodestring or nullrequired

Country code of the user claiming the campaign

businessobject

Response

application/json

{
  "id": "string",
  "createdAt": {},
  "user": {
    "id": "string",
    "email": {},
    "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": "2025-10-22T19:05:50.493Z",
    "updatedAt": null,
    "order": 1,
    "tags": [],
    "countryCodeRestrictions": [ … ]
  },
  "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
  }
}

Business claim reward (Critical Financial)