Skip to content
/
Update trigger source

PERS-api Documentation (2.0.13)

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

Create trigger source

Request

Create a new trigger source (QR code, NFC tag, webhook, geofence, etc.) for a campaign

Security
authJWT
Bodyapplication/jsonrequired
typestringrequired

Type of the trigger source

Enum"QR_CODE""API_WEBHOOK"
Example: "QR_CODE"
namestringrequired

Human-readable name for the trigger source

Example: "Main Entrance QR Code"
descriptionobject or null

Optional description explaining this trigger source

Example: "QR code located at the main entrance for visitor check-in"
metadataobject

Type-specific configuration and settings

Example: {"tokenConfig":{"tokenId":"1"}}
businessIdobject or null

Reference to the business that owns this trigger source. Optional - can be tenant-wide trigger sources

Example: "business-uuid-123"
curl -i -X POST \
  https://docs.pers.ninja/_mock/swagger/trigger-sources \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "QR_CODE",
    "name": "Main Entrance QR Code",
    "description": "QR code located at the main entrance for visitor check-in",
    "metadata": {
      "tokenConfig": {
        "tokenId": "1"
      }
    },
    "businessId": "business-uuid-123"
  }'

Responses

Trigger source created successfully

Bodyapplication/json
typestringrequired

Type of the trigger source

Enum"QR_CODE""API_WEBHOOK"
Example: "QR_CODE"
namestringrequired

Human-readable name for the trigger source

Example: "Main Entrance QR Code"
descriptionobject or null

Optional description explaining this trigger source

Example: "QR code located at the main entrance for visitor check-in"
metadataobject

Type-specific configuration and settings

Example: {"tokenConfig":{"tokenId":"1"}}
businessIdobject or null

Reference to the business that owns this trigger source. Optional - can be tenant-wide trigger sources

Example: "business-uuid-123"
idstringrequired

Unique identifier for the trigger source

Example: "source-12345"
isActivebooleanrequired

Whether this trigger source is currently active. Inactive sources won't trigger any flows

Example: true
analyticsobject or null

Usage analytics and statistics for this trigger source

createdAtobjectrequired

Timestamp when the trigger source was created

Example: "2024-01-01T12:00:00.000Z"
updatedAtobjectrequired

Timestamp when the trigger source was last updated

Example: "2024-01-10T12:00:00.000Z"
Response
application/json
{
  "type": "QR_CODE",
  "name": "Main Entrance QR Code",
  "description": "QR code located at the main entrance for visitor check-in",
  "metadata": {
    "tokenConfig": { … }
  },
  "businessId": "business-uuid-123",
  "id": "source-12345",
  "isActive": true,
  "analytics": {
    "totalEngagements": 42,
    "uniqueUsers": 28,
    "lastEngagedAt": "2024-01-15T12:00:00.000Z",
    "firstEngagedAt": "2024-01-01T08:30:00.000Z",
    "averageEngagementsPerDay": 2.1
  },
  "createdAt": "2024-01-01T12:00:00.000Z",
  "updatedAt": "2024-01-10T12:00:00.000Z"
}

Get all trigger sources

Request

Retrieve all trigger sources with optional filtering and pagination

Security
projectKey
Query
typestring

Filter by trigger source type

Enum"QR_CODE""API_WEBHOOK"
businessIdstring

Filter by business ID

campaignIdstring

Filter by associated campaign ID

activeboolean

Filter by active status

limitnumber

Items per page

pagenumber

Page number (1-based)

sortBystring

Field to sort by

Enum"name""createdAt""type"
sortOrderstring

Sort order

Enum"ASC""DESC"
curl -i -X GET \
  'https://docs.pers.ninja/_mock/swagger/trigger-sources?type=QR_CODE&businessId=string&campaignId=string&active=true&limit=0&page=0&sortBy=name&sortOrder=ASC' \
  -H 'x-project-key: YOUR_API_KEY_HERE'

Responses

List of trigger sources

Bodyapplication/jsonArray [
typestringrequired

Type of the trigger source

Enum"QR_CODE""API_WEBHOOK"
Example: "QR_CODE"
namestringrequired

Human-readable name for the trigger source

Example: "Main Entrance QR Code"
descriptionobject or null

Optional description explaining this trigger source

Example: "QR code located at the main entrance for visitor check-in"
metadataobject

Type-specific configuration and settings

Example: {"tokenConfig":{"tokenId":"1"}}
businessIdobject or null

Reference to the business that owns this trigger source. Optional - can be tenant-wide trigger sources

Example: "business-uuid-123"
idstringrequired

Unique identifier for the trigger source

Example: "source-12345"
isActivebooleanrequired

Whether this trigger source is currently active. Inactive sources won't trigger any flows

Example: true
analyticsobject or null

Usage analytics and statistics for this trigger source

createdAtobjectrequired

Timestamp when the trigger source was created

Example: "2024-01-01T12:00:00.000Z"
updatedAtobjectrequired

Timestamp when the trigger source was last updated

Example: "2024-01-10T12:00:00.000Z"
]
Response
application/json
[
  {
    "type": "QR_CODE",
    "name": "Main Entrance QR Code",
    "description": "QR code located at the main entrance for visitor check-in",
    "metadata": { … },
    "businessId": "business-uuid-123",
    "id": "source-12345",
    "isActive": true,
    "analytics": { … },
    "createdAt": "2024-01-01T12:00:00.000Z",
    "updatedAt": "2024-01-10T12:00:00.000Z"
  }
]

Get trigger source by ID

Request

Retrieve a specific trigger source with its configuration

Security
projectKey
Path
idstringrequired

Trigger source ID

curl -i -X GET \
  'https://docs.pers.ninja/_mock/swagger/trigger-sources/{id}' \
  -H 'x-project-key: YOUR_API_KEY_HERE'

Responses

Trigger source retrieved successfully

Bodyapplication/json
typestringrequired

Type of the trigger source

Enum"QR_CODE""API_WEBHOOK"
Example: "QR_CODE"
namestringrequired

Human-readable name for the trigger source

Example: "Main Entrance QR Code"
descriptionobject or null

Optional description explaining this trigger source

Example: "QR code located at the main entrance for visitor check-in"
metadataobject

Type-specific configuration and settings

Example: {"tokenConfig":{"tokenId":"1"}}
businessIdobject or null

Reference to the business that owns this trigger source. Optional - can be tenant-wide trigger sources

Example: "business-uuid-123"
idstringrequired

Unique identifier for the trigger source

Example: "source-12345"
isActivebooleanrequired

Whether this trigger source is currently active. Inactive sources won't trigger any flows

Example: true
analyticsobject or null

Usage analytics and statistics for this trigger source

createdAtobjectrequired

Timestamp when the trigger source was created

Example: "2024-01-01T12:00:00.000Z"
updatedAtobjectrequired

Timestamp when the trigger source was last updated

Example: "2024-01-10T12:00:00.000Z"
Response
application/json
{
  "type": "QR_CODE",
  "name": "Main Entrance QR Code",
  "description": "QR code located at the main entrance for visitor check-in",
  "metadata": {
    "tokenConfig": { … }
  },
  "businessId": "business-uuid-123",
  "id": "source-12345",
  "isActive": true,
  "analytics": {
    "totalEngagements": 42,
    "uniqueUsers": 28,
    "lastEngagedAt": "2024-01-15T12:00:00.000Z",
    "firstEngagedAt": "2024-01-01T08:30:00.000Z",
    "averageEngagementsPerDay": 2.1
  },
  "createdAt": "2024-01-01T12:00:00.000Z",
  "updatedAt": "2024-01-10T12:00:00.000Z"
}

Update trigger source

Request

Update an existing trigger source configuration

Security
authJWT
Path
idstringrequired

Trigger source ID

Bodyapplication/jsonrequired

Trigger source update data

typestringrequired

Type of the trigger source

Enum"QR_CODE""API_WEBHOOK"
Example: "QR_CODE"
namestringrequired

Human-readable name for the trigger source

Example: "Main Entrance QR Code"
descriptionobject or null

Optional description explaining this trigger source

Example: "QR code located at the main entrance for visitor check-in"
metadataobject

Type-specific configuration and settings

Example: {"tokenConfig":{"tokenId":"1"}}
businessIdobject or null

Reference to the business that owns this trigger source. Optional - can be tenant-wide trigger sources

Example: "business-uuid-123"
curl -i -X PUT \
  'https://docs.pers.ninja/_mock/swagger/trigger-sources/{id}' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "QR_CODE",
    "name": "Main Entrance QR Code",
    "description": "QR code located at the main entrance for visitor check-in",
    "metadata": {
      "tokenConfig": {
        "tokenId": "1"
      }
    },
    "businessId": "business-uuid-123"
  }'

Responses

Trigger source updated successfully

Bodyapplication/json
typestringrequired

Type of the trigger source

Enum"QR_CODE""API_WEBHOOK"
Example: "QR_CODE"
namestringrequired

Human-readable name for the trigger source

Example: "Main Entrance QR Code"
descriptionobject or null

Optional description explaining this trigger source

Example: "QR code located at the main entrance for visitor check-in"
metadataobject

Type-specific configuration and settings

Example: {"tokenConfig":{"tokenId":"1"}}
businessIdobject or null

Reference to the business that owns this trigger source. Optional - can be tenant-wide trigger sources

Example: "business-uuid-123"
idstringrequired

Unique identifier for the trigger source

Example: "source-12345"
isActivebooleanrequired

Whether this trigger source is currently active. Inactive sources won't trigger any flows

Example: true
analyticsobject or null

Usage analytics and statistics for this trigger source

createdAtobjectrequired

Timestamp when the trigger source was created

Example: "2024-01-01T12:00:00.000Z"
updatedAtobjectrequired

Timestamp when the trigger source was last updated

Example: "2024-01-10T12:00:00.000Z"
Response
application/json
{
  "type": "QR_CODE",
  "name": "Main Entrance QR Code",
  "description": "QR code located at the main entrance for visitor check-in",
  "metadata": {
    "tokenConfig": { … }
  },
  "businessId": "business-uuid-123",
  "id": "source-12345",
  "isActive": true,
  "analytics": {
    "totalEngagements": 42,
    "uniqueUsers": 28,
    "lastEngagedAt": "2024-01-15T12:00:00.000Z",
    "firstEngagedAt": "2024-01-01T08:30:00.000Z",
    "averageEngagementsPerDay": 2.1
  },
  "createdAt": "2024-01-01T12:00:00.000Z",
  "updatedAt": "2024-01-10T12:00:00.000Z"
}

Delete trigger source

Request

Soft delete a trigger source (sets deletedAt timestamp)

Security
authJWT
Path
idstringrequired

Trigger source ID

curl -i -X DELETE \
  'https://docs.pers.ninja/_mock/swagger/trigger-sources/{id}' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Trigger source deleted successfully

Business Types

Operations

Redemption Types

Operations

Redemption Redeems

Operations

Redemption Tokens

Operations

API Keys

Operations