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

Metrics

Metrics ingestion and refresh endpoints for participations and campaigns

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, TikTok video ID)

Example: "ABC123"
snapshot.​impressionsinteger or null

Number of impressions (null for TikTok if unavailable)

Example: 1000
snapshot.​reachinteger or null

Number of unique users reached (null for TikTok if unavailable)

Example: 850
snapshot.​likesinteger or null

Number of likes (null if unavailable)

Example: 100
snapshot.​commentsinteger or null

Number of comments (null if unavailable)

Example: 20
snapshot.​savesinteger or null

Number of saves (null for TikTok if unavailable)

Example: 50
snapshot.​sharesinteger or null

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 at least one content submission and a status of 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"
  ]
}

Notifications

User notification management endpoints

Operations

Dev

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

Operations