Skip to content

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

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

Execute redemption (Unified)

Request

Process redemption execution using role-based detection. Supports user, business, and admin redemption processing.

Security
projectKey or authJWT
Bodyapplication/jsonrequired
redemptionIdstringrequired

The redemption id

businessIdstring or nullrequired

The business id associated with the redemption, if applicable

curl -i -X POST \
  https://docs.pers.ninja/_mock/swagger/redemptions/redeems \
  -H 'Content-Type: application/json' \
  -H 'x-project-key: YOUR_API_KEY_HERE' \
  -d '{
    "redemptionId": "string",
    "businessId": "string"
  }'

Responses

Redemption executed successfully

Bodyapplication/json
redeemobjectrequired

The redemption redeem details that the user redeemed

redeem.​idstringrequired

The id of the redemption user redeem

redeem.​userIdstringrequired

The user id that is claiming the redemption

redeem.​redemptionIdstringrequired

The redemption that the user is redeeming

redeem.​userCountryCodestring or nullrequired

The country code of the user redeeming the redemption

redeem.​statusstringrequired

The status of the redemption redeem

Default "PENDING"
Enum"PENDING""PROCESSING""COMPLETED""FAILED"
redeem.​createdAtstring or null(date-time)required

The date and time when processing of the redemption redeem started

redeem.​updatedAtstring or null(date-time)required

The date and time when processing of the redemption redeem was last updated

redeem.​messagestring or nullrequired

Message regarding the redemption status (failure reason, success info, etc.)

redeem.​includedobject or null

Included related entities. Only populated when include parameter is specified. Contains redemption, user, business, and/or transactions entities based on requested relations.

senderTransactionobject or nullrequired

The sender transaction that resulted from the user redeeming the redemption, this is applicable for redemptions that involve sending tokens from the user to a specific address

senderTransaction.​transactionobjectrequired

Transaction details

senderTransaction.​transaction.​amountobjectrequired

Transaction amount

senderTransaction.​transaction.​idstringrequired

Transaction id

senderTransaction.​transaction.​tokenAddressstringrequired

Transaction token address

senderTransaction.​transaction.​contractTokenIdobject or nullrequired

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

senderTransaction.​transaction.​tokenTypeobjectrequired

Transaction token type

senderTransaction.​transaction.​senderAddressstringrequired

Sender address

senderTransaction.​transaction.​recipientAddressobjectrequired

Recipient address

senderTransaction.​transaction.​transactionHashobjectrequired

Transaction hash

senderTransaction.​transaction.​typestringrequired

Transaction type

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

Trigger process type

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

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

senderTransaction.​transaction.​statusstringrequired

Transaction status

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

create date

senderTransaction.​transaction.​updatedAtobjectrequired

update date

senderTransaction.​transaction.​tenantIdstringrequired

Tenant ID for multi-tenant isolation

senderTransaction.​transaction.​chainIdobjectrequired

Blockchain chain ID

senderTransaction.​transaction.​senderIdobject or nullrequired

Sender entity ID (polymorphic reference)

senderTransaction.​transaction.​senderOwnerTypestring or nullrequired

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

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

Recipient entity ID (polymorphic reference)

senderTransaction.​transaction.​recipientOwnerTypestring or nullrequired

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

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

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

senderTransaction.​transaction.​engagedBusinessIdobject or nullrequired

Business commercially involved in this transaction (for stats/reporting)

senderTransaction.​transaction.​authorizedSubmitterIdobject or nullrequired

Entity authorized to submit this transaction (for POS flow security)

senderTransaction.​transaction.​authorizedSubmitterTypestring or nullrequired

Type of entity authorized to submit (USER, BUSINESS, etc.)

Enum"user""business""tenant""system""external"
senderTransaction.​transaction.​includedobject or null

Included related entities. Only populated when include parameter is specified. Contains sender, recipient, and/or engaged business entities based on requested relations.

senderTransaction.​transactionStatusstringrequired

Current status of the transaction

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

Prepared transaction data ready for signing (if applicable)

senderTransaction.​actionableobject or nullrequired

Actionable details for the transaction, if applicable

senderTransaction.​actionable.​messageobject

User-friendly message describing the action

senderTransaction.​actionable.​actionUrlobject

URL to perform the action

senderTransaction.​actionable.​authTokenobject

Authentication token for the action

senderTransaction.​actionable.​actionTypestringrequired

Type of action to be performed

senderTransaction.​walletSigningStatusstringrequired

Current status of the wallet signing process

Response
application/json
{
  "redeem": {
    "id": "string",
    "userId": "string",
    "redemptionId": "string",
    "userCountryCode": "string",
    "status": "PENDING",
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z",
    "message": "string",
    "included": { … }
  },
  "senderTransaction": {
    "transaction": { … },
    "transactionStatus": "created",
    "signingData": {},
    "actionable": { … },
    "walletSigningStatus": "string"
  }
}

Get redemption redeems with advanced filtering

Request

Get redemption redeems with comprehensive filtering options:

  • redemptionId: Filter by specific redemption (optional)
  • userId: Filter by specific user ID (admin only)
  • businessId: Filter by specific business ID (admin only)
  • include: Optionally include related entities (redemption, user, business, transactions)

Access Control:

  • Users: See only their own redemptions
  • Business: See only redemptions associated with their business account
  • Admin: Can filter by any combination of parameters or see all redemptions

Security Notes:

  • Users cannot access userId or businessId parameters (automatically filtered)
  • Business accounts automatically filter to their own businessId regardless of parameter
  • Admin has full access to all filtering options

Use pagination parameters (page & limit) for optimal performance - critical for high-volume data. Legacy support: returns array without params (deprecated - will be removed in future).

Security
projectKey or authJWT
Query
redemptionIdstring

Filter by specific redemption ID

userIdstring

Filter by specific user ID (admin only)

businessIdstring

Filter by specific business ID (admin only)

includeArray of strings

Include related entities: redemption, user, business, transactions (comma-separated)

pagestring

Page number for pagination (1-based)

limitstring

Number of items per page

curl -i -X GET \
  'https://docs.pers.ninja/_mock/swagger/redemptions/redeems?redemptionId=string&userId=string&businessId=string&include=string&page=string&limit=string' \
  -H 'x-project-key: YOUR_API_KEY_HERE'

Responses

Redemption redeems retrieved successfully

Bodyapplication/jsonArray [
idstringrequired

The id of the redemption user redeem

userIdstringrequired

The user id that is claiming the redemption

redemptionIdstringrequired

The redemption that the user is redeeming

userCountryCodestring or nullrequired

The country code of the user redeeming the redemption

statusstringrequired

The status of the redemption redeem

Default "PENDING"
Enum"PENDING""PROCESSING""COMPLETED""FAILED"
createdAtstring or null(date-time)required

The date and time when processing of the redemption redeem started

updatedAtstring or null(date-time)required

The date and time when processing of the redemption redeem was last updated

messagestring or nullrequired

Message regarding the redemption status (failure reason, success info, etc.)

includedobject or null

Included related entities. Only populated when include parameter is specified. Contains redemption, user, business, and/or transactions entities based on requested relations.

]
Response
application/json
[
  {
    "id": "string",
    "userId": "string",
    "redemptionId": "string",
    "userCountryCode": "string",
    "status": "PENDING",
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z",
    "message": "string",
    "included": { … }
  }
]

Get my redemption redeems (Convenience)

Request

Convenience endpoint for authenticated users to retrieve their own redemption redeems.

Equivalent to GET /redemption-redeems but with required authentication and automatic filtering to current user context.

Features:

  • Automatic user context (no userId parameter needed)
  • Optional redemption filtering
  • Requires user authentication
  • Simplified response structure
  • Optional entity inclusion (redemption, user, business, transactions)
  • Use pagination parameters (page & limit) for optimal performance - recommended for active users
  • Legacy support: returns array without params (deprecated - will be removed in future)

Usage Examples:

  • GET /redemption-redeems/me (all redemptions for authenticated user)
  • GET /redemption-redeems/me?redemptionId=123 (specific user redemption)
  • GET /redemption-redeems/me?page=1&limit=10 (paginated results)
  • GET /redemption-redeems/me?include=redemption,user (with related entities)
  • GET /redemption-redeems/me?include=redemption,transactions (with transactions)
Security
authJWT
Query
redemptionIdstring

Filter by specific redemption ID

includeArray of strings

Include related entities: redemption, user, business, transactions (comma-separated)

pagestring

Page number for pagination (1-based)

limitstring

Number of items per page

curl -i -X GET \
  'https://docs.pers.ninja/_mock/swagger/redemptions/redeems/me?redemptionId=string&include=string&page=string&limit=string' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

User redemption redeems retrieved successfully

Bodyapplication/jsonArray [
idstringrequired

The id of the redemption user redeem

userIdstringrequired

The user id that is claiming the redemption

redemptionIdstringrequired

The redemption that the user is redeeming

userCountryCodestring or nullrequired

The country code of the user redeeming the redemption

statusstringrequired

The status of the redemption redeem

Default "PENDING"
Enum"PENDING""PROCESSING""COMPLETED""FAILED"
createdAtstring or null(date-time)required

The date and time when processing of the redemption redeem started

updatedAtstring or null(date-time)required

The date and time when processing of the redemption redeem was last updated

messagestring or nullrequired

Message regarding the redemption status (failure reason, success info, etc.)

includedobject or null

Included related entities. Only populated when include parameter is specified. Contains redemption, user, business, and/or transactions entities based on requested relations.

]
Response
application/json
[
  {
    "id": "string",
    "userId": "string",
    "redemptionId": "string",
    "userCountryCode": "string",
    "status": "PENDING",
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z",
    "message": "string",
    "included": { … }
  }
]

Get specific redemption redeem

Request

Get current status of a specific redemption redeem with automatic access control based on authentication context. Optionally include related entities (redemption, user, business, transactions).

Security
projectKey or authJWT
Path
redeemIdstringrequired
Query
includeArray of strings

Include related entities: redemption, user, business, transactions (comma-separated)

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

Responses

Redemption redeem retrieved successfully

Bodyapplication/json
idstringrequired

The id of the redemption user redeem

userIdstringrequired

The user id that is claiming the redemption

redemptionIdstringrequired

The redemption that the user is redeeming

userCountryCodestring or nullrequired

The country code of the user redeeming the redemption

statusstringrequired

The status of the redemption redeem

Default "PENDING"
Enum"PENDING""PROCESSING""COMPLETED""FAILED"
createdAtstring or null(date-time)required

The date and time when processing of the redemption redeem started

updatedAtstring or null(date-time)required

The date and time when processing of the redemption redeem was last updated

messagestring or nullrequired

Message regarding the redemption status (failure reason, success info, etc.)

includedobject or null

Included related entities. Only populated when include parameter is specified. Contains redemption, user, business, and/or transactions entities based on requested relations.

Response
application/json
{
  "id": "string",
  "userId": "string",
  "redemptionId": "string",
  "userCountryCode": "string",
  "status": "PENDING",
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z",
  "message": "string",
  "included": {
    "redemption": { … },
    "user": { … },
    "business": { … },
    "transactions": [ … ]
  }
}

Redemption Tokens

Operations

API Keys

Operations