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

Create a new campaign

Request

Create a new campaign for the authenticated user and immediately attempt to fund it using targetBudgetAmountCents. The campaign is created as DRAFT, then funding is attempted. If funding succeeds, the campaign transitions to ACTIVE. If funding fails due to insufficient balance, the campaign remains DRAFT and funding attempt details are returned. For other funding failures, the campaign creation is rolled back. Returns 201 Created on success. Requires a valid JWT access token.

Security
bearerAuth
Bodyapplication/jsonrequired
campaignTitlestring>= 3 charactersrequired

Title of the campaign

Example: "Summer Product Launch"
campaignDescriptionstringnon-emptyrequired

Description of the campaign

Example: "Promote our new summer product line to increase brand awareness"
campaignObjectiveTypestringrequired

Objective type for the campaign

Enum"CAMPAIGN_OBJECTIVE_AWARENESS""CAMPAIGN_OBJECTIVE_ENGAGEMENT""CAMPAIGN_OBJECTIVE_CONVERSIONS"
Example: "CAMPAIGN_OBJECTIVE_AWARENESS"
campaignCurrencyCodestringrequired

Currency code for the campaign

Enum"NGN""USD"
Example: "NGN"
targetBudgetAmountCentsinteger>= 1required

Target budget in cents (required). This amount will be immediately attempted to be funded from the user's wallet.

Example: 1000000
campaignStartDateTimestampstring or null(date-time)

Campaign start date (optional)

Example: "2024-06-01T00:00:00Z"
campaignEndDateTimestampstring or null(date-time)

Campaign end date (optional, must be after start date)

Example: "2024-08-31T23:59:59Z"
requirementsobject
curl -i -X POST \
  https://docs-staging.varmply.com/_mock/openapi/campaigns \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "campaignTitle": "Summer Product Launch",
    "campaignDescription": "Promote our new summer product line to increase brand awareness",
    "campaignObjectiveType": "CAMPAIGN_OBJECTIVE_AWARENESS",
    "campaignCurrencyCode": "NGN",
    "targetBudgetAmountCents": 1000000,
    "requirements": {
      "requiredHashtags": [
        "#hashtag1",
        "#hashtag2"
      ],
      "requiredMentions": [
        "@mention1",
        "@mention2"
      ],
      "allowedContentTypes": [
        "INSTAGRAM"
      ],
      "submissionLimit": 2
    },
    "campaignStartDateTimestamp": "2024-06-01T00:00:00Z",
    "campaignEndDateTimestamp": "2024-08-31T23:59:59Z"
  }'

Responses

Campaign created successfully. If funding succeeded, campaign will be ACTIVE with funded escrow. If funding failed due to insufficient balance, campaign will be DRAFT with fundingAttempt details included.

Bodyapplication/json
campaignobject(Campaign)required
campaign.​campaignIdstringrequired

Unique identifier for the campaign

Example: "campaign_abc123"
campaign.​ownerUserIdstringrequired

Unique identifier for the campaign owner

Example: "user_123"
campaign.​campaignTitlestringrequired

Title of the campaign

Example: "Summer Product Launch"
campaign.​campaignDescriptionstringrequired

Description of the campaign

Example: "Promote our new summer product line to increase brand awareness"
campaign.​campaignObjectiveTypestringrequired

Objective type for the campaign

Enum"CAMPAIGN_OBJECTIVE_AWARENESS""CAMPAIGN_OBJECTIVE_ENGAGEMENT""CAMPAIGN_OBJECTIVE_CONVERSIONS"
Example: "CAMPAIGN_OBJECTIVE_AWARENESS"
campaign.​campaignCurrencyCodestringrequired

Currency code for the campaign

Enum"NGN""USD"
Example: "NGN"
campaign.​targetBudgetAmountCentsinteger or nullrequired

Target budget in cents (null if no target set)

Example: 1000000
campaign.​campaignLifeCycleStatusstringrequired

Current lifecycle status of the campaign

Enum"CAMPAIGN_DRAFT""CAMPAIGN_ACTIVE""CAMPAIGN_PAUSED""CAMPAIGN_COMPLETED""CAMPAIGN_COMPLETED_WITH_REFUND""CAMPAIGN_CANCELLED"
Example: "CAMPAIGN_ACTIVE"
campaign.​campaignStartDateTimestampstring or null(date-time)required

Campaign start date (null if not set)

Example: "2024-06-01T00:00:00Z"
campaign.​campaignEndDateTimestampstring or null(date-time)required

Campaign end date (null if not set)

Example: "2024-08-31T23:59:59Z"
campaign.​completedAtTimestampstring or null(date-time)required

When the campaign was completed (null if not yet completed)

Example: "2024-09-01T00:00:00Z"
campaign.​requirementsobjectrequired
campaign.​requirements.​requiredHashtagsArray of stringsrequired

Array of required hashtags for submissions

Example: ["#hashtag1","#hashtag2"]
campaign.​requirements.​requiredMentionsArray of stringsrequired

Array of required mentions for submissions

Example: ["@mention1","@mention2"]
campaign.​requirements.​allowedContentTypesArray of stringsrequired

Array of allowed content platform types

Items Enum"INSTAGRAM""TIKTOK""FACEBOOK""YOUTUBE"
Example: ["INSTAGRAM"]
campaign.​requirements.​submissionLimitinteger>= 1required

Maximum number of submissions allowed per participation

Example: 2
campaign.​createdAtTimestampstring(date-time)required

When the campaign was created

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

When the campaign was last updated

Example: "2024-01-01T00:00:00Z"
campaignEscrowobject(CampaignEscrow)required
campaignEscrow.​escrowIdstringrequired

Unique identifier for the escrow

Example: "escrow_xyz789"
campaignEscrow.​campaignIdstringrequired

Unique identifier for the associated campaign

Example: "campaign_abc123"
campaignEscrow.​escrowCurrencyCodestringrequired

Currency code for the escrow

Enum"NGN""USD"
Example: "NGN"
campaignEscrow.​currentEscrowBalanceAmountCentsintegerrequired

Current balance in the escrow account (cents)

Example: 500000
campaignEscrow.​totalFundedAmountCentsintegerrequired

Total amount funded into the escrow (cents)

Example: 500000
campaignEscrow.​totalReleasedAmountCentsintegerrequired

Total amount released from the escrow (cents)

Example: 0
campaignEscrow.​totalRefundedAmountCentsintegerrequired

Total amount refunded from the escrow (cents)

Example: 0
campaignEscrow.​createdAtTimestampstring(date-time)required

When the escrow was created

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

When the escrow was last updated

Example: "2024-01-01T12:00:00Z"
fundingAttemptobject

Present only when funding failed due to insufficient balance

Response
application/json
{
  "campaign": {
    "campaignId": "campaign_abc123",
    "ownerUserId": "user_123",
    "campaignTitle": "Summer Product Launch",
    "campaignDescription": "Promote our new summer product line to increase brand awareness",
    "campaignObjectiveType": "CAMPAIGN_OBJECTIVE_AWARENESS",
    "campaignCurrencyCode": "NGN",
    "targetBudgetAmountCents": 1000000,
    "campaignLifeCycleStatus": "CAMPAIGN_ACTIVE",
    "campaignStartDateTimestamp": "2024-06-01T00:00:00Z",
    "campaignEndDateTimestamp": "2024-08-31T23:59:59Z",
    "completedAtTimestamp": null,
    "requirements": { … },
    "createdAtTimestamp": "2024-01-01T00:00:00Z",
    "lastUpdatedAtTimestamp": "2024-01-01T00:00:00Z"
  },
  "campaignEscrow": {
    "escrowId": "escrow_xyz789",
    "campaignId": "campaign_abc123",
    "escrowCurrencyCode": "NGN",
    "currentEscrowBalanceAmountCents": 1000000,
    "totalFundedAmountCents": 1000000,
    "totalReleasedAmountCents": 0,
    "totalRefundedAmountCents": 0,
    "createdAtTimestamp": "2024-01-01T00:00:00Z",
    "lastUpdatedAtTimestamp": "2024-01-01T00:00:00Z"
  }
}

Get campaign details

Request

Retrieve a campaign summary for the authenticated user. Only the campaign owner can access the campaign. Returns 200 OK on success, 404 if not found, 403 if not owned by user. Requires a valid JWT access token.

Security
bearerAuth
Path
campaignIdstringrequired

Unique identifier for the campaign

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

Responses

Campaign retrieved successfully

Bodyapplication/json
campaignobject(Campaign)required
campaign.​campaignIdstringrequired

Unique identifier for the campaign

Example: "campaign_abc123"
campaign.​ownerUserIdstringrequired

Unique identifier for the campaign owner

Example: "user_123"
campaign.​campaignTitlestringrequired

Title of the campaign

Example: "Summer Product Launch"
campaign.​campaignDescriptionstringrequired

Description of the campaign

Example: "Promote our new summer product line to increase brand awareness"
campaign.​campaignObjectiveTypestringrequired

Objective type for the campaign

Enum"CAMPAIGN_OBJECTIVE_AWARENESS""CAMPAIGN_OBJECTIVE_ENGAGEMENT""CAMPAIGN_OBJECTIVE_CONVERSIONS"
Example: "CAMPAIGN_OBJECTIVE_AWARENESS"
campaign.​campaignCurrencyCodestringrequired

Currency code for the campaign

Enum"NGN""USD"
Example: "NGN"
campaign.​targetBudgetAmountCentsinteger or nullrequired

Target budget in cents (null if no target set)

Example: 1000000
campaign.​campaignLifeCycleStatusstringrequired

Current lifecycle status of the campaign

Enum"CAMPAIGN_DRAFT""CAMPAIGN_ACTIVE""CAMPAIGN_PAUSED""CAMPAIGN_COMPLETED""CAMPAIGN_COMPLETED_WITH_REFUND""CAMPAIGN_CANCELLED"
Example: "CAMPAIGN_ACTIVE"
campaign.​campaignStartDateTimestampstring or null(date-time)required

Campaign start date (null if not set)

Example: "2024-06-01T00:00:00Z"
campaign.​campaignEndDateTimestampstring or null(date-time)required

Campaign end date (null if not set)

Example: "2024-08-31T23:59:59Z"
campaign.​completedAtTimestampstring or null(date-time)required

When the campaign was completed (null if not yet completed)

Example: "2024-09-01T00:00:00Z"
campaign.​requirementsobjectrequired
campaign.​requirements.​requiredHashtagsArray of stringsrequired

Array of required hashtags for submissions

Example: ["#hashtag1","#hashtag2"]
campaign.​requirements.​requiredMentionsArray of stringsrequired

Array of required mentions for submissions

Example: ["@mention1","@mention2"]
campaign.​requirements.​allowedContentTypesArray of stringsrequired

Array of allowed content platform types

Items Enum"INSTAGRAM""TIKTOK""FACEBOOK""YOUTUBE"
Example: ["INSTAGRAM"]
campaign.​requirements.​submissionLimitinteger>= 1required

Maximum number of submissions allowed per participation

Example: 2
campaign.​createdAtTimestampstring(date-time)required

When the campaign was created

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

When the campaign was last updated

Example: "2024-01-01T00:00:00Z"
campaignEscrowobject(CampaignEscrow)required
campaignEscrow.​escrowIdstringrequired

Unique identifier for the escrow

Example: "escrow_xyz789"
campaignEscrow.​campaignIdstringrequired

Unique identifier for the associated campaign

Example: "campaign_abc123"
campaignEscrow.​escrowCurrencyCodestringrequired

Currency code for the escrow

Enum"NGN""USD"
Example: "NGN"
campaignEscrow.​currentEscrowBalanceAmountCentsintegerrequired

Current balance in the escrow account (cents)

Example: 500000
campaignEscrow.​totalFundedAmountCentsintegerrequired

Total amount funded into the escrow (cents)

Example: 500000
campaignEscrow.​totalReleasedAmountCentsintegerrequired

Total amount released from the escrow (cents)

Example: 0
campaignEscrow.​totalRefundedAmountCentsintegerrequired

Total amount refunded from the escrow (cents)

Example: 0
campaignEscrow.​createdAtTimestampstring(date-time)required

When the escrow was created

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

When the escrow was last updated

Example: "2024-01-01T12:00:00Z"
Response
application/json
{
  "campaign": {
    "campaignId": "campaign_abc123",
    "ownerUserId": "user_123",
    "campaignTitle": "Summer Product Launch",
    "campaignDescription": "Promote our new summer product line to increase brand awareness",
    "campaignObjectiveType": "CAMPAIGN_OBJECTIVE_AWARENESS",
    "campaignCurrencyCode": "NGN",
    "targetBudgetAmountCents": 1000000,
    "campaignLifeCycleStatus": "CAMPAIGN_ACTIVE",
    "campaignStartDateTimestamp": "2024-06-01T00:00:00Z",
    "campaignEndDateTimestamp": "2024-08-31T23:59:59Z",
    "completedAtTimestamp": null,
    "requirements": { … },
    "createdAtTimestamp": "2024-01-01T00:00:00Z",
    "lastUpdatedAtTimestamp": "2024-01-01T00:00:00Z"
  },
  "campaignEscrow": {
    "escrowId": "escrow_xyz789",
    "campaignId": "campaign_abc123",
    "escrowCurrencyCode": "NGN",
    "currentEscrowBalanceAmountCents": 500000,
    "totalFundedAmountCents": 500000,
    "totalReleasedAmountCents": 0,
    "totalRefundedAmountCents": 0,
    "createdAtTimestamp": "2024-01-01T00:00:00Z",
    "lastUpdatedAtTimestamp": "2024-01-01T12:00:00Z"
  }
}

Get campaign analytics summary

Request

Retrieve a comprehensive analytics summary for a campaign including escrow, participation, submission, and payout metrics. Returns 200 OK on success, 404 if campaign not found. Requires a valid JWT access token.

Security
bearerAuth
Path
campaignIdstringrequired

Unique identifier for the campaign

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

Responses

Campaign analytics summary retrieved successfully

Bodyapplication/json
campaignobject(Campaign)required
campaign.​campaignIdstringrequired

Unique identifier for the campaign

Example: "campaign_abc123"
campaign.​ownerUserIdstringrequired

Unique identifier for the campaign owner

Example: "user_123"
campaign.​campaignTitlestringrequired

Title of the campaign

Example: "Summer Product Launch"
campaign.​campaignDescriptionstringrequired

Description of the campaign

Example: "Promote our new summer product line to increase brand awareness"
campaign.​campaignObjectiveTypestringrequired

Objective type for the campaign

Enum"CAMPAIGN_OBJECTIVE_AWARENESS""CAMPAIGN_OBJECTIVE_ENGAGEMENT""CAMPAIGN_OBJECTIVE_CONVERSIONS"
Example: "CAMPAIGN_OBJECTIVE_AWARENESS"
campaign.​campaignCurrencyCodestringrequired

Currency code for the campaign

Enum"NGN""USD"
Example: "NGN"
campaign.​targetBudgetAmountCentsinteger or nullrequired

Target budget in cents (null if no target set)

Example: 1000000
campaign.​campaignLifeCycleStatusstringrequired

Current lifecycle status of the campaign

Enum"CAMPAIGN_DRAFT""CAMPAIGN_ACTIVE""CAMPAIGN_PAUSED""CAMPAIGN_COMPLETED""CAMPAIGN_COMPLETED_WITH_REFUND""CAMPAIGN_CANCELLED"
Example: "CAMPAIGN_ACTIVE"
campaign.​campaignStartDateTimestampstring or null(date-time)required

Campaign start date (null if not set)

Example: "2024-06-01T00:00:00Z"
campaign.​campaignEndDateTimestampstring or null(date-time)required

Campaign end date (null if not set)

Example: "2024-08-31T23:59:59Z"
campaign.​completedAtTimestampstring or null(date-time)required

When the campaign was completed (null if not yet completed)

Example: "2024-09-01T00:00:00Z"
campaign.​requirementsobjectrequired
campaign.​requirements.​requiredHashtagsArray of stringsrequired

Array of required hashtags for submissions

Example: ["#hashtag1","#hashtag2"]
campaign.​requirements.​requiredMentionsArray of stringsrequired

Array of required mentions for submissions

Example: ["@mention1","@mention2"]
campaign.​requirements.​allowedContentTypesArray of stringsrequired

Array of allowed content platform types

Items Enum"INSTAGRAM""TIKTOK""FACEBOOK""YOUTUBE"
Example: ["INSTAGRAM"]
campaign.​requirements.​submissionLimitinteger>= 1required

Maximum number of submissions allowed per participation

Example: 2
campaign.​createdAtTimestampstring(date-time)required

When the campaign was created

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

When the campaign was last updated

Example: "2024-01-01T00:00:00Z"
escrowSummaryobjectrequired
escrowSummary.​fundedintegerrequired

Total amount funded into escrow (cents)

Example: 500000
escrowSummary.​releasedintegerrequired

Total amount released from escrow (cents)

Example: 300000
escrowSummary.​refundedintegerrequired

Total amount refunded from escrow (cents)

Example: 0
escrowSummary.​currentBalanceintegerrequired

Current escrow balance (cents)

Example: 200000
participationCountsobjectrequired
participationCounts.​totalintegerrequired

Total number of participations

Example: 10
participationCounts.​activeintegerrequired

Number of active participations (approved or content submitted)

Example: 7
participationCounts.​completedintegerrequired

Number of completed participations

Example: 3
submissionCountsobjectrequired
submissionCounts.​totalintegerrequired

Total number of content submissions

Example: 15
submissionCounts.​approvedintegerrequired

Number of approved submissions

Example: 8
submissionCounts.​rejectedintegerrequired

Number of rejected submissions

Example: 2
submissionCounts.​pendingintegerrequired

Number of pending submissions

Example: 5
payoutSummaryobjectrequired
payoutSummary.​totalInfluencerPayoutintegerrequired

Total amount paid out to influencers (cents)

Example: 250000
payoutSummary.​totalPlatformFeeintegerrequired

Total platform fees collected (cents)

Example: 50000
payoutSummary.​payoutCountintegerrequired

Number of payout transactions processed

Example: 5
lifecycleobjectrequired
lifecycle.​statusstringrequired

Current lifecycle status of the campaign

Enum"CAMPAIGN_DRAFT""CAMPAIGN_ACTIVE""CAMPAIGN_PAUSED""CAMPAIGN_COMPLETED""CAMPAIGN_COMPLETED_WITH_REFUND""CAMPAIGN_CANCELLED"
Example: "CAMPAIGN_ACTIVE"
lifecycle.​completedAtTimestampstring or null(date-time)required

When the campaign was completed (null if not yet completed)

Example: null
Response
application/json
{
  "campaign": {
    "campaignId": "campaign_abc123",
    "ownerUserId": "user_123",
    "campaignTitle": "Summer Product Launch",
    "campaignDescription": "Promote our new summer product line to increase brand awareness",
    "campaignObjectiveType": "CAMPAIGN_OBJECTIVE_AWARENESS",
    "campaignCurrencyCode": "NGN",
    "targetBudgetAmountCents": 1000000,
    "campaignLifeCycleStatus": "CAMPAIGN_ACTIVE",
    "campaignStartDateTimestamp": "2024-06-01T00:00:00Z",
    "campaignEndDateTimestamp": "2024-08-31T23:59:59Z",
    "completedAtTimestamp": null,
    "requirements": { … },
    "createdAtTimestamp": "2024-01-01T00:00:00Z",
    "lastUpdatedAtTimestamp": "2024-01-01T00:00:00Z"
  },
  "escrowSummary": {
    "funded": 500000,
    "released": 300000,
    "refunded": 0,
    "currentBalance": 200000
  },
  "participationCounts": {
    "total": 10,
    "active": 7,
    "completed": 3
  },
  "submissionCounts": {
    "total": 15,
    "approved": 8,
    "rejected": 2,
    "pending": 5
  },
  "payoutSummary": {
    "totalInfluencerPayout": 250000,
    "totalPlatformFee": 50000,
    "payoutCount": 5
  },
  "lifecycle": {
    "status": "CAMPAIGN_ACTIVE",
    "completedAtTimestamp": null
  }
}

Get campaign ledger activity feed

Request

Retrieve campaign ledger transaction events as an activity feed, showing all financial transactions related to a campaign in chronological order (newest first). Returns 200 OK on success, 404 if campaign not found. Supports optional limit query parameter (default 50). Requires a valid JWT access token.

Security
bearerAuth
Path
campaignIdstringrequired

Unique identifier for the campaign

Example: campaign_abc123
Query
limitinteger>= 1

Maximum number of events to return (default 50)

Default 50
Example: limit=50
curl -i -X GET \
  'https://docs-staging.varmply.com/_mock/openapi/campaigns/campaign_abc123/ledger?limit=50' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Campaign ledger events retrieved successfully

Bodyapplication/jsonArray [
transactionIdstringrequired

Unique identifier for the ledger transaction

Example: "ledger_tx_abc123"
occurredAtTimestampstring(date-time)required

When the transaction occurred

Example: "2024-01-15T10:30:00Z"
transactionTypestringrequired

Type of ledger transaction

Enum"LEDGER_ENTRY_TRANSACTION_TYPE_ESCROW_FUNDING""LEDGER_ENTRY_TRANSACTION_TYPE_PLATFORM_PAYOUT_FEE""LEDGER_ENTRY_TRANSACTION_TYPE_INFLUENCER_PAYOUT_NET""LEDGER_ENTRY_TRANSACTION_TYPE_INFLUENCER_PAYOUT_GROSS""LEDGER_ENTRY_TRANSACTION_TYPE_ADMIN_WALLET_FUNDING""LEDGER_ENTRY_TRANSACTION_TYPE_ESCROW_REFUND""LEDGER_ENTRY_TRANSACTION_TYPE_DEV_WALLET_FUND"
Example: "LEDGER_ENTRY_TRANSACTION_TYPE_INFLUENCER_PAYOUT_GROSS"
descriptionstringrequired

Human-friendly description of the transaction

Example: "Influencer payout"
totalAmountCentsintegerrequired

Sum of positive line amounts in cents

Example: 10000
currencyCodestringrequired

Currency code for the transaction

Enum"NGN""USD"
Example: "NGN"
fromAccountsArray of objects(CampaignLedgerEventAccount)required

Ledger lines with negative amounts (sources)

fromAccounts[].​ledgerAccountTypestringrequired

Type of ledger account

Enum"LEDGER_ACCOUNT_TYPE_USER_WALLET""LEDGER_ACCOUNT_TYPE_CAMPAIGN_ESCROW""LEDGER_ACCOUNT_TYPE_PLATFORM_WALLET"
Example: "LEDGER_ACCOUNT_TYPE_USER_WALLET"
fromAccounts[].​ledgerAccountReferenceIdstringrequired

Reference identifier for the account (user ID, campaign ID, or PLATFORM_WALLET)

Example: "user_456"
fromAccounts[].​amountCentsintegerrequired

Amount in cents (absolute value for fromAccounts)

Example: 10000
toAccountsArray of objects(CampaignLedgerEventAccount)required

Ledger lines with positive amounts (destinations)

toAccounts[].​ledgerAccountTypestringrequired

Type of ledger account

Enum"LEDGER_ACCOUNT_TYPE_USER_WALLET""LEDGER_ACCOUNT_TYPE_CAMPAIGN_ESCROW""LEDGER_ACCOUNT_TYPE_PLATFORM_WALLET"
Example: "LEDGER_ACCOUNT_TYPE_USER_WALLET"
toAccounts[].​ledgerAccountReferenceIdstringrequired

Reference identifier for the account (user ID, campaign ID, or PLATFORM_WALLET)

Example: "user_456"
toAccounts[].​amountCentsintegerrequired

Amount in cents (absolute value for fromAccounts)

Example: 10000
]
Response
application/json
[
  {
    "transactionId": "ledger_tx_abc123",
    "occurredAtTimestamp": "2024-01-15T10:30:00Z",
    "transactionType": "LEDGER_ENTRY_TRANSACTION_TYPE_INFLUENCER_PAYOUT_GROSS",
    "description": "Influencer payout",
    "totalAmountCents": 10000,
    "currencyCode": "NGN",
    "fromAccounts": [ … ],
    "toAccounts": [ … ]
  },
  {
    "transactionId": "ledger_tx_def456",
    "occurredAtTimestamp": "2024-01-10T08:00:00Z",
    "transactionType": "LEDGER_ENTRY_TRANSACTION_TYPE_ESCROW_FUNDING",
    "description": "Escrow funded",
    "totalAmountCents": 50000,
    "currencyCode": "NGN",
    "fromAccounts": [ … ],
    "toAccounts": [ … ]
  }
]

Get campaign timeline analytics

Request

Retrieve time-series timeline data for a campaign with daily buckets showing cumulative payouts, escrow balance, participation counts, and approved submission counts over time. Returns 200 OK on success, 404 if campaign not found. Supports optional limitDays query parameter to limit the number of days returned. Requires a valid JWT access token. All timestamps are in UTC (ISO 8601 format with Z suffix).

Security
bearerAuth
Path
campaignIdstringrequired

Unique identifier for the campaign

Example: campaign_abc123
Query
limitDaysinteger>= 1

Maximum number of days to return (returns most recent N days)

Example: limitDays=30
curl -i -X GET \
  'https://docs-staging.varmply.com/_mock/openapi/campaigns/campaign_abc123/timeline?limitDays=30' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Campaign timeline retrieved successfully

Bodyapplication/json
campaignIdstringrequired

Unique identifier for the campaign

Example: "campaign_abc123"
bucketGranularitystringrequired

Granularity of time buckets

Value"DAY"
Example: "DAY"
pointsArray of objects(CampaignTimelinePoint)required

Timeline data points, one per day

points[].​bucketDatestring(date)required

Date of the bucket in YYYY-MM-DD format

Example: "2024-01-15"
points[].​bucketStartTimestampstring(date-time)required

Start of the bucket (00:00:00 UTC)

Example: "2024-01-15T00:00:00Z"
points[].​bucketEndTimestampstring(date-time)required

End of the bucket (23:59:59.999 UTC)

Example: "2024-01-15T23:59:59.999Z"
points[].​cumulativePayoutAmountCentsintegerrequired

Cumulative total of all payouts up to this bucket

Example: 10000
points[].​remainingEscrowBalanceAmountCentsintegerrequired

Remaining escrow balance at the end of this bucket

Example: 40000
points[].​totalParticipationCountintegerrequired

Cumulative total of participations up to this bucket

Example: 5
points[].​totalApprovedSubmissionCountintegerrequired

Cumulative total of approved submissions up to this bucket

Example: 3
Response
application/json
{
  "campaignId": "campaign_abc123",
  "bucketGranularity": "DAY",
  "points": [
    { … },
    { … },
    { … }
  ]
}

Fund a campaign

Request

Fund a campaign from the authenticated user's wallet. Only the campaign owner can fund their campaign. Returns 200 OK on success. Requires a valid JWT access token.

Security
bearerAuth
Path
campaignIdstringrequired

Unique identifier for the campaign

Example: campaign_abc123
Bodyapplication/jsonrequired
fundingAmountCentsinteger>= 1required

Amount to fund in cents

Example: 500000
walletCurrencyCodestringrequired

Currency code of the wallet to fund from

Enum"NGN""USD"
Example: "NGN"
curl -i -X POST \
  https://docs-staging.varmply.com/_mock/openapi/campaigns/campaign_abc123/fund \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "fundingAmountCents": 500000,
    "walletCurrencyCode": "NGN"
  }'

Responses

Campaign funded successfully

Bodyapplication/json
campaignobject(Campaign)required
campaign.​campaignIdstringrequired

Unique identifier for the campaign

Example: "campaign_abc123"
campaign.​ownerUserIdstringrequired

Unique identifier for the campaign owner

Example: "user_123"
campaign.​campaignTitlestringrequired

Title of the campaign

Example: "Summer Product Launch"
campaign.​campaignDescriptionstringrequired

Description of the campaign

Example: "Promote our new summer product line to increase brand awareness"
campaign.​campaignObjectiveTypestringrequired

Objective type for the campaign

Enum"CAMPAIGN_OBJECTIVE_AWARENESS""CAMPAIGN_OBJECTIVE_ENGAGEMENT""CAMPAIGN_OBJECTIVE_CONVERSIONS"
Example: "CAMPAIGN_OBJECTIVE_AWARENESS"
campaign.​campaignCurrencyCodestringrequired

Currency code for the campaign

Enum"NGN""USD"
Example: "NGN"
campaign.​targetBudgetAmountCentsinteger or nullrequired

Target budget in cents (null if no target set)

Example: 1000000
campaign.​campaignLifeCycleStatusstringrequired

Current lifecycle status of the campaign

Enum"CAMPAIGN_DRAFT""CAMPAIGN_ACTIVE""CAMPAIGN_PAUSED""CAMPAIGN_COMPLETED""CAMPAIGN_COMPLETED_WITH_REFUND""CAMPAIGN_CANCELLED"
Example: "CAMPAIGN_ACTIVE"
campaign.​campaignStartDateTimestampstring or null(date-time)required

Campaign start date (null if not set)

Example: "2024-06-01T00:00:00Z"
campaign.​campaignEndDateTimestampstring or null(date-time)required

Campaign end date (null if not set)

Example: "2024-08-31T23:59:59Z"
campaign.​completedAtTimestampstring or null(date-time)required

When the campaign was completed (null if not yet completed)

Example: "2024-09-01T00:00:00Z"
campaign.​requirementsobjectrequired
campaign.​requirements.​requiredHashtagsArray of stringsrequired

Array of required hashtags for submissions

Example: ["#hashtag1","#hashtag2"]
campaign.​requirements.​requiredMentionsArray of stringsrequired

Array of required mentions for submissions

Example: ["@mention1","@mention2"]
campaign.​requirements.​allowedContentTypesArray of stringsrequired

Array of allowed content platform types

Items Enum"INSTAGRAM""TIKTOK""FACEBOOK""YOUTUBE"
Example: ["INSTAGRAM"]
campaign.​requirements.​submissionLimitinteger>= 1required

Maximum number of submissions allowed per participation

Example: 2
campaign.​createdAtTimestampstring(date-time)required

When the campaign was created

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

When the campaign was last updated

Example: "2024-01-01T00:00:00Z"
campaignEscrowobject(CampaignEscrow)required
campaignEscrow.​escrowIdstringrequired

Unique identifier for the escrow

Example: "escrow_xyz789"
campaignEscrow.​campaignIdstringrequired

Unique identifier for the associated campaign

Example: "campaign_abc123"
campaignEscrow.​escrowCurrencyCodestringrequired

Currency code for the escrow

Enum"NGN""USD"
Example: "NGN"
campaignEscrow.​currentEscrowBalanceAmountCentsintegerrequired

Current balance in the escrow account (cents)

Example: 500000
campaignEscrow.​totalFundedAmountCentsintegerrequired

Total amount funded into the escrow (cents)

Example: 500000
campaignEscrow.​totalReleasedAmountCentsintegerrequired

Total amount released from the escrow (cents)

Example: 0
campaignEscrow.​totalRefundedAmountCentsintegerrequired

Total amount refunded from the escrow (cents)

Example: 0
campaignEscrow.​createdAtTimestampstring(date-time)required

When the escrow was created

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

When the escrow was last updated

Example: "2024-01-01T12:00:00Z"
Response
application/json
{
  "campaign": {
    "campaignId": "campaign_abc123",
    "ownerUserId": "user_123",
    "campaignTitle": "Summer Product Launch",
    "campaignDescription": "Promote our new summer product line",
    "campaignObjectiveType": "CAMPAIGN_OBJECTIVE_AWARENESS",
    "campaignCurrencyCode": "NGN",
    "targetBudgetAmountCents": 1000000,
    "campaignLifeCycleStatus": "CAMPAIGN_ACTIVE",
    "campaignStartDateTimestamp": "2024-06-01T00:00:00Z",
    "campaignEndDateTimestamp": "2024-08-31T23:59:59Z",
    "completedAtTimestamp": null,
    "createdAtTimestamp": "2024-01-01T00:00:00Z",
    "lastUpdatedAtTimestamp": "2024-01-01T00:00:00Z"
  },
  "campaignEscrow": {
    "escrowId": "escrow_xyz789",
    "campaignId": "campaign_abc123",
    "escrowCurrencyCode": "NGN",
    "currentEscrowBalanceAmountCents": 500000,
    "totalFundedAmountCents": 500000,
    "totalReleasedAmountCents": 0,
    "totalRefundedAmountCents": 0,
    "createdAtTimestamp": "2024-01-01T00:00:00Z",
    "lastUpdatedAtTimestamp": "2024-01-01T12:00:00Z"
  }
}

Finalize a campaign

Request

Finalize a campaign if completion conditions are met. Only the campaign owner can finalize their campaign. Completion requires either: campaign endDate has passed OR escrow balance is zero. Returns 200 OK with updated campaign on success, 400 if not eligible. Requires a valid JWT access token.

Security
bearerAuth
Path
campaignIdstringrequired

Unique identifier for the campaign

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

Responses

Campaign finalized successfully

Bodyapplication/json
campaignobject(Campaign)required
campaign.​campaignIdstringrequired

Unique identifier for the campaign

Example: "campaign_abc123"
campaign.​ownerUserIdstringrequired

Unique identifier for the campaign owner

Example: "user_123"
campaign.​campaignTitlestringrequired

Title of the campaign

Example: "Summer Product Launch"
campaign.​campaignDescriptionstringrequired

Description of the campaign

Example: "Promote our new summer product line to increase brand awareness"
campaign.​campaignObjectiveTypestringrequired

Objective type for the campaign

Enum"CAMPAIGN_OBJECTIVE_AWARENESS""CAMPAIGN_OBJECTIVE_ENGAGEMENT""CAMPAIGN_OBJECTIVE_CONVERSIONS"
Example: "CAMPAIGN_OBJECTIVE_AWARENESS"
campaign.​campaignCurrencyCodestringrequired

Currency code for the campaign

Enum"NGN""USD"
Example: "NGN"
campaign.​targetBudgetAmountCentsinteger or nullrequired

Target budget in cents (null if no target set)

Example: 1000000
campaign.​campaignLifeCycleStatusstringrequired

Current lifecycle status of the campaign

Enum"CAMPAIGN_DRAFT""CAMPAIGN_ACTIVE""CAMPAIGN_PAUSED""CAMPAIGN_COMPLETED""CAMPAIGN_COMPLETED_WITH_REFUND""CAMPAIGN_CANCELLED"
Example: "CAMPAIGN_ACTIVE"
campaign.​campaignStartDateTimestampstring or null(date-time)required

Campaign start date (null if not set)

Example: "2024-06-01T00:00:00Z"
campaign.​campaignEndDateTimestampstring or null(date-time)required

Campaign end date (null if not set)

Example: "2024-08-31T23:59:59Z"
campaign.​completedAtTimestampstring or null(date-time)required

When the campaign was completed (null if not yet completed)

Example: "2024-09-01T00:00:00Z"
campaign.​requirementsobjectrequired
campaign.​requirements.​requiredHashtagsArray of stringsrequired

Array of required hashtags for submissions

Example: ["#hashtag1","#hashtag2"]
campaign.​requirements.​requiredMentionsArray of stringsrequired

Array of required mentions for submissions

Example: ["@mention1","@mention2"]
campaign.​requirements.​allowedContentTypesArray of stringsrequired

Array of allowed content platform types

Items Enum"INSTAGRAM""TIKTOK""FACEBOOK""YOUTUBE"
Example: ["INSTAGRAM"]
campaign.​requirements.​submissionLimitinteger>= 1required

Maximum number of submissions allowed per participation

Example: 2
campaign.​createdAtTimestampstring(date-time)required

When the campaign was created

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

When the campaign was last updated

Example: "2024-01-01T00:00:00Z"
campaignEscrowobject(CampaignEscrow)required
campaignEscrow.​escrowIdstringrequired

Unique identifier for the escrow

Example: "escrow_xyz789"
campaignEscrow.​campaignIdstringrequired

Unique identifier for the associated campaign

Example: "campaign_abc123"
campaignEscrow.​escrowCurrencyCodestringrequired

Currency code for the escrow

Enum"NGN""USD"
Example: "NGN"
campaignEscrow.​currentEscrowBalanceAmountCentsintegerrequired

Current balance in the escrow account (cents)

Example: 500000
campaignEscrow.​totalFundedAmountCentsintegerrequired

Total amount funded into the escrow (cents)

Example: 500000
campaignEscrow.​totalReleasedAmountCentsintegerrequired

Total amount released from the escrow (cents)

Example: 0
campaignEscrow.​totalRefundedAmountCentsintegerrequired

Total amount refunded from the escrow (cents)

Example: 0
campaignEscrow.​createdAtTimestampstring(date-time)required

When the escrow was created

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

When the escrow was last updated

Example: "2024-01-01T12:00:00Z"
Response
application/json
{
  "campaign": {
    "campaignId": "campaign_abc123",
    "ownerUserId": "user_123",
    "campaignTitle": "Summer Product Launch",
    "campaignDescription": "Promote our new summer product line to increase brand awareness",
    "campaignObjectiveType": "CAMPAIGN_OBJECTIVE_AWARENESS",
    "campaignCurrencyCode": "NGN",
    "targetBudgetAmountCents": 1000000,
    "campaignLifeCycleStatus": "CAMPAIGN_COMPLETED_WITH_REFUND",
    "campaignStartDateTimestamp": "2024-06-01T00:00:00Z",
    "campaignEndDateTimestamp": "2024-08-31T23:59:59Z",
    "completedAtTimestamp": "2024-09-01T00:00:00Z",
    "requirements": { … },
    "createdAtTimestamp": "2024-01-01T00:00:00Z",
    "lastUpdatedAtTimestamp": "2024-09-01T00:00:00Z"
  },
  "campaignEscrow": {
    "escrowId": "escrow_xyz789",
    "campaignId": "campaign_abc123",
    "escrowCurrencyCode": "NGN",
    "currentEscrowBalanceAmountCents": 0,
    "totalFundedAmountCents": 500000,
    "totalReleasedAmountCents": 300000,
    "totalRefundedAmountCents": 200000,
    "createdAtTimestamp": "2024-01-01T00:00:00Z",
    "lastUpdatedAtTimestamp": "2024-09-01T00:00:00Z"
  }
}

Join a campaign as a creator

Request

Join a campaign as a creator. Creates an auto-accepted participation. Requires a valid JWT access token.

Security
bearerAuth
Path
campaignIdstringrequired

Unique identifier for the campaign

Example: campaign_abc123
Bodyapplication/json
object
curl -i -X POST \
  https://docs-staging.varmply.com/_mock/openapi/campaigns/campaign_abc123/participations \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{}'

Responses

Successfully joined the campaign

Bodyapplication/json
participationobject(Participation)required
participation.​participationIdstringrequired

Unique identifier for the participation

Example: "participation_xyz789"
participation.​campaignIdstringrequired

Unique identifier for the campaign

Example: "campaign_abc123"
participation.​influencerUserIdstringrequired

Unique identifier for the influencer user

Example: "user_123"
participation.​participationStatusstringrequired

Current status of the participation

Enum"PARTICIPATION_STATUS_PENDING""PARTICIPATION_STATUS_APPROVED""PARTICIPATION_STATUS_REJECTED""PARTICIPATION_STATUS_CONTENT_SUBMITTED""PARTICIPATION_STATUS_COMPLETED"
Example: "PARTICIPATION_STATUS_APPROVED"
participation.​contentSubmissionListArray of objects(ParticipationContentSubmission)required

List of content submissions for this participation

participation.​contentSubmissionList[].​platformTypestringrequired

Platform where the content was posted

Enum"INSTAGRAM""TIKTOK""FACEBOOK""YOUTUBE"
Example: "INSTAGRAM"
participation.​contentSubmissionList[].​contentUrlstring(uri)required

URL to the content

Example: "https://instagram.com/p/abc123"
participation.​contentSubmissionList[].​submittedAtTimestampstring(date-time)required

When the content was submitted

Example: "2024-01-01T12:00:00Z"
participation.​contentSubmissionList[].​postedAtTimestampstring or null(date-time)required

When the content was posted (null if not yet posted)

Example: "2024-01-01T12:00:00Z"
participation.​contentSubmissionList[].​declaredHashtagsArray of stringsrequired

Array of hashtags declared in the content submission

Example: ["#summer","#productlaunch"]
participation.​contentSubmissionList[].​declaredMentionsArray of stringsrequired

Array of mentions declared in the content submission

Example: ["@brand"]
participation.​contentSubmissionList[].​declaredContentTypestringrequired

Content type declared by the influencer during submission

Enum"INSTAGRAM""TIKTOK""FACEBOOK""YOUTUBE"
Example: "INSTAGRAM"
participation.​contentSubmissionList[].​submissionStatusstringrequired

Status of the submission. Submissions start as PENDING and transition to ACCEPTED or REJECTED based on campaign requirements validation.

Enum"CONTENT_SUBMISSION_STATUS_PENDING""CONTENT_SUBMISSION_STATUS_ACCEPTED""CONTENT_SUBMISSION_STATUS_REJECTED"
Example: "CONTENT_SUBMISSION_STATUS_PENDING"
participation.​contentSubmissionList[].​rejectionReasonstring or null

Reason for rejection if submissionStatus is REJECTED. Possible values: CAMPAIGN_NOT_ACTIVE, SUBMISSION_LIMIT_REACHED, CONTENT_TYPE_NOT_ALLOWED, MISSING_REQUIRED_HASHTAGS, MISSING_REQUIRED_MENTIONS, INTEGRATION_NOT_ELIGIBLE

Example: null
participation.​createdAtTimestampstring(date-time)required

When the participation was created

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

When the participation was last updated

Example: "2024-01-01T00:00:00Z"
Response
application/json
{
  "participation": {
    "participationId": "participation_xyz789",
    "campaignId": "campaign_abc123",
    "influencerUserId": "user_123",
    "participationStatus": "PARTICIPATION_STATUS_APPROVED",
    "contentSubmissionList": [],
    "createdAtTimestamp": "2024-01-01T00:00:00Z",
    "lastUpdatedAtTimestamp": "2024-01-01T00:00:00Z"
  }
}

Get campaign analytics

Request

Returns read-only campaign analytics with normalized metrics and money streams. Supports from, to, and bucket for date range and bucketing (defaults apply when omitted). Accessible by campaign owner or participants. Aggregation is based on ACCEPTED submissions only. All timestamps are in UTC (ISO 8601 format with Z suffix).

Security
bearerAuth
Path
campaignIdstringrequired

Unique identifier for the campaign

Example: campaign_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/campaigns/campaign_abc123/analytics?from=2024-01-01T00%3A00%3A00Z&to=2024-01-15T00%3A00%3A00Z&bucket=DAY' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Campaign analytics retrieved successfully

Bodyapplication/json
campaign_idstringrequired

Unique identifier for the campaign

Example: "campaign_abc123"
campaign_statestringrequired

Current lifecycle state of the campaign

Enum"CAMPAIGN_DRAFT""CAMPAIGN_ACTIVE""CAMPAIGN_PAUSED""CAMPAIGN_COMPLETED""CAMPAIGN_COMPLETED_WITH_REFUND""CAMPAIGN_CANCELLED""CAMPAIGN_ENDED_SCHEDULED""CAMPAIGN_ENDED_ESCROW_DEPLETED"
Example: "CAMPAIGN_ACTIVE"
currencystringrequired

Currency code for campaign money fields

Enum"NGN""USD"
Example: "NGN"
integration_coverageobject(CampaignIntegrationCoverageDto)required
integration_coverage.​eligible_creatorsintegerrequired
Example: 12
integration_coverage.​limitedintegerrequired
Example: 3
integration_coverage.​validintegerrequired
Example: 9
integration_coverage.​errorintegerrequired
Example: 0
integration_coverage.​not_connectedintegerrequired
Example: 0
totalsobject(AnalyticsTotalsDto)required
totals.​impressionsinteger or nullrequired
Example: 12345
totals.​reachinteger or nullrequired
Example: 9000
totals.​likesinteger or nullrequired
Example: 320
totals.​commentsinteger or nullrequired
Example: 44
totals.​sharesinteger or nullrequired
Example: null
totals.​savesinteger or nullrequired
Example: 12
totals.​viewsinteger or nullrequired
Example: null
timeseriesobject(AnalyticsTimeseriesDto)required
timeseries.​bucketstring(AnalyticsTimeseriesBucket)required

Bucket granularity for timeseries aggregation.

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

Normalized Varmply metric key.

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

Start of the aggregation window (inclusive, UTC)

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

End of the aggregation window (exclusive, UTC)

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

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

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

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

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

Source of the chart point value.

Enum"SNAPSHOT_DELTA""PLATFORM_TOTAL""ESTIMATED"
moneyobject(CampaignAnalyticsMoneyDto)required
money.​escrow_balance_centsintegerrequired
Example: 500000
money.​accrued_total_centsintegerrequired
Example: 120000
money.​paid_total_centsintegerrequired
Example: 80000
money.​blocked_total_centsintegerrequired
Example: 40000
money.​blocked_reason_codestring or nullrequired

Reason code for blocked accruals (null when blocked_total_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
{
  "campaign_id": "campaign_abc123",
  "campaign_state": "CAMPAIGN_ACTIVE",
  "currency": "NGN",
  "integration_coverage": {
    "eligible_creators": 12,
    "limited": 3,
    "valid": 9,
    "error": 0,
    "not_connected": 0
  },
  "totals": {
    "impressions": 12345,
    "reach": 9000,
    "likes": 320,
    "comments": 44,
    "shares": null,
    "saves": 12,
    "views": null
  },
  "timeseries": {
    "bucket": "DAY",
    "series": [ … ]
  },
  "money": {
    "escrow_balance_cents": 500000,
    "accrued_total_cents": 120000,
    "paid_total_cents": 80000,
    "blocked_total_cents": 40000,
    "blocked_reason_code": "INSUFFICIENT_ESCROW"
  },
  "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"
  }
}

Get participation analytics within campaign

Request

Returns read-only participation analytics within a campaign context. Accessible by campaign owner or the participation creator. Aggregates metrics from ACCEPTED submissions only and explicitly marks which submissions are counted. 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
campaignIdstringrequired

Unique identifier for the campaign

Example: campaign_abc123
participationIdstringrequired

Unique identifier for the participation

Example: participation_xyz789
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/campaigns/campaign_abc123/participations/participation_xyz789/analytics?from=2024-01-01T00%3A00%3A00Z&to=2024-01-15T00%3A00%3A00Z&bucket=DAY' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Participation analytics retrieved successfully

Bodyapplication/json
participation_idstringrequired

Unique identifier for the participation

Example: "participation_xyz789"
campaign_idstringrequired

Unique identifier for the campaign

Example: "campaign_abc123"
integration_capabilitystringrequired

Creator integration capability for this participation context

Enum"VALID""LIMITED""ERROR""NOT_CONNECTED"
Example: "VALID"
submissionsArray of objectsrequired
submissions[].​submission_idstringrequired
Example: "submission_abc123"
submissions[].​platformstringrequired
Enum"INSTAGRAM""TIKTOK""FACEBOOK""YOUTUBE"
Example: "INSTAGRAM"
submissions[].​content_urlstringrequired
Example: "https://instagram.com/p/example"
submissions[].​statusstring(AnalyticsSubmissionStatus)required
Enum"ACCEPTED""REJECTED""PENDING"
submissions[].​counted_in_aggregatebooleanrequired
Example: true
submissions[].​metricsobject(AnalyticsMetricsDto)required
submissions[].​metrics.​totalsobject(AnalyticsTotalsDto)required
submissions[].​metrics.​totals.​impressionsinteger or nullrequired
Example: 12345
submissions[].​metrics.​totals.​reachinteger or nullrequired
Example: 9000
submissions[].​metrics.​totals.​likesinteger or nullrequired
Example: 320
submissions[].​metrics.​totals.​commentsinteger or nullrequired
Example: 44
submissions[].​metrics.​totals.​sharesinteger or nullrequired
Example: null
submissions[].​metrics.​totals.​savesinteger or nullrequired
Example: 12
submissions[].​metrics.​totals.​viewsinteger or nullrequired
Example: null
submissions[].​metrics.​timeseriesobject(AnalyticsTimeseriesDto)required
submissions[].​metrics.​timeseries.​bucketstring(AnalyticsTimeseriesBucket)required

Bucket granularity for timeseries aggregation.

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

Normalized Varmply metric key.

Enum"impressions""reach""likes""comments""shares""saves""views"
submissions[].​metrics.​timeseries.​series[].​pointsArray of objects(AnalyticsTimeseriesPointDto)required
submissions[].​moneyobject(AnalyticsMoneyDto)required
submissions[].​money.​accrued_centsintegerrequired
Example: 120000
submissions[].​money.​paid_centsintegerrequired
Example: 80000
submissions[].​money.​blocked_centsintegerrequired
Example: 40000
submissions[].​money.​blocked_reason_codestring or nullrequired

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

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

Metrics status

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

Timestamp of the most recent snapshot fetchedAtTimestamp (UTC)

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

Timestamp of the most recent ingestion attempt (UTC)

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

Timestamp of the most recent successful ingestion (UTC)

Example: "2024-01-01T12:00:00Z"
submissions[].​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
submissions[].​freshness.​freshness_statusstringrequired

Freshness status of the analytics data

Enum"FRESH""STALE""UNKNOWN"
Example: "FRESH"
aggregateobjectrequired
aggregate.​by_platformArray of objectsrequired
aggregate.​by_platform[].​platformstringrequired
Enum"INSTAGRAM""TIKTOK""FACEBOOK""YOUTUBE"
Example: "INSTAGRAM"
aggregate.​by_platform[].​totalsobject(AnalyticsTotalsDto)required
aggregate.​by_platform[].​totals.​impressionsinteger or nullrequired
Example: 12345
aggregate.​by_platform[].​totals.​reachinteger or nullrequired
Example: 9000
aggregate.​by_platform[].​totals.​likesinteger or nullrequired
Example: 320
aggregate.​by_platform[].​totals.​commentsinteger or nullrequired
Example: 44
aggregate.​by_platform[].​totals.​sharesinteger or nullrequired
Example: null
aggregate.​by_platform[].​totals.​savesinteger or nullrequired
Example: 12
aggregate.​by_platform[].​totals.​viewsinteger or nullrequired
Example: null
aggregate.​by_platform[].​timeseriesobject(AnalyticsTimeseriesDto)required
aggregate.​by_platform[].​timeseries.​bucketstring(AnalyticsTimeseriesBucket)required

Bucket granularity for timeseries aggregation.

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

Normalized Varmply metric key.

Enum"impressions""reach""likes""comments""shares""saves""views"
aggregate.​by_platform[].​timeseries.​series[].​pointsArray of objects(AnalyticsTimeseriesPointDto)required
aggregate.​by_platform[].​moneyobject(AnalyticsMoneyDto)required
aggregate.​by_platform[].​money.​accrued_centsintegerrequired
Example: 120000
aggregate.​by_platform[].​money.​paid_centsintegerrequired
Example: 80000
aggregate.​by_platform[].​money.​blocked_centsintegerrequired
Example: 40000
aggregate.​by_platform[].​money.​blocked_reason_codestring or nullrequired

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

Value"INSUFFICIENT_ESCROW"
Example: "INSUFFICIENT_ESCROW"
aggregate.​overallobjectrequired
aggregate.​overall.​totalsobject(AnalyticsTotalsDto)required
aggregate.​overall.​totals.​impressionsinteger or nullrequired
Example: 12345
aggregate.​overall.​totals.​reachinteger or nullrequired
Example: 9000
aggregate.​overall.​totals.​likesinteger or nullrequired
Example: 320
aggregate.​overall.​totals.​commentsinteger or nullrequired
Example: 44
aggregate.​overall.​totals.​sharesinteger or nullrequired
Example: null
aggregate.​overall.​totals.​savesinteger or nullrequired
Example: 12
aggregate.​overall.​totals.​viewsinteger or nullrequired
Example: null
aggregate.​overall.​timeseriesobject(AnalyticsTimeseriesDto)required
aggregate.​overall.​timeseries.​bucketstring(AnalyticsTimeseriesBucket)required

Bucket granularity for timeseries aggregation.

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

Normalized Varmply metric key.

Enum"impressions""reach""likes""comments""shares""saves""views"
aggregate.​overall.​timeseries.​series[].​pointsArray of objects(AnalyticsTimeseriesPointDto)required
aggregate.​overall.​moneyobject(AnalyticsMoneyDto)required
aggregate.​overall.​money.​accrued_centsintegerrequired
Example: 120000
aggregate.​overall.​money.​paid_centsintegerrequired
Example: 80000
aggregate.​overall.​money.​blocked_centsintegerrequired
Example: 40000
aggregate.​overall.​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
{
  "participation_id": "participation_xyz789",
  "campaign_id": "campaign_abc123",
  "integration_capability": "VALID",
  "submissions": [
    { … }
  ],
  "aggregate": {
    "by_platform": [ … ],
    "overall": { … },
    "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"
  }
}

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

Notifications

User notification management endpoints

Operations

Dev

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

Operations