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

Get participation details with submission tracking

Request

Retrieve detailed information about a participation including submission tracking status. Returns campaign info, participation record, and tracking status for each submission. Requires authentication - accessible to both the influencer and campaign owner.

Security
bearerAuth
Path
participationIdstringrequired

Unique identifier for the participation

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

Responses

Participation details retrieved successfully

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"
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"
submission_tracking_summaryobjectrequired
submission_tracking_summary.​submission_limitintegerrequired

Maximum number of submissions that can be tracked for metrics

Example: 3
submission_tracking_summary.​accepted_submission_countintegerrequired

Total number of accepted submissions

Example: 5
submission_tracking_summary.​tracked_submission_countintegerrequired

Number of submissions currently being tracked for metrics

Example: 3
submission_tracking_listArray of objectsrequired
submission_tracking_list[].​submission_idstringrequired

Unique identifier for the submission

Example: "submission_abc123"
submission_tracking_list[].​is_trackedbooleanrequired

Whether this submission is being tracked for metrics

Example: true
submission_tracking_list[].​tracking_reasonstringrequired

Reason for the tracking status

Enum"SUBMISSION_TRACKING_WITHIN_LIMIT""SUBMISSION_TRACKING_OVER_LIMIT""SUBMISSION_TRACKING_NOT_ACCEPTED""SUBMISSION_TRACKING_INELIGIBLE_INTEGRATION""SUBMISSION_TRACKING_CAMPAIGN_NOT_ACTIVE""SUBMISSION_TRACKING_MISSING_EXTERNAL_MEDIA_ID""SUBMISSION_TRACKING_PLATFORM_NOT_SUPPORTED"
Example: "SUBMISSION_TRACKING_WITHIN_LIMIT"
Response
application/json
{
  "participation": {
    "participationId": "participation_xyz789",
    "campaignId": "campaign_abc123",
    "influencerUserId": "user_123",
    "participationStatus": "PARTICIPATION_STATUS_CONTENT_SUBMITTED",
    "contentSubmissionList": [],
    "createdAtTimestamp": "2024-01-01T00:00:00Z",
    "lastUpdatedAtTimestamp": "2024-01-01T12:00:00Z"
  },
  "campaign": {
    "campaignId": "campaign_abc123",
    "campaignTitle": "Summer Campaign",
    "campaignDescription": "Summer product launch",
    "campaignLifeCycleStatus": "CAMPAIGN_ACTIVE"
  },
  "submission_tracking_summary": {
    "submission_limit": 3,
    "accepted_submission_count": 5,
    "tracked_submission_count": 3
  },
  "submission_tracking_list": [
    { … },
    { … }
  ]
}

Submit content for a participation

Request

Submit content (e.g., Instagram post, TikTok video) for a participation. Creates a submission with PENDING status. Requires a valid JWT access token. Only the influencer who owns the participation can submit content.

Security
bearerAuth
Path
participationIdstringrequired

Unique identifier for the participation

Example: participation_xyz789
Bodyapplication/jsonrequired
content_urlstring(uri)required

URL to the content

Example: "https://instagram.com/p/abc123"
platformstringrequired

Platform where the content was posted

Enum"INSTAGRAM""TIKTOK""FACEBOOK""YOUTUBE"
Example: "INSTAGRAM"
posted_at_timestampstring or null(date-time)

When the content was posted (optional)

Example: "2024-01-01T12:00:00Z"
declared_hashtagsArray of strings

Array of hashtags declared in the content submission

Default []
Example: ["#summer","#productlaunch"]
declared_mentionsArray of strings

Array of mentions declared in the content submission

Default []
Example: ["@brand"]
curl -i -X POST \
  https://docs-staging.varmply.com/_mock/openapi/participations/participation_xyz789/submissions \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "content_url": "https://instagram.com/p/abc123",
    "platform": "INSTAGRAM",
    "posted_at_timestamp": "2024-01-01T12:00:00Z",
    "declared_hashtags": [
      "#summer",
      "#productlaunch"
    ],
    "declared_mentions": [
      "@brand"
    ]
  }'

Responses

Content submitted successfully (submission created with PENDING status)

Bodyapplication/json
submissionobjectrequired
submission.​submission_idstringrequired
Example: "submission_xyz789"
submission.​participation_idstringrequired
Example: "participation_xyz789"
submission.​content_urlstring(uri)required
Example: "https://instagram.com/p/abc123"
submission.​platformstringrequired
Enum"INSTAGRAM""TIKTOK""FACEBOOK""YOUTUBE"
Example: "INSTAGRAM"
submission.​submission_statusstringrequired
Enum"PENDING""ACCEPTED""REJECTED"
Example: "PENDING"
submission.​rejection_reasonstring or nullrequired
Example: null
submission.​submitted_at_timestampstring(date-time)required
Example: "2024-01-01T12:00:00Z"
participationobjectrequired
participation.​participation_idstringrequired
Example: "participation_xyz789"
participation.​participation_statusstringrequired
Example: "PARTICIPATION_STATUS_PENDING"
Response
application/json
{
  "submission": {
    "submission_id": "submission_xyz789",
    "participation_id": "participation_xyz789",
    "content_url": "https://instagram.com/p/abc123",
    "platform": "INSTAGRAM",
    "submission_status": "PENDING",
    "rejection_reason": null,
    "submitted_at_timestamp": "2024-01-01T12:00:00Z"
  },
  "participation": {
    "participation_id": "participation_xyz789",
    "participation_status": "PARTICIPATION_STATUS_PENDING"
  }
}

Review submission (approve or reject)

Request

Sponsor reviews a submission with APPROVE or REJECT action. Only the campaign owner can review submissions. Requires a valid JWT access token. Submission must be in PENDING status.

Security
bearerAuth
Path
submissionIdstringrequired

Unique identifier for the submission

Example: submission_xyz789
Bodyapplication/jsonrequired
actionstringrequired

Review action to take

Enum"APPROVE""REJECT"
Example: "APPROVE"
reasonstring

Optional reason for rejection (required when action is REJECT)

Example: "Content does not meet campaign requirements"
curl -i -X POST \
  https://docs-staging.varmply.com/_mock/openapi/submissions/submission_xyz789/review \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "action": "APPROVE"
  }'

Responses

Submission reviewed successfully

Bodyapplication/json
submission_idstringrequired
Example: "submission_xyz789"
participation_idstringrequired
Example: "participation_xyz789"
submission_statusstringrequired
Enum"PENDING""ACCEPTED""REJECTED"
Example: "ACCEPTED"
rejection_reasonstring or nullrequired
Example: null
participation_statusstringrequired
Example: "PARTICIPATION_STATUS_APPROVED"
Response
application/json
{
  "submission_id": "submission_xyz789",
  "participation_id": "participation_xyz789",
  "submission_status": "ACCEPTED",
  "rejection_reason": null,
  "participation_status": "PARTICIPATION_STATUS_APPROVED"
}

Approve participation content (legacy endpoint)

Request

Legacy endpoint for approving submitted content for a participation. Only the campaign owner can approve content. Requires a valid JWT access token. Note: This endpoint is maintained for backward compatibility. New implementations should use POST /submissions/{submissionId}/review instead.

Security
bearerAuth
Path
participationIdstringrequired

Unique identifier for the participation

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

Responses

Content approved successfully

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-01T13:00:00Z"
  }
}

Mark participation as completed

Request

Mark a participation as completed. Only the campaign owner can mark participations as completed. Requires a valid JWT access token.

Security
bearerAuth
Path
participationIdstringrequired

Unique identifier for the participation

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

Responses

Participation marked as completed successfully

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_COMPLETED",
    "contentSubmissionList": [ … ],
    "createdAtTimestamp": "2024-01-01T00:00:00Z",
    "lastUpdatedAtTimestamp": "2024-01-01T14:00:00Z"
  }
}

Get participation analytics

Request

Returns read-only participation analytics for the authenticated user. Only accessible by 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
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/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": null,
    "last_attempt_at": null,
    "last_success_at": null,
    "last_failure_reason": null,
    "freshness_status": "STALE"
  }
}

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