Skip to content
/
Get campaign payout previ...

Varmply Backend API (0.1.0)

Varmply API – MVP backend for campaigns, wallets, authentication, and influencer participation.

Download OpenAPI description
openapi.json
openapi.yaml
Languages
Servers
Mock server
https://docs-staging.varmply.com/_mock/openapi/
Local development server
http://localhost:3000/
Staging environment
https://api-staging.varmply.com/
Production environment
https://api.varmply.com/

Health

Health check endpoints

Operations

Authentication

User registration and authentication

Operations

Wallet

Wallet balance and operations

Operations

Dev

Development-only endpoints for testing (not available in production)

Operations

Campaigns

Campaign creation, management, and funding

Operations

Participation

Campaign participation and content submission

Operations

OAuth

Social media OAuth connection flows

Operations

Metrics

Content metrics and analytics endpoints

Operations

Refresh metrics for a participation's submitted content

Request

Refreshes metrics (impressions, reach, likes, comments, saves, shares) for a participation's submitted content. Fetches the latest metrics from the social media platform API and creates a snapshot. Requires the participation to have submitted content and the user to have a connected social account with valid OAuth tokens. Returns 200 OK with the created metrics snapshot on success.

Security
bearerAuth
Path
participationIdstringrequired

Unique identifier for the participation

Example: participation_xyz789
curl -i -X POST \
  https://docs-staging.varmply.com/_mock/openapi/metrics/participations/participation_xyz789/refresh \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Metrics refreshed successfully

Bodyapplication/json
snapshotobject(SubmissionMetricsSnapshot)required
snapshot.​snapshotIdstringrequired

Unique identifier for the metrics snapshot

Example: "snapshot_abc123"
snapshot.​participationIdstringrequired

Unique identifier for the participation

Example: "participation_xyz789"
snapshot.​externalMediaIdstringrequired

External media ID from the social platform (e.g., Instagram post ID)

Example: "ABC123"
snapshot.​impressionsintegerrequired

Number of impressions

Example: 1000
snapshot.​reachintegerrequired

Number of unique users reached

Example: 850
snapshot.​likesintegerrequired

Number of likes

Example: 100
snapshot.​commentsintegerrequired

Number of comments

Example: 20
snapshot.​savesintegerrequired

Number of saves

Example: 50
snapshot.​sharesintegerrequired

Number of shares

Example: 10
snapshot.​fetchedAtTimestampstring(date-time)required

When the metrics were fetched from the platform API

Example: "2024-01-01T12:00:00Z"
snapshot.​createdAtTimestampstring(date-time)required

When the snapshot was created

Example: "2024-01-01T12:00:00Z"
snapshot.​lastUpdatedAtTimestampstring(date-time)required

When the snapshot was last updated

Example: "2024-01-01T12:00:00Z"
Response
application/json
{
  "snapshot": {
    "snapshotId": "snapshot_abc123",
    "participationId": "participation_xyz789",
    "externalMediaId": "ABC123",
    "impressions": 1000,
    "reach": 850,
    "likes": 100,
    "comments": 20,
    "saves": 50,
    "shares": 10,
    "fetchedAtTimestamp": "2024-01-01T12:00:00Z",
    "createdAtTimestamp": "2024-01-01T12:00:00Z",
    "lastUpdatedAtTimestamp": "2024-01-01T12:00:00Z"
  }
}

Refresh metrics for all eligible participations in a campaign

Request

Refreshes metrics for all eligible participations in a campaign. Eligible participations are those with Instagram content submissions and status APPROVED or COMPLETED. Processes participations sequentially and returns a summary of successful and failed refreshes. Only the campaign owner can refresh metrics for their campaign. Returns 200 OK with the refresh summary on success.

Security
bearerAuth
Path
campaignIdstringrequired

Unique identifier for the campaign

Example: campaign_abc123
curl -i -X POST \
  https://docs-staging.varmply.com/_mock/openapi/metrics/campaigns/campaign_abc123/refresh \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Campaign metrics refresh completed

Bodyapplication/json
campaignIdstringrequired

Unique identifier for the campaign

Example: "campaign_abc123"
totalEligibleParticipationCountintegerrequired

Total number of participations eligible for metrics refresh (has Instagram submission and status APPROVED or COMPLETED)

Example: 5
successfulCountintegerrequired

Number of participations that were successfully refreshed

Example: 4
failedCountintegerrequired

Number of participations that failed to refresh

Example: 1
failedParticipationIdListArray of stringsrequired

List of participation IDs that failed to refresh

Example: ["participation_xyz789"]
Response
application/json
{
  "campaignId": "campaign_abc123",
  "totalEligibleParticipationCount": 5,
  "successfulCount": 4,
  "failedCount": 1,
  "failedParticipationIdList": [
    "participation_xyz789"
  ]
}

Get campaign analytics summary

Request

Returns read-only analytics summary for a campaign, including aggregated metrics totals and participation-level breakdown. Only the campaign owner can view analytics. Returns aggregated metrics from the latest snapshot per participation.

Security
bearerAuth
Path
campaignIdstringrequired

Unique identifier for the campaign

Example: campaign_abc123
curl -i -X GET \
  https://docs-staging.varmply.com/_mock/openapi/analytics/campaigns/campaign_abc123/summary \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Campaign analytics summary

Bodyapplication/json
summaryobject(CampaignAnalyticsSummary)required
summary.​campaignIdstringrequired

Unique identifier for the campaign

Example: "campaign_abc123"
summary.​totalImpressionsintegerrequired

Sum of impressions across all participations with metrics

Example: 2592
summary.​totalReachintegerrequired

Sum of reach across all participations with metrics

Example: 2023
summary.​totalLikesintegerrequired

Sum of likes across all participations with metrics

Example: 192
summary.​totalCommentsintegerrequired

Sum of comments across all participations with metrics

Example: 112
summary.​totalSavesintegerrequired

Sum of saves across all participations with metrics

Example: 24
summary.​totalSharesintegerrequired

Sum of shares across all participations with metrics

Example: 5
summary.​participationCountWithMetricsintegerrequired

Number of participations that have at least one metrics snapshot

Example: 3
summary.​totalParticipationCountintegerrequired

Total number of participations in the campaign (regardless of metrics presence)

Example: 5
summary.​metricsCoverageRationumber(float)required

Ratio of participations with metrics to total participations (0-1)

Example: 0.6
summary.​earliestSnapshotFetchedAtTimestampstring or null(date-time)required

Earliest fetchedAtTimestamp across all snapshots, or null if no snapshots

Example: "2025-11-26T23:39:30.449Z"
summary.​latestSnapshotFetchedAtTimestampstring or null(date-time)required

Latest fetchedAtTimestamp across all snapshots, or null if no snapshots

Example: "2025-11-27T10:12:02.100Z"
participationAnalyticsListArray of objects(ParticipationAnalyticsView)required

List of participation analytics views, one per participation that has metrics

participationAnalyticsList[].​participationIdstringrequired

Unique identifier for the participation

Example: "participation_xyz789"
participationAnalyticsList[].​influencerUserIdstringrequired

Unique identifier for the influencer user

Example: "user_123"
participationAnalyticsList[].​externalMediaIdstringrequired

External media ID from the latest snapshot

Example: "abc123"
participationAnalyticsList[].​impressionsintegerrequired

Impressions from the latest snapshot

Example: 2592
participationAnalyticsList[].​reachintegerrequired

Reach from the latest snapshot

Example: 2023
participationAnalyticsList[].​likesintegerrequired

Likes from the latest snapshot

Example: 192
participationAnalyticsList[].​commentsintegerrequired

Comments from the latest snapshot

Example: 112
participationAnalyticsList[].​savesintegerrequired

Saves from the latest snapshot

Example: 24
participationAnalyticsList[].​sharesintegerrequired

Shares from the latest snapshot

Example: 5
participationAnalyticsList[].​lastMetricsSyncedAtTimestampstring or null(date-time)required

Last time metrics were synced for this participation (from participation entity)

Example: "2025-11-26T23:39:30.449Z"
participationAnalyticsList[].​latestSnapshotFetchedAtTimestampstring(date-time)required

FetchedAtTimestamp of the latest snapshot

Example: "2025-11-26T23:39:30.449Z"
Response
application/json
{
  "summary": {
    "campaignId": "campaign_abc123",
    "totalImpressions": 2592,
    "totalReach": 2023,
    "totalLikes": 192,
    "totalComments": 112,
    "totalSaves": 24,
    "totalShares": 5,
    "participationCountWithMetrics": 3,
    "totalParticipationCount": 5,
    "metricsCoverageRatio": 0.6,
    "earliestSnapshotFetchedAtTimestamp": "2025-11-26T23:39:30.449Z",
    "latestSnapshotFetchedAtTimestamp": "2025-11-27T10:12:02.100Z"
  },
  "participationAnalyticsList": [
    { … }
  ]
}

Get campaign payout preview

Request

Returns a read-only payout preview for a campaign showing calculated payouts per participation based on metrics and a default payout formula, compared against available escrow balance. Only the campaign owner can view payout previews. This endpoint does not execute any payouts.

Security
bearerAuth
Path
campaignIdstringrequired

Unique identifier for the campaign

Example: campaign_abc123
curl -i -X GET \
  https://docs-staging.varmply.com/_mock/openapi/analytics/campaigns/campaign_abc123/payout-preview \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Campaign payout preview

Bodyapplication/json
campaignIdstringrequired

Unique identifier for the campaign

Example: "campaign_abc123"
campaignCurrencyCodestringrequired

Currency code for the campaign

Enum"NGN""USD"
Example: "NGN"
escrowAvailableAmountCentsintegerrequired

Current available escrow balance in cents

Example: 5000000
totalRequestedPayoutAmountCentsintegerrequired

Total requested payout amount across all participations in cents

Example: 3200000
shortfallAmountCentsintegerrequired

Shortfall amount if escrow is insufficient (0 if escrow covers all payouts)

Example: 0
participationPayoutListArray of objects(ParticipationPayoutPreview)required

List of participation payout previews

participationPayoutList[].​participationIdstringrequired

Unique identifier for the participation

Example: "participation_xyz789"
participationPayoutList[].​influencerUserIdstringrequired

Unique identifier for the influencer user

Example: "user_123"
participationPayoutList[].​externalMediaIdstringrequired

External media ID from the latest snapshot

Example: "abc123"
participationPayoutList[].​impressionsintegerrequired

Impressions from the latest snapshot

Example: 2592
participationPayoutList[].​reachintegerrequired

Reach from the latest snapshot

Example: 2023
participationPayoutList[].​likesintegerrequired

Likes from the latest snapshot

Example: 192
participationPayoutList[].​commentsintegerrequired

Comments from the latest snapshot

Example: 112
participationPayoutList[].​savesintegerrequired

Saves from the latest snapshot

Example: 24
participationPayoutList[].​sharesintegerrequired

Shares from the latest snapshot

Example: 5
participationPayoutList[].​lastMetricsSyncedAtTimestampstring or null(date-time)required

Last time metrics were synced for this participation

Example: "2025-11-27T08:30:49.957Z"
participationPayoutList[].​latestSnapshotFetchedAtTimestampstring(date-time)required

FetchedAtTimestamp of the latest snapshot

Example: "2025-11-27T08:30:49.957Z"
participationPayoutList[].​grossPayoutAmountCentsintegerrequired

Calculated gross payout amount for this participation in cents

Example: 80000
Response
application/json
{
  "campaignId": "campaign_abc123",
  "campaignCurrencyCode": "NGN",
  "escrowAvailableAmountCents": 5000000,
  "totalRequestedPayoutAmountCents": 3200000,
  "shortfallAmountCents": 0,
  "participationPayoutList": [
    { … }
  ]
}