# Get marketplace campaigns

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.

Endpoint: GET /marketplace/campaigns
Version: 0.1.0
Security: bearerAuth

## Query parameters:

  - `platform` (string)
    Filter campaigns by allowed platform
    Enum: "INSTAGRAM", "TIKTOK"

  - `objective` (string)
    Filter campaigns by objective type
    Enum: "CAMPAIGN_OBJECTIVE_AWARENESS", "CAMPAIGN_OBJECTIVE_ENGAGEMENT", "CAMPAIGN_OBJECTIVE_CONVERSIONS"

  - `currency` (string)
    Filter campaigns by currency code
    Enum: "NGN", "USD"

  - `status` (string)
    Filter campaigns by lifecycle status (defaults to CAMPAIGN_ACTIVE if not specified)
    Enum: "CAMPAIGN_ACTIVE", "CAMPAIGN_DRAFT", "CAMPAIGN_ENDED_SCHEDULED", "CAMPAIGN_ENDED_ESCROW_DEPLETED"

  - `limit` (integer)
    Maximum number of campaigns to return (1-100, default 20)
    Example: 20

  - `cursor` (string)
    Cursor for pagination (ISO timestamp from previous response's next_cursor)
    Example: "2024-01-01T12:00:00Z"

  - `sortBy` (string)
    Sort order for campaigns
    Enum: "newest", "ending_soon", "highest_payout_rate"

  - `filterByCapability` (boolean)
    If true, only show campaigns where user has VALID or LIMITED integration capability

  - `eligible_only` (boolean)
    If true, only return campaigns where the user can join (canJoin === true)

  - `q` (string)
    Search query to filter campaigns by title or description (case-insensitive substring match)
    Example: "album tour"

## Response 200 fields (application/json):

  - `campaigns` (array, required)
    List of active campaigns available in the marketplace

  - `campaigns.campaign_id` (string, required)
    Unique identifier for the campaign
    Example: "campaign_abc123"

  - `campaigns.campaign_title` (string, required)
    Title of the campaign
    Example: "Burna Boy Album Tour Promotion"

  - `campaigns.campaign_description` (string, required)
    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_type` (string, required)
    Objective type for the campaign
    Enum: "CAMPAIGN_OBJECTIVE_AWARENESS", "CAMPAIGN_OBJECTIVE_ENGAGEMENT", "CAMPAIGN_OBJECTIVE_CONVERSIONS"

  - `campaigns.campaign_currency_code` (string, required)
    Currency code for the campaign
    Enum: "NGN", "USD"

  - `campaigns.campaign_state` (string, required)
    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"

  - `campaigns.campaign_start_date_timestamp` (string,null)
    Campaign start date (null if not set)
    Example: "2024-12-30T00:00:00Z"

  - `campaigns.campaign_end_date_timestamp` (string,null)
    Campaign end date (null if not set)
    Example: "2025-01-29T23:59:59Z"

  - `campaigns.created_at_timestamp` (string, required)
    ISO timestamp when the campaign was created
    Example: "2024-12-30T00:00:00Z"

  - `campaigns.payout_rate_amount_cents` (integer, required)
    Payout rate per unit in cents (from payout formula constants)
    Example: 10000

  - `campaigns.budget_amount_cents` (integer,null, required)
    Target budget amount in cents (from campaign targetBudgetAmountCents)
    Example: 10000000

  - `campaigns.requirements` (object, required)

  - `campaigns.requirements.allowed_platform_list` (array, required)
    List of platforms allowed for content submission
    Enum: "INSTAGRAM", "TIKTOK", "FACEBOOK", "YOUTUBE"

  - `campaigns.requirements.required_hashtag_list` (array, required)
    List of required hashtags for content submission
    Example: ["#burnaboy","#africangiant"]

  - `campaigns.requirements.required_mention_list` (array, required)
    List of required mentions for content submission
    Example: ["@burnaboy"]

  - `campaigns.requirements.submission_limit` (integer, required)
    Maximum number of submissions allowed per participation
    Example: 3

  - `campaigns.requirements.escrow_balance_amount_cents` (integer,null, required)
    Current escrow balance in cents (null if escrow not yet created)
    Example: 5000000

  - `campaigns.joinability` (object, required)

  - `campaigns.joinability.canJoin` (boolean, required)
    Whether the current user can join this campaign
    Example: true

  - `campaigns.joinability.reasons` (array, required)
    Array of reason codes if the user cannot join (empty array if can join)
    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"

  - `next_cursor` (string,null, 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 400 fields (application/json):

  - `error` (string, required)
    Error code that identifies the type of error. This is a stable identifier that can be used
for programmatic error handling. Common codes include:
- NOT_FOUND - Resource not found
- VALIDATION_ERROR - Input validation failed
- PERMISSION_DENIED - User lacks permission for the action
- CONFLICT - Request conflicts with current resource state
- UNAUTHORIZED - Authentication required
- INTERNAL_SERVER_ERROR - Unexpected server error
    Example: "VALIDATION_ERROR"

  - `message` (string, required)
    User-friendly error message that should always be displayed to end users. This message is
designed to be clear, actionable, and free of technical details.

This field is always present and contains the primary message for end users.
    Example: "The email address you entered is not valid. Please check the format and try again."

  - `technicalMessage` (string)
    Optional technical message for developers. Contains detailed information including IDs,
error codes, and technical context. Only included when it differs from the user-friendly
message field. When present, developers can use this for debugging while end users
should see the message field.
    Example: "Campaign with ID campaign_123 not found"

  - `details` (object)
    Additional error details (optional). May contain structured information about the error,
such as validation field errors or additional context.

  - `requestId` (string)
    Unique request identifier for tracing. Included in X-Request-ID header and can be used
to correlate errors with server logs.
    Example: "550e8400-e29b-41d4-a716-446655440000"

  - `timestamp` (string, required)
    ISO 8601 timestamp when the error occurred
    Example: "2024-01-01T00:00:00Z"

## Response 401 fields (application/json):

  - `error` (string, required)
    Error code that identifies the type of error. This is a stable identifier that can be used
for programmatic error handling. Common codes include:
- NOT_FOUND - Resource not found
- VALIDATION_ERROR - Input validation failed
- PERMISSION_DENIED - User lacks permission for the action
- CONFLICT - Request conflicts with current resource state
- UNAUTHORIZED - Authentication required
- INTERNAL_SERVER_ERROR - Unexpected server error
    Example: "VALIDATION_ERROR"

  - `message` (string, required)
    User-friendly error message that should always be displayed to end users. This message is
designed to be clear, actionable, and free of technical details.

This field is always present and contains the primary message for end users.
    Example: "The email address you entered is not valid. Please check the format and try again."

  - `technicalMessage` (string)
    Optional technical message for developers. Contains detailed information including IDs,
error codes, and technical context. Only included when it differs from the user-friendly
message field. When present, developers can use this for debugging while end users
should see the message field.
    Example: "Campaign with ID campaign_123 not found"

  - `details` (object)
    Additional error details (optional). May contain structured information about the error,
such as validation field errors or additional context.

  - `requestId` (string)
    Unique request identifier for tracing. Included in X-Request-ID header and can be used
to correlate errors with server logs.
    Example: "550e8400-e29b-41d4-a716-446655440000"

  - `timestamp` (string, required)
    ISO 8601 timestamp when the error occurred
    Example: "2024-01-01T00:00:00Z"