Skip to content

Varmply Backend API (0.1.0)

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

Error Messages

Common error codes: - NOT_FOUND - Resource not found (404) - VALIDATION_ERROR - Input validation failed (400) - PERMISSION_DENIED - User lacks permission (403) - CONFLICT - Resource conflict (409) - UNAUTHORIZED - Authentication required (401) - INTERNAL_SERVER_ERROR - Unexpected server error (500)

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, authentication, and email verification

Operations

Onboarding

User onboarding flow for all user types, including role assignment, profile setup (creator and sponsor), and settings configuration

Operations

Connections

Social media platform connection status and management

Operations

OAuth

Social media OAuth connection flows

Operations

Wallet

Wallet balance and operations

Operations

Campaigns

Campaign creation, management, and funding

Operations

Marketplace

Public marketplace for discovering and joining campaigns

Operations

Participation

Campaign participation and content submission (creator-focused)

Operations

Analytics

Analytics and reporting endpoints for campaigns, participations, and submissions

Operations

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. All timestamps are in UTC (ISO 8601 format with Z suffix).

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": [
    { … }
  ]
}

Get submission analytics

Request

Returns read-only submission analytics with normalized metrics and money streams. Only accessible by the submission creator. Supports from, to, and bucket for date range and bucketing (defaults apply when omitted). All timestamps are in UTC (ISO 8601 format with Z suffix).

Security
bearerAuth
Path
submissionIdstringrequired

Unique identifier for the submission

Example: submission_abc123
Query
fromstring(date-time)

ISO timestamp (inclusive) for analytics window start (UTC)

Example: from=2024-01-01T00:00:00Z
tostring(date-time)

ISO timestamp (exclusive) for analytics window end (UTC)

Example: to=2024-01-15T00:00:00Z
bucketstring(AnalyticsTimeseriesBucket)

Bucket granularity override

Enum"DAY""WEEK"
curl -i -X GET \
  'https://docs-staging.varmply.com/_mock/openapi/submissions/submission_abc123/analytics?from=2024-01-01T00%3A00%3A00Z&to=2024-01-15T00%3A00%3A00Z&bucket=DAY' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Submission analytics retrieved successfully

Bodyapplication/json
submission_idstringrequired

Unique identifier for the submission

Example: "submission_abc123"
participation_idstringrequired

Unique identifier for the participation

Example: "participation_xyz789"
campaign_idstringrequired

Unique identifier for the campaign

Example: "campaign_abc123"
platformstringrequired

Platform type for the submission

Enum"INSTAGRAM""TIKTOK""FACEBOOK""YOUTUBE"
Example: "INSTAGRAM"
content_urlstringrequired

Original content URL submitted by the creator

Example: "https://instagram.com/p/example"
statusstring(AnalyticsSubmissionStatus)required
Enum"ACCEPTED""REJECTED""PENDING"
metricsobject(AnalyticsMetricsDto)required
metrics.​totalsobject(AnalyticsTotalsDto)required
metrics.​totals.​impressionsinteger or nullrequired
Example: 12345
metrics.​totals.​reachinteger or nullrequired
Example: 9000
metrics.​totals.​likesinteger or nullrequired
Example: 320
metrics.​totals.​commentsinteger or nullrequired
Example: 44
metrics.​totals.​sharesinteger or nullrequired
Example: null
metrics.​totals.​savesinteger or nullrequired
Example: 12
metrics.​totals.​viewsinteger or nullrequired
Example: null
metrics.​timeseriesobject(AnalyticsTimeseriesDto)required
metrics.​timeseries.​bucketstring(AnalyticsTimeseriesBucket)required

Bucket granularity for timeseries aggregation.

Enum"DAY""WEEK"
metrics.​timeseries.​seriesArray of objects(AnalyticsTimeseriesMetricSeriesDto)required
metrics.​timeseries.​series[].​metricstring(AnalyticsMetricKey)required

Normalized Varmply metric key.

Enum"impressions""reach""likes""comments""shares""saves""views"
metrics.​timeseries.​series[].​pointsArray of objects(AnalyticsTimeseriesPointDto)required
metrics.​timeseries.​series[].​points[].​start_atstring(date-time)required

Start of the aggregation window (inclusive, UTC)

Example: "2024-01-01T00:00:00Z"
metrics.​timeseries.​series[].​points[].​end_atstring(date-time)required

End of the aggregation window (exclusive, UTC)

Example: "2024-01-02T00:00:00Z"
metrics.​timeseries.​series[].​points[].​valueinteger or nullrequired

Value for the metric in this window (null if unavailable)

Example: 1000
metrics.​timeseries.​series[].​points[].​is_partialbooleanrequired

True if derived from an incomplete window (e.g. range cuts a bucket boundary)

Example: false
metrics.​timeseries.​series[].​points[].​sourcestring(AnalyticsTimeseriesPointSource)required

Source of the chart point value.

Enum"SNAPSHOT_DELTA""PLATFORM_TOTAL""ESTIMATED"
moneyobject(AnalyticsMoneyDto)required
money.​accrued_centsintegerrequired
Example: 120000
money.​paid_centsintegerrequired
Example: 80000
money.​blocked_centsintegerrequired
Example: 40000
money.​blocked_reason_codestring or nullrequired

Reason code for blocked accruals (null when blocked_cents is 0)

Value"INSUFFICIENT_ESCROW"
Example: "INSUFFICIENT_ESCROW"
freshnessobject(AnalyticsFreshnessDto)required
freshness.​statusstringrequired

Metrics status

Enum"OK""STALE""FAILED""PENDING"
Example: "OK"
freshness.​last_snapshot_atstring or null(date-time)required

Timestamp of the most recent snapshot fetchedAtTimestamp (UTC)

Example: "2024-01-01T12:00:00Z"
freshness.​last_attempt_atstring or null(date-time)required

Timestamp of the most recent ingestion attempt (UTC)

Example: "2024-01-01T12:10:00Z"
freshness.​last_success_atstring or null(date-time)required

Timestamp of the most recent successful ingestion (UTC)

Example: "2024-01-01T12:00:00Z"
freshness.​last_failure_reasonstring or nullrequired

Last failure reason mapped into a stable enum (null if none)

Enum"RATE_LIMIT""PERMISSION""INVALID_MEDIA""UNKNOWN"
Example: null
freshness.​freshness_statusstringrequired

Freshness status of the analytics data

Enum"FRESH""STALE""UNKNOWN"
Example: "FRESH"
Response
application/json
{
  "submission_id": "submission_abc123",
  "participation_id": "participation_xyz789",
  "campaign_id": "campaign_abc123",
  "platform": "INSTAGRAM",
  "content_url": "https://instagram.com/p/example",
  "status": "ACCEPTED",
  "metrics": {
    "totals": { … },
    "timeseries": { … }
  },
  "money": {
    "accrued_cents": 5000,
    "paid_cents": 0,
    "blocked_cents": 0,
    "blocked_reason_code": null
  },
  "freshness": {
    "last_snapshot_at": "2024-01-01T12:00:00Z",
    "last_attempt_at": "2024-01-01T12:10:00Z",
    "last_success_at": "2024-01-01T12:00:00Z",
    "last_failure_reason": null,
    "freshness_status": "FRESH"
  }
}

Metrics

Metrics ingestion and refresh endpoints for participations and campaigns

Operations

Notifications

User notification management endpoints

Operations

Dev

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

Operations