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

Get marketplace campaigns

Request

Retrieve a list of campaigns available in the marketplace with joinability projections for the current user. This is a read-only endpoint that returns campaigns with their requirements and per-user joinability information. Supports filtering by platform, objective, currency, and status. Results are paginated using cursor-based pagination. Requires a valid JWT access token.

Security
bearerAuth
Query
platformstring

Filter campaigns by allowed platform

Enum"INSTAGRAM""TIKTOK"
Example: platform=INSTAGRAM
objectivestring

Filter campaigns by objective type

Enum"CAMPAIGN_OBJECTIVE_AWARENESS""CAMPAIGN_OBJECTIVE_ENGAGEMENT""CAMPAIGN_OBJECTIVE_CONVERSIONS"
Example: objective=CAMPAIGN_OBJECTIVE_ENGAGEMENT
currencystring

Filter campaigns by currency code

Enum"NGN""USD"
Example: currency=NGN
statusstring

Filter campaigns by lifecycle status (defaults to CAMPAIGN_ACTIVE if not specified)

Enum"CAMPAIGN_ACTIVE""CAMPAIGN_DRAFT""CAMPAIGN_ENDED_SCHEDULED""CAMPAIGN_ENDED_ESCROW_DEPLETED"
Example: status=CAMPAIGN_ACTIVE
limitinteger[ 1 .. 100 ]

Maximum number of campaigns to return (1-100, default 20)

Default 20
Example: limit=20
cursorstring(date-time)

Cursor for pagination (ISO timestamp from previous response's next_cursor)

Example: cursor=2024-01-01T12:00:00Z
sortBystring

Sort order for campaigns

Default "newest"
Enum"newest""ending_soon""highest_payout_rate"
Example: sortBy=newest
filterByCapabilityboolean

If true, only show campaigns where user has VALID or LIMITED integration capability

Default false
Example: filterByCapability=false
eligible_onlyboolean

If true, only return campaigns where the user can join (canJoin === true)

Default false
Example: eligible_only=false
qstring

Search query to filter campaigns by title or description (case-insensitive substring match)

Example: q=album tour
curl -i -X GET \
  'https://docs-staging.varmply.com/_mock/openapi/marketplace/campaigns?platform=INSTAGRAM&objective=CAMPAIGN_OBJECTIVE_ENGAGEMENT&currency=NGN&status=CAMPAIGN_ACTIVE&limit=20&cursor=2024-01-01T12%3A00%3A00Z&sortBy=newest&filterByCapability=false&eligible_only=false&q=album+tour' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Successfully retrieved marketplace campaigns

Bodyapplication/json
campaignsArray of objects(MarketplaceCampaignDTO)required

List of active campaigns available in the marketplace

campaigns[].​campaign_idstringrequired

Unique identifier for the campaign

Example: "campaign_abc123"
campaigns[].​campaign_titlestringrequired

Title of the campaign

Example: "Burna Boy Album Tour Promotion"
campaigns[].​campaign_descriptionstringrequired

Description of the campaign

Example: "Promote my upcoming album tour dates across Nigeria. Need influencers to create hype content with specific hashtags and mentions."
campaigns[].​campaign_objective_typestringrequired

Objective type for the campaign

Enum"CAMPAIGN_OBJECTIVE_AWARENESS""CAMPAIGN_OBJECTIVE_ENGAGEMENT""CAMPAIGN_OBJECTIVE_CONVERSIONS"
Example: "CAMPAIGN_OBJECTIVE_ENGAGEMENT"
campaigns[].​campaign_currency_codestringrequired

Currency code for the campaign

Enum"NGN""USD"
Example: "NGN"
campaigns[].​campaign_statestringrequired

Current lifecycle status of the campaign. Note: The marketplace endpoints only return campaigns with status CAMPAIGN_ACTIVE by default. The enum includes all possible campaign states for type safety, but marketplace filtering ensures only ACTIVE campaigns are visible.

Enum"CAMPAIGN_ACTIVE""CAMPAIGN_DRAFT""CAMPAIGN_ENDED_SCHEDULED""CAMPAIGN_ENDED_ESCROW_DEPLETED"
Example: "CAMPAIGN_ACTIVE"
campaigns[].​campaign_start_date_timestampstring or null(date-time)

Campaign start date (null if not set)

Example: "2024-12-30T00:00:00Z"
campaigns[].​campaign_end_date_timestampstring or null(date-time)

Campaign end date (null if not set)

Example: "2025-01-29T23:59:59Z"
campaigns[].​created_at_timestampstring(date-time)required

ISO timestamp when the campaign was created

Example: "2024-12-30T00:00:00Z"
campaigns[].​payout_rate_amount_centsintegerrequired

Payout rate per unit in cents (from payout formula constants)

Example: 10000
campaigns[].​budget_amount_centsinteger or nullrequired

Target budget amount in cents (from campaign targetBudgetAmountCents)

Example: 10000000
campaigns[].​requirementsobject(MarketplaceCampaignRequirements)required
campaigns[].​requirements.​allowed_platform_listArray of stringsrequired

List of platforms allowed for content submission

Items Enum"INSTAGRAM""TIKTOK""FACEBOOK""YOUTUBE"
Example: ["INSTAGRAM","TIKTOK","FACEBOOK"]
campaigns[].​requirements.​required_hashtag_listArray of stringsrequired

List of required hashtags for content submission

Example: ["#burnaboy","#africangiant"]
campaigns[].​requirements.​required_mention_listArray of stringsrequired

List of required mentions for content submission

Example: ["@burnaboy"]
campaigns[].​requirements.​submission_limitintegerrequired

Maximum number of submissions allowed per participation

Example: 3
campaigns[].​requirements.​escrow_balance_amount_centsinteger or nullrequired

Current escrow balance in cents (null if escrow not yet created)

Example: 5000000
campaigns[].​joinabilityobject(JoinabilityProjection)required
campaigns[].​joinability.​canJoinbooleanrequired

Whether the current user can join this campaign

Example: true
campaigns[].​joinability.​reasonsArray of stringsrequired

Array of reason codes if the user cannot join (empty array if can join)

Items Enum"NOT_AUTHENTICATED""EMAIL_NOT_VERIFIED""NOT_A_CREATOR""CREATOR_PROFILE_INCOMPLETE""NO_ELIGIBLE_INTEGRATION""CAMPAIGN_NOT_ACTIVE""CAMPAIGN_NOT_IN_WINDOW""ESCROW_DEPLETED""ALREADY_JOINED""SUBMISSION_LIMIT_REACHED"
Example: []
next_cursorstring or null(date-time)required

ISO timestamp cursor for pagination. Use this value as the cursor query parameter in the next request to fetch more campaigns. Null if there are no more campaigns.

Example: "2024-12-30T01:00:00Z"
Response
application/json
{
  "campaigns": [
    { … }
  ],
  "next_cursor": "2024-12-30T01:00:00Z"
}

Get marketplace campaign detail

Request

Retrieve detailed information about a specific campaign in the marketplace, including joinability projection for the current user. This is a read-only endpoint that returns campaign details with per-user joinability information. 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/marketplace/campaigns/campaign_abc123 \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Successfully retrieved marketplace campaign detail

Bodyapplication/json
campaign_idstringrequired

Unique identifier for the campaign

Example: "campaign_abc123"
campaign_titlestringrequired

Title of the campaign

Example: "Burna Boy Album Tour Promotion"
campaign_descriptionstringrequired

Description of the campaign

Example: "Promote my upcoming album tour dates across Nigeria. Need influencers to create hype content with specific hashtags and mentions."
campaign_objective_typestringrequired

Objective type for the campaign

Enum"CAMPAIGN_OBJECTIVE_AWARENESS""CAMPAIGN_OBJECTIVE_ENGAGEMENT""CAMPAIGN_OBJECTIVE_CONVERSIONS"
Example: "CAMPAIGN_OBJECTIVE_ENGAGEMENT"
campaign_currency_codestringrequired

Currency code for the campaign

Enum"NGN""USD"
Example: "NGN"
campaign_statestringrequired

Current lifecycle status of the campaign. Note: The marketplace endpoints only return campaigns with status CAMPAIGN_ACTIVE by default. The enum includes all possible campaign states for type safety, but marketplace filtering ensures only ACTIVE campaigns are visible.

Enum"CAMPAIGN_ACTIVE""CAMPAIGN_DRAFT""CAMPAIGN_ENDED_SCHEDULED""CAMPAIGN_ENDED_ESCROW_DEPLETED"
Example: "CAMPAIGN_ACTIVE"
campaign_start_date_timestampstring or null(date-time)

Campaign start date (null if not set)

Example: "2024-12-30T00:00:00Z"
campaign_end_date_timestampstring or null(date-time)

Campaign end date (null if not set)

Example: "2025-01-29T23:59:59Z"
created_at_timestampstring(date-time)required

ISO timestamp when the campaign was created

Example: "2024-12-30T00:00:00Z"
payout_rate_amount_centsintegerrequired

Payout rate per unit in cents (from payout formula constants)

Example: 10000
budget_amount_centsinteger or nullrequired

Target budget amount in cents (from campaign targetBudgetAmountCents)

Example: 10000000
requirementsobject(MarketplaceCampaignRequirements)required
requirements.​allowed_platform_listArray of stringsrequired

List of platforms allowed for content submission

Items Enum"INSTAGRAM""TIKTOK""FACEBOOK""YOUTUBE"
Example: ["INSTAGRAM","TIKTOK","FACEBOOK"]
requirements.​required_hashtag_listArray of stringsrequired

List of required hashtags for content submission

Example: ["#burnaboy","#africangiant"]
requirements.​required_mention_listArray of stringsrequired

List of required mentions for content submission

Example: ["@burnaboy"]
requirements.​submission_limitintegerrequired

Maximum number of submissions allowed per participation

Example: 3
requirements.​escrow_balance_amount_centsinteger or nullrequired

Current escrow balance in cents (null if escrow not yet created)

Example: 5000000
joinabilityobject(JoinabilityProjection)required
joinability.​canJoinbooleanrequired

Whether the current user can join this campaign

Example: true
joinability.​reasonsArray of stringsrequired

Array of reason codes if the user cannot join (empty array if can join)

Items Enum"NOT_AUTHENTICATED""EMAIL_NOT_VERIFIED""NOT_A_CREATOR""CREATOR_PROFILE_INCOMPLETE""NO_ELIGIBLE_INTEGRATION""CAMPAIGN_NOT_ACTIVE""CAMPAIGN_NOT_IN_WINDOW""ESCROW_DEPLETED""ALREADY_JOINED""SUBMISSION_LIMIT_REACHED"
Example: []
Response
application/json
{
  "campaign_id": "campaign_abc123",
  "campaign_title": "Burna Boy Album Tour Promotion",
  "campaign_description": "Promote my upcoming album tour dates across Nigeria. Need influencers to create hype content with specific hashtags and mentions.",
  "campaign_objective_type": "CAMPAIGN_OBJECTIVE_ENGAGEMENT",
  "campaign_currency_code": "NGN",
  "campaign_state": "CAMPAIGN_ACTIVE",
  "campaign_start_date_timestamp": "2024-12-30T00:00:00Z",
  "campaign_end_date_timestamp": "2025-01-29T23:59:59Z",
  "created_at_timestamp": "2024-12-30T00:00:00Z",
  "payout_rate_amount_cents": 10000,
  "budget_amount_cents": 10000000,
  "requirements": {
    "allowed_platform_list": [ … ],
    "required_hashtag_list": [ … ],
    "required_mention_list": [ … ],
    "submission_limit": 3,
    "escrow_balance_amount_cents": 5000000
  },
  "joinability": {
    "canJoin": true,
    "reasons": []
  }
}

Join a marketplace campaign

Request

Allow a creator to join a campaign from the marketplace. This endpoint uses MarketplaceJoinabilityEvaluator for consistency with GET /marketplace/campaigns/:id. Returns the created/updated participation with joinability snapshot. Handles idempotency: joining twice returns the existing participation. Requires authentication and creator role with verified email.

Security
bearerAuth
Path
campaignIdstringrequired

Unique identifier for the campaign

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

Responses

Successfully joined campaign or already joined (idempotent)

Bodyapplication/json
participation_idstringrequired

Unique identifier for the participation

Example: "participation_xyz789"
campaign_idstringrequired

Unique identifier for the campaign

Example: "campaign_abc123"
influencer_user_idstringrequired

Unique identifier for the influencer/creator user

Example: "user_123"
participation_statusstringrequired

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"
created_at_timestampstring(date-time)required

ISO timestamp when the participation was created

Example: "2024-01-01T00:00:00Z"
joinabilityobject(JoinabilityProjection)required
joinability.​canJoinbooleanrequired

Whether the current user can join this campaign

Example: true
joinability.​reasonsArray of stringsrequired

Array of reason codes if the user cannot join (empty array if can join)

Items Enum"NOT_AUTHENTICATED""EMAIL_NOT_VERIFIED""NOT_A_CREATOR""CREATOR_PROFILE_INCOMPLETE""NO_ELIGIBLE_INTEGRATION""CAMPAIGN_NOT_ACTIVE""CAMPAIGN_NOT_IN_WINDOW""ESCROW_DEPLETED""ALREADY_JOINED""SUBMISSION_LIMIT_REACHED"
Example: []
Response
application/json
{
  "participation_id": "participation_xyz789",
  "campaign_id": "campaign_abc123",
  "influencer_user_id": "user_123",
  "participation_status": "PARTICIPATION_STATUS_APPROVED",
  "created_at_timestamp": "2024-01-01T00:00:00Z",
  "joinability": {
    "canJoin": false,
    "reasons": [ … ]
  }
}

Join a campaign (Marketplace)

Request

Allow a creator to attempt to join a campaign via the marketplace. This endpoint uses the eligibility evaluator to determine if the creator can participate. Returns 200 OK with either:

  • eligible: true and participation object if eligible
  • eligible: false with reasonCode and optional metadata if ineligible No HTTP 400s for business rules - all outcomes return 200 with structured response. 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/join \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{}'

Responses

Join attempt result (eligible or ineligible)

Bodyapplication/json
One of:
eligiblebooleanrequired
Valuetrue
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
{
  "eligible": true,
  "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"
  }
}

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