Skip to content

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

Tenant Management

Tenant management for multi-tenant PERS loyalty platform. Each tenant represents a business or organization running their own reward program with dedicated data isolation and configuration.
Core Features:

•
Multi-Tenant Architecture:
Complete data isolation between tenant organizations

•
Tenant Configuration:
Custom settings, branding, and program rules per tenant

•
Admin Dashboard Access:
Comprehensive management interface for tenant administrators

•
Data Security:
Highest level confidentiality and security per tenant environment

•
API Integration:
Seamless integration with existing business systems

Create new tenant

Request

Create a new tenant (project) in the system. This is the initial setup step for new organizations.

Security
projectKey
Bodyapplication/jsonrequired
projectNamestringrequired
curl -i -X POST \
  https://docs.pers.ninja/_mock/swagger/tenants \
  -H 'Content-Type: application/json' \
  -H 'x-project-key: YOUR_API_KEY_HERE' \
  -d '{
    "projectName": "string"
  }'

Responses

Tenant created successfully

Bodyapplication/json
projectNamestringrequired

Name of the tenant.

acronymstringrequired

Acronym of the tenant.

idstringrequired

Unique identifier for tenant. This id is used to identify tenant in the system for client requests.

createdAtstring(date-time)required

Date when tenant was created.

projectDescriptionstring

Description of the tenant.

projectWebsitestring

Website of the tenant.

projectEmailstring

Email of the tenant.

projectImageUrlstring

Image URL of the tenant.

projectApiKeystringrequired

Unique identifier for tenant. This id is used to identify tenant in the system for client requests.

testnetProjectApiKeystringrequired

Testnet project API key for tenant. Used in case of testnet project.

stripeApiKeystring

Stripe API key for tenant. Used in case of stripe payment.

stripeWebhookSecretstring

Stripe webhook secret for tenant. Used in case of stripe payment.

loginTokenstring

This is an optional field for any extra login requirements for your users.

allowJWTForUnauthenticatedUsersbooleanrequired

This is an optional field for any extra login requirements for your users.

firebaseTenantIdstring
defaultWalletManagementTypestringrequired

Default wallet management type for tenant. This is used when creating a new wallet for the tenant. It can be either CUSTODIAL or NON_CUSTODIAL. CUSTODIAL means that the wallet is managed by the platform, while NON_CUSTODIAL means that the wallet is managed by the user.

Default "custodial"
Enum"custodial""non-custodial"
Response
application/json
{
  "projectName": "string",
  "acronym": "string",
  "id": "string",
  "createdAt": "2019-08-24T14:15:22Z",
  "projectDescription": "string",
  "projectWebsite": "string",
  "projectEmail": "string",
  "projectImageUrl": "string",
  "projectApiKey": "string",
  "testnetProjectApiKey": "string",
  "stripeApiKey": "string",
  "stripeWebhookSecret": "string",
  "loginToken": "string",
  "allowJWTForUnauthenticatedUsers": true,
  "firebaseTenantId": "string",
  "defaultWalletManagementType": "custodial"
}

Update tenant configuration

Request

ADMIN: Update tenant information and settings

Security
authJWT
Bodyapplication/jsonrequired
projectNamestring

The project name

Example: "My Project"
projectDescriptionstring

The project description

stripeApiKeystring
stripeWebhookSecretstring
stripePublishableKeystring
loginTokenstring
allowJWTForUnauthenticatedUsersboolean

This is an optional field for any extra login requirements for your users.

firebaseTenantIdstring
projectWebsitestring
projectEmailstring
projectImageUrlstring
curl -i -X PUT \
  https://docs.pers.ninja/_mock/swagger/tenants \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "projectName": "My Project",
    "projectDescription": "string",
    "stripeApiKey": "string",
    "stripeWebhookSecret": "string",
    "stripePublishableKey": "string",
    "loginToken": "string",
    "allowJWTForUnauthenticatedUsers": true,
    "firebaseTenantId": "string",
    "projectWebsite": "string",
    "projectEmail": "string",
    "projectImageUrl": "string"
  }'

Responses

Tenant updated successfully

Bodyapplication/json
projectNamestringrequired

Name of the tenant.

acronymstringrequired

Acronym of the tenant.

idstringrequired

Unique identifier for tenant. This id is used to identify tenant in the system for client requests.

createdAtstring(date-time)required

Date when tenant was created.

projectDescriptionstring

Description of the tenant.

projectWebsitestring

Website of the tenant.

projectEmailstring

Email of the tenant.

projectImageUrlstring

Image URL of the tenant.

projectApiKeystringrequired

Unique identifier for tenant. This id is used to identify tenant in the system for client requests.

testnetProjectApiKeystringrequired

Testnet project API key for tenant. Used in case of testnet project.

stripeApiKeystring

Stripe API key for tenant. Used in case of stripe payment.

stripeWebhookSecretstring

Stripe webhook secret for tenant. Used in case of stripe payment.

loginTokenstring

This is an optional field for any extra login requirements for your users.

allowJWTForUnauthenticatedUsersbooleanrequired

This is an optional field for any extra login requirements for your users.

firebaseTenantIdstring
defaultWalletManagementTypestringrequired

Default wallet management type for tenant. This is used when creating a new wallet for the tenant. It can be either CUSTODIAL or NON_CUSTODIAL. CUSTODIAL means that the wallet is managed by the platform, while NON_CUSTODIAL means that the wallet is managed by the user.

Default "custodial"
Enum"custodial""non-custodial"
Response
application/json
{
  "projectName": "string",
  "acronym": "string",
  "id": "string",
  "createdAt": "2019-08-24T14:15:22Z",
  "projectDescription": "string",
  "projectWebsite": "string",
  "projectEmail": "string",
  "projectImageUrl": "string",
  "projectApiKey": "string",
  "testnetProjectApiKey": "string",
  "stripeApiKey": "string",
  "stripeWebhookSecret": "string",
  "loginToken": "string",
  "allowJWTForUnauthenticatedUsers": true,
  "firebaseTenantId": "string",
  "defaultWalletManagementType": "custodial"
}

Get client configuration

Request

Retrieve client-side configuration for the project

Security
projectKey
curl -i -X GET \
  https://docs.pers.ninja/_mock/swagger/tenants/client-config \
  -H 'x-project-key: YOUR_API_KEY_HERE'

Responses

Client configuration retrieved successfully

Bodyapplication/json
projectNamestringrequired

The project name

Example: "My Project"
idstringrequired

The project id

Example: "ererf-erf-erf-erf"
stripePublishableKeystring

Stripe publishable key for tenant. Used in case of stripe payment.

firebaseTenantIdstring

Firebase tenant ID for tenant. This id is needed, if you choose to setup Firebase for user authentification for your project.

infuraApiKeystring

Infura API key for tenant. Used in for client interaction with web3 provider.

polyScanApiKeystring

PolyScan API key for tenant. Used in for client interaction with PolyScan.

clientIpLocationobject or null

Geolocation information derived from the client IP address

Response
application/json
{
  "projectName": "My Project",
  "id": "ererf-erf-erf-erf",
  "stripePublishableKey": "string",
  "firebaseTenantId": "string",
  "infuraApiKey": "string",
  "polyScanApiKey": "string",
  "clientIpLocation": {
    "country_code": "string",
    "country_name": "string",
    "region_code": "string",
    "region_name": "string",
    "city_name": "string",
    "postal_code": "string",
    "latitude": 37.7749,
    "longitude": -122.4194,
    "accuracy_radius": 5
  }
}

Get login token

Request

Generate a login token for the project

Security
projectKey
curl -i -X GET \
  https://docs.pers.ninja/_mock/swagger/tenants/login-token \
  -H 'x-project-key: YOUR_API_KEY_HERE'

Responses

Login token generated successfully

Bodyapplication/json
string
Response
application/json
"string"

Get current tenant information

Request

Convenience endpoint for API key holders to retrieve their own tenant information.

REQUIREMENTS:

  • Header: x-project-key (project identification)

RETURNS:

  • Enhanced public tenant information for the project associated with the API key

This is equivalent to calling GET /tenants/:id with your own tenant ID, but you don't need to know the ID.

Security
projectKey
curl -i -X GET \
  https://docs.pers.ninja/_mock/swagger/tenants/me \
  -H 'x-project-key: YOUR_API_KEY_HERE'

Responses

Current tenant information retrieved successfully

Bodyapplication/json
projectNamestringrequired

Name of the tenant.

acronymstringrequired

Acronym of the tenant.

idstringrequired

Unique identifier for tenant. This id is used to identify tenant in the system for client requests.

createdAtstring(date-time)required

Date when tenant was created.

projectDescriptionstring

Description of the tenant.

projectWebsitestring

Website of the tenant.

projectEmailstring

Email of the tenant.

projectImageUrlstring

Image URL of the tenant.

projectApiKeystringrequired

Unique identifier for tenant. This id is used to identify tenant in the system for client requests.

Response
application/json
{
  "projectName": "string",
  "acronym": "string",
  "id": "string",
  "createdAt": "2019-08-24T14:15:22Z",
  "projectDescription": "string",
  "projectWebsite": "string",
  "projectEmail": "string",
  "projectImageUrl": "string",
  "projectApiKey": "string"
}

Get tenant information by ID

Request

Context-aware tenant information retrieval:

UNAUTHENTICATED ACCESS:

  • No headers required
  • Returns: Basic public tenant information
Security
projectKey
Path
idstringrequired
curl -i -X GET \
  'https://docs.pers.ninja/_mock/swagger/tenants/{id}' \
  -H 'x-project-key: YOUR_API_KEY_HERE'

Responses

Tenant information retrieved successfully (data level depends on authentication)

Bodyapplication/json
projectNamestringrequired

Name of the tenant.

acronymstringrequired

Acronym of the tenant.

idstringrequired

Unique identifier for tenant. This id is used to identify tenant in the system for client requests.

createdAtstring(date-time)required

Date when tenant was created.

projectDescriptionstring

Description of the tenant.

projectWebsitestring

Website of the tenant.

projectEmailstring

Email of the tenant.

projectImageUrlstring

Image URL of the tenant.

projectApiKeystringrequired

Unique identifier for tenant. This id is used to identify tenant in the system for client requests.

Response
application/json
{
  "projectName": "string",
  "acronym": "string",
  "id": "string",
  "createdAt": "2019-08-24T14:15:22Z",
  "projectDescription": "string",
  "projectWebsite": "string",
  "projectEmail": "string",
  "projectImageUrl": "string",
  "projectApiKey": "string"
}

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

Redemption Tokens

Operations

API Keys

Operations