Skip to content
/
Get current user/business...

PERS-api Documentation (2.0.12)

PERS API Documentation

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

Usage Guidelines:

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

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

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

Tenants

Operations

Admins

Operations

Tokens

Operations

Campaigns

Operations

Campaign Tags

Operations

Campaign Tokens

Operations

Campaign Triggers

Operations

Campaign Engagements

Operations

Campaign Claims

Operations

Redemptions

Operations

Purchases

Operations

Businesses

Operations

Transactions

Operations

Transaction Management System

Comprehensive transaction management for credits and tokens with secure processing and real-time balance updates. Handles all operations within the loyalty platform.
Transaction Operations:

•
Token Minting:
Create new tokens and add to user accounts

•
Token Transfers:
Secure peer-to-peer token transfers between users

•
Token Burning:
Remove tokens from circulation with proper audit trails

•
Balance Queries:
Real-time balance checks across multiple token types

•
Transaction Authorization:
Verify user permissions and sufficient balances

•
Transaction History:
Complete audit logs for all operations

Get current user/business transactions

Request

Consolidated endpoint for user/business transactions. Use role parameter to filter: SENDER (sent), RECIPIENT (received), or omit for all transactions. Supports full pagination and filtering.

Security
authJWT
Query
searchstring

Wildcard search for ID, address or transaction hash

participantAddressstring

Filter by specific wallet address (must belong to authentication context for non-admins)

tokenAddressstring
pagenumber

Page number (1-based)

limitnumber

Items per page

sortBystring

Sort field

sortOrderstring

Sort order

Enum"ASC""DESC"
dateFromstring

Filter items created after this date (ISO 8601)

dateTostring

Filter items created before this date (ISO 8601)

typeArray of strings
Items Enum"MINT""TRANSFER""BURN"
tokenTypeArray of objects
statusArray of strings
Items Enum"created""processing""pending_signature""broadcasted""succeeded""failed""cancelled""expired"
roleArray of strings

Filter by transaction role: SENDER, RECIPIENT, or omit for all

Items Enum"SENDER""RECIPIENT"
curl -i -X GET \
  'https://docs.pers.ninja/_mock/swagger/transactions/me?search=string&participantAddress=string&tokenAddress=string&page=0&limit=0&sortBy=string&sortOrder=ASC&dateFrom=string&dateTo=string&type=MINT&status=created&role=SENDER' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Get all transactions with advanced filtering

Request

Get transactions with comprehensive filtering options: - search: Wildcard search for ID, address or transaction hash - participantId: Filter by user/business/tenant ID - role: Filter by SENDER, RECIPIENT, or both (omit for all) - status: Filter by transaction status - tokenType: Filter by token type - type: Filter by transaction type (MINT, BURN, TRANSFER) - Standard pagination parameters supported

Security
authJWT
Query
searchstring

Wildcard search for ID, address or transaction hash

participantIdstring
participantAddressstring
tokenAddressstring
pagenumber

Page number (1-based)

limitnumber

Items per page

sortBystring

Sort field

sortOrderstring

Sort order

Enum"ASC""DESC"
dateFromstring

Filter items created after this date (ISO 8601)

dateTostring

Filter items created before this date (ISO 8601)

typeArray of strings
Items Enum"MINT""TRANSFER""BURN"
tokenTypeArray of objects
statusArray of strings
Items Enum"created""processing""pending_signature""broadcasted""succeeded""failed""cancelled""expired"
roleArray of strings
Items Enum"SENDER""RECIPIENT"
curl -i -X GET \
  'https://docs.pers.ninja/_mock/swagger/transactions?search=string&participantId=string&participantAddress=string&tokenAddress=string&page=0&limit=0&sortBy=string&sortOrder=ASC&dateFrom=string&dateTo=string&type=MINT&status=created&role=SENDER' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Create transaction

Request

Create any type of transaction (MINT/TRANSFER/BURN) using role-based trigger detection. Sender will be determined based on the authentication context or provided explicitly (Pending verification). Depending on transaction type and signing context will either return a prepared transaction for client-side signing or execute server-side directly.

Security
authJWT
Bodyapplication/jsonrequired
web3TransactionTypestringrequired

Transaction type for easier detection and routing

Enum"MINT""TRANSFER""BURN"
Example: "TRANSFER"
senderobject

Transaction sender, will be resolved from auth context if not provided. if provided and different from auth user, signing capabilities will be checked or transaction will be rejected.

recipientobject

Transaction recipient (not required for BURN operations)

tokenobject

Token identification with multiple resolution strategies. If not provided, defaults to active credit token.

amountnumberrequired

Transaction amount

Example: 100
curl -i -X POST \
  https://docs.pers.ninja/_mock/swagger/transactions \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "web3TransactionType": "TRANSFER",
    "sender": {
      "accountId": "user123",
      "accountType": "user",
      "accountAddress": "0x742d35Cc5dB3dC0F0e8f0b0d2fA0c3fA2ed5D0f8"
    },
    "recipient": {
      "accountId": "user123",
      "accountType": "user",
      "accountAddress": "0x742d35Cc5dB3dC0F0e8f0b0d2fA0c3fA2ed5D0f8"
    },
    "token": {
      "tokenDbId": "uuid-12345-67890",
      "contractAddress": "0x742d35Cc5dB3dC0F0e8f0b0d2fA0c3fA2ed5D0f8",
      "contractTokenId": "721",
      "chainId": 1
    },
    "amount": 100
  }'

Responses

transaction created

Bodyapplication/json
transactionobjectrequired

Transaction details

transaction.​amountnumberrequired

Transaction amount

transaction.​idstringrequired

Transaction id

transaction.​tokenAddressstringrequired

Transaction token address

transaction.​contractTokenIdobject or nullrequired

Transaction token contract id, this is the blockchain contract id of the token

transaction.​tokenTypestringrequired

Transaction token type

transaction.​senderAddressstringrequired

Sender address

transaction.​recipientAddressobjectrequired

Recipient address

transaction.​transactionHashobjectrequired

Transaction hash

transaction.​typestringrequired

Transaction type

Enum"MINT""TRANSFER""BURN"
transaction.​triggerProcessTypestringrequired

Trigger process type

Enum"PURCHASE""SPEND""TRANSFER""EARN""CAMPAIGN_USER_CLAIM""CAMPAIGN_SYSTEM_CLAIM""CAMPAIGN_BUSINESS_CLAIM""REDEMPTION_SPEND""REDEMPTION_RECEIVE""MIGRATION"
transaction.​triggerProcessIdobjectrequired

Trigger process id, this is the id of the entity that triggered the transaction if applicable (e.g. CampaignUserClaim id)

transaction.​statusstringrequired

Transaction status

Enum"created""processing""pending_signature""broadcasted""succeeded""failed""cancelled""expired"
transaction.​createdAtobjectrequired

create date

transaction.​updatedAtobjectrequired

update date

transaction.​tenantIdstringrequired

Tenant ID for multi-tenant isolation

transaction.​chainIdnumberrequired

Blockchain chain ID

transaction.​senderIdobject or nullrequired

Sender entity ID (polymorphic reference)

transaction.​senderOwnerTypestring or nullrequired

Sender entity type (user, business, system etc.)

Enum"user""business""tenant""system""external"
transaction.​recipientIdobject or nullrequired

Recipient entity ID (polymorphic reference)

transaction.​recipientOwnerTypestring or nullrequired

Recipient entity type (user, Business, system, etc.)

Enum"user""business""tenant""system""external"
transaction.​messageobject or nullrequired

Optional message associated with the transaction, e.g. for error details

transactionStatusstringrequired

Current status of the transaction

Enum"created""processing""pending_signature""broadcasted""succeeded""failed""cancelled""expired"
signingDataobject or nullrequired

Prepared transaction data ready for signing (if applicable)

actionableobject or nullrequired

Actionable details for the transaction, if applicable

actionable.​messageobject

User-friendly message describing the action

actionable.​actionUrlobject

URL to perform the action

actionable.​authTokenobject

Authentication token for the action

actionable.​actionTypestringrequired

Type of action to be performed

walletSigningStatusstringrequired

Current status of the wallet signing process

Response
application/json
{
  "transaction": {
    "amount": 0,
    "id": "string",
    "tokenAddress": "string",
    "contractTokenId": {},
    "tokenType": "string",
    "senderAddress": "string",
    "recipientAddress": {},
    "transactionHash": {},
    "type": "MINT",
    "triggerProcessType": "PURCHASE",
    "triggerProcessId": {},
    "status": "created",
    "createdAt": {},
    "updatedAt": {},
    "tenantId": "string",
    "chainId": 0,
    "senderId": {},
    "senderOwnerType": "user",
    "recipientId": {},
    "recipientOwnerType": "user",
    "message": {}
  },
  "transactionStatus": "created",
  "signingData": {},
  "actionable": {
    "message": {},
    "actionUrl": {},
    "authToken": {},
    "actionType": "string"
  },
  "walletSigningStatus": "string"
}

Get transaction by ID

Request

Get single transaction by ID. Requires valid project API key.

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

Responses

Transaction found

Bodyapplication/json
amountnumberrequired

Transaction amount

idstringrequired

Transaction id

tokenAddressstringrequired

Transaction token address

contractTokenIdobject or nullrequired

Transaction token contract id, this is the blockchain contract id of the token

tokenTypestringrequired

Transaction token type

senderAddressstringrequired

Sender address

recipientAddressobjectrequired

Recipient address

transactionHashobjectrequired

Transaction hash

typestringrequired

Transaction type

Enum"MINT""TRANSFER""BURN"
triggerProcessTypestringrequired

Trigger process type

Enum"PURCHASE""SPEND""TRANSFER""EARN""CAMPAIGN_USER_CLAIM""CAMPAIGN_SYSTEM_CLAIM""CAMPAIGN_BUSINESS_CLAIM""REDEMPTION_SPEND""REDEMPTION_RECEIVE""MIGRATION"
triggerProcessIdobjectrequired

Trigger process id, this is the id of the entity that triggered the transaction if applicable (e.g. CampaignUserClaim id)

statusstringrequired

Transaction status

Enum"created""processing""pending_signature""broadcasted""succeeded""failed""cancelled""expired"
createdAtobjectrequired

create date

updatedAtobjectrequired

update date

tenantIdstringrequired

Tenant ID for multi-tenant isolation

chainIdnumberrequired

Blockchain chain ID

senderIdobject or nullrequired

Sender entity ID (polymorphic reference)

senderOwnerTypestring or nullrequired

Sender entity type (user, business, system etc.)

Enum"user""business""tenant""system""external"
recipientIdobject or nullrequired

Recipient entity ID (polymorphic reference)

recipientOwnerTypestring or nullrequired

Recipient entity type (user, Business, system, etc.)

Enum"user""business""tenant""system""external"
messageobject or nullrequired

Optional message associated with the transaction, e.g. for error details

Response
application/json
{
  "amount": 0,
  "id": "string",
  "tokenAddress": "string",
  "contractTokenId": {},
  "tokenType": "string",
  "senderAddress": "string",
  "recipientAddress": {},
  "transactionHash": {},
  "type": "MINT",
  "triggerProcessType": "PURCHASE",
  "triggerProcessId": {},
  "status": "created",
  "createdAt": {},
  "updatedAt": {},
  "tenantId": "string",
  "chainId": 0,
  "senderId": {},
  "senderOwnerType": "user",
  "recipientId": {},
  "recipientOwnerType": "user",
  "message": {}
}

Prepare existing transaction for client-side signing

Request

Prepares transaction data for client-side execution from existing transaction ID. Returns the data needed for the client to sign and submit the transaction.

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

Responses

Transaction prepared successfully

Bodyapplication/json
transactionobjectrequired

Transaction details

transaction.​amountnumberrequired

Transaction amount

transaction.​idstringrequired

Transaction id

transaction.​tokenAddressstringrequired

Transaction token address

transaction.​contractTokenIdobject or nullrequired

Transaction token contract id, this is the blockchain contract id of the token

transaction.​tokenTypestringrequired

Transaction token type

transaction.​senderAddressstringrequired

Sender address

transaction.​recipientAddressobjectrequired

Recipient address

transaction.​transactionHashobjectrequired

Transaction hash

transaction.​typestringrequired

Transaction type

Enum"MINT""TRANSFER""BURN"
transaction.​triggerProcessTypestringrequired

Trigger process type

Enum"PURCHASE""SPEND""TRANSFER""EARN""CAMPAIGN_USER_CLAIM""CAMPAIGN_SYSTEM_CLAIM""CAMPAIGN_BUSINESS_CLAIM""REDEMPTION_SPEND""REDEMPTION_RECEIVE""MIGRATION"
transaction.​triggerProcessIdobjectrequired

Trigger process id, this is the id of the entity that triggered the transaction if applicable (e.g. CampaignUserClaim id)

transaction.​statusstringrequired

Transaction status

Enum"created""processing""pending_signature""broadcasted""succeeded""failed""cancelled""expired"
transaction.​createdAtobjectrequired

create date

transaction.​updatedAtobjectrequired

update date

transaction.​tenantIdstringrequired

Tenant ID for multi-tenant isolation

transaction.​chainIdnumberrequired

Blockchain chain ID

transaction.​senderIdobject or nullrequired

Sender entity ID (polymorphic reference)

transaction.​senderOwnerTypestring or nullrequired

Sender entity type (user, business, system etc.)

Enum"user""business""tenant""system""external"
transaction.​recipientIdobject or nullrequired

Recipient entity ID (polymorphic reference)

transaction.​recipientOwnerTypestring or nullrequired

Recipient entity type (user, Business, system, etc.)

Enum"user""business""tenant""system""external"
transaction.​messageobject or nullrequired

Optional message associated with the transaction, e.g. for error details

transactionStatusstringrequired

Current status of the transaction

Enum"created""processing""pending_signature""broadcasted""succeeded""failed""cancelled""expired"
signingDataobject or nullrequired

Prepared transaction data ready for signing (if applicable)

actionableobject or nullrequired

Actionable details for the transaction, if applicable

actionable.​messageobject

User-friendly message describing the action

actionable.​actionUrlobject

URL to perform the action

actionable.​authTokenobject

Authentication token for the action

actionable.​actionTypestringrequired

Type of action to be performed

walletSigningStatusstringrequired

Current status of the wallet signing process

Response
application/json
{
  "transaction": {
    "amount": 0,
    "id": "string",
    "tokenAddress": "string",
    "contractTokenId": {},
    "tokenType": "string",
    "senderAddress": "string",
    "recipientAddress": {},
    "transactionHash": {},
    "type": "MINT",
    "triggerProcessType": "PURCHASE",
    "triggerProcessId": {},
    "status": "created",
    "createdAt": {},
    "updatedAt": {},
    "tenantId": "string",
    "chainId": 0,
    "senderId": {},
    "senderOwnerType": "user",
    "recipientId": {},
    "recipientOwnerType": "user",
    "message": {}
  },
  "transactionStatus": "created",
  "signingData": {},
  "actionable": {
    "message": {},
    "actionUrl": {},
    "authToken": {},
    "actionType": "string"
  },
  "walletSigningStatus": "string"
}

Submit client-side signed transaction

Request

Submits a signed transaction from the client. This method is used to finalize the transaction after the client has signed it.

Security
authJWT
Bodyapplication/jsonrequired
transactionIdstringrequired

Transaction ID, this is the transaction hash or identifier

typestringrequired

Transaction format type for submission

Enum"legacy""EIP-2930""EIP-1559""EIP-712"
Example: "legacy"
signaturestring

EIP-712 structured data for smart wallet meta-transactions (required when type is EIP-712)

Example: "0x1234567890abcdef..."
signedTransactionstring

Pre-signed blockchain transaction in RLP encoded hex format (required for legacy, EIP-2930, EIP-1559)

Example: "0xf86c0a8255f0..."
curl -i -X POST \
  https://docs.pers.ninja/_mock/swagger/transactions/submit \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "transactionId": "string",
    "type": "legacy",
    "signature": "0x1234567890abcdef...",
    "signedTransaction": "0xf86c0a8255f0..."
  }'

Responses

Transaction submitted successfully

Bodyapplication/json
transactionobjectrequired

Transaction details

transaction.​amountnumberrequired

Transaction amount

transaction.​idstringrequired

Transaction id

transaction.​tokenAddressstringrequired

Transaction token address

transaction.​contractTokenIdobject or nullrequired

Transaction token contract id, this is the blockchain contract id of the token

transaction.​tokenTypestringrequired

Transaction token type

transaction.​senderAddressstringrequired

Sender address

transaction.​recipientAddressobjectrequired

Recipient address

transaction.​transactionHashobjectrequired

Transaction hash

transaction.​typestringrequired

Transaction type

Enum"MINT""TRANSFER""BURN"
transaction.​triggerProcessTypestringrequired

Trigger process type

Enum"PURCHASE""SPEND""TRANSFER""EARN""CAMPAIGN_USER_CLAIM""CAMPAIGN_SYSTEM_CLAIM""CAMPAIGN_BUSINESS_CLAIM""REDEMPTION_SPEND""REDEMPTION_RECEIVE""MIGRATION"
transaction.​triggerProcessIdobjectrequired

Trigger process id, this is the id of the entity that triggered the transaction if applicable (e.g. CampaignUserClaim id)

transaction.​statusstringrequired

Transaction status

Enum"created""processing""pending_signature""broadcasted""succeeded""failed""cancelled""expired"
transaction.​createdAtobjectrequired

create date

transaction.​updatedAtobjectrequired

update date

transaction.​tenantIdstringrequired

Tenant ID for multi-tenant isolation

transaction.​chainIdnumberrequired

Blockchain chain ID

transaction.​senderIdobject or nullrequired

Sender entity ID (polymorphic reference)

transaction.​senderOwnerTypestring or nullrequired

Sender entity type (user, business, system etc.)

Enum"user""business""tenant""system""external"
transaction.​recipientIdobject or nullrequired

Recipient entity ID (polymorphic reference)

transaction.​recipientOwnerTypestring or nullrequired

Recipient entity type (user, Business, system, etc.)

Enum"user""business""tenant""system""external"
transaction.​messageobject or nullrequired

Optional message associated with the transaction, e.g. for error details

transactionStatusstringrequired

Current status of the transaction

Enum"created""processing""pending_signature""broadcasted""succeeded""failed""cancelled""expired"
signingDataobject or nullrequired

Prepared transaction data ready for signing (if applicable)

actionableobject or nullrequired

Actionable details for the transaction, if applicable

actionable.​messageobject

User-friendly message describing the action

actionable.​actionUrlobject

URL to perform the action

actionable.​authTokenobject

Authentication token for the action

actionable.​actionTypestringrequired

Type of action to be performed

walletSigningStatusstringrequired

Current status of the wallet signing process

Response
application/json
{
  "transaction": {
    "amount": 0,
    "id": "string",
    "tokenAddress": "string",
    "contractTokenId": {},
    "tokenType": "string",
    "senderAddress": "string",
    "recipientAddress": {},
    "transactionHash": {},
    "type": "MINT",
    "triggerProcessType": "PURCHASE",
    "triggerProcessId": {},
    "status": "created",
    "createdAt": {},
    "updatedAt": {},
    "tenantId": "string",
    "chainId": 0,
    "senderId": {},
    "senderOwnerType": "user",
    "recipientId": {},
    "recipientOwnerType": "user",
    "message": {}
  },
  "transactionStatus": "created",
  "signingData": {},
  "actionable": {
    "message": {},
    "actionUrl": {},
    "authToken": {},
    "actionType": "string"
  },
  "walletSigningStatus": "string"
}

Export all transactions as CSV

Request

Downloads all transactions as a CSV file. RLS ensures tenant isolation automatically. File includes all transaction data formatted for business analysis.

Security
authJWT
curl -i -X GET \
  https://docs.pers.ninja/_mock/swagger/transactions/export/csv \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

CSV file download

Headers
Content-Typestring

MIME type of the file

Example: "text/csv"
Content-Dispositionstring

File download attachment

Example: "attachment; filename=\"transactions_2024-01-15.csv\""
Bodyapplication/json
string(binary)
Response
application/json
"string"

Get transaction analytics

Request

Get transaction analytics with dynamic filtering, grouping, and metrics. Optimized for dashboard modules: stamps count, rewards analysis, top users, etc. RLS ensures tenant isolation automatically.

Security
authJWT
Bodyapplication/jsonrequired

Analytics configuration with filters, grouping, and metrics

filtersobject

Dynamic filters based on TransactionDTO fields - all transaction fields available

Example: {"status":"SUCCEEDED","tokenType":"STAMP","triggerProcessType":"MINT","tenantId":"tenant-123","chainId":1}
groupByArray of strings

Fields to group by - any TransactionDTO field plus computed time fields

Example: ["tokenType","month","status","chainId"]
groupByExpressionsArray of objects(GroupByExpressionDTO)

Complex CASE WHEN expressions for advanced grouping scenarios

Example: [{"expression":"CASE WHEN senderOwnerType = user THEN senderId WHEN recipientOwnerType = user THEN recipientId END","alias":"userId","label":"User ID"}]
metricsstring

Metrics to calculate

Enum"count""sum""avg""min""max"
Example: ["count"]
sortBystring or any

Field to order results by (supports expression aliases)

Example: "count"
One of:

Field to order results by (supports expression aliases)

string
sortOrderstring

Order direction

Enum"ASC""DESC"
Example: "DESC"
limitnumber[ 1 .. 100 ]

Maximum number of results to return

Example: 10
startDatestring(date-time)

Start date for analytics (ISO format)

Example: "2024-01-01T00:00:00.000Z"
endDatestring(date-time)

End date for analytics (ISO format)

Example: "2024-12-31T23:59:59.999Z"
curl -i -X POST \
  https://docs.pers.ninja/_mock/swagger/transactions/analytics \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "filters": {
      "status": "SUCCEEDED",
      "tokenType": "STAMP"
    },
    "groupBy": [
      "month"
    ],
    "metrics": [
      "count"
    ],
    "sortBy": "count",
    "sortOrder": "DESC",
    "limit": 12
  }'

Responses

Analytics results retrieved successfully

Bodyapplication/json
resultsArray of arraysrequired

Analytics results array with dynamic fields and expression aliases

Example: [{"userId":"user-123","count":45},{"userAddress":"0xabc...def","count":32},{"tokenType":"STAMP","count":150,"month":"2024-01-01T00:00:00.000Z"}]
totalGroupsnumberrequired

Total number of result groups

Example: 3
metadataobjectrequired

Query execution metadata

Example: {"executionTime":"45ms"}
Response
application/json
{
  "results": [
    { … },
    { … },
    { … }
  ],
  "totalGroups": 3,
  "metadata": {
    "executionTime": "45ms"
  }
}

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