Social Perks

Get the market-rate pricing for a marketing action. Returns USD value and recommended perk type/value.

{
  "type": "object",
  "properties": {
    "actionId": {
      "type": "string",
      "description": "Action ID (e.g. ig_post, google_review)"
    },
    "platformId": {
      "type": "string",
      "description": "Platform ID (e.g. instagram, google)"
    },
    "businessType": {
      "type": "string",
      "description": "Business type modifier (default: general)"
    }
  }
}

List the 125 marketing actions available on Social Perks. Filterable by platform, type, and effort.

{
  "type": "object",
  "properties": {
    "platformId": {
      "type": "string"
    },
    "type": {
      "type": "string",
      "enum": [
        "content",
        "review",
        "engage",
        "share",
        "referral"
      ]
    },
    "maxEffort": {
      "type": "integer",
      "minimum": 0,
      "maximum": 5
    },
    "page": {
      "type": "integer",
      "default": 1
    },
    "perPage": {
      "type": "integer",
      "default": 50
    }
  }
}

Get industry benchmarks (engagement rate, conversion rate, etc.) for a business type.

{
  "type": "object",
  "properties": {
    "businessType": {
      "type": "string",
      "description": "Industry name or slug (e.g. 'restaurants', 'coffee-shops'). Omit for the full catalog."
    }
  }
}

List campaigns. Requires auth — returns the caller's campaigns.

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "draft",
        "active",
        "paused",
        "completed"
      ]
    }
  }
}

Search influencers by platform and follower count.

{
  "type": "object",
  "properties": {
    "platform": {
      "type": "string"
    },
    "minFollowers": {
      "type": "integer"
    }
  }
}

Create and launch a new campaign for the calling business. Returns the campaign id, name, and dashboard URL. The campaign goes live immediately — no separate publish step.

{
  "type": "object",
  "properties": {
    "businessId": {
      "type": "string",
      "description": "The business owning this campaign. Must match the API key's business."
    },
    "name": {
      "type": "string",
      "description": "Customer-facing campaign name",
      "maxLength": 200
    },
    "description": {
      "type": "string",
      "description": "Optional internal description"
    },
    "actions": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "minItems": 1,
      "description": "Action IDs the campaign accepts (e.g. ['ig_st'] for an Instagram Story Tag)."
    },
    "discountValue": {
      "type": "number",
      "minimum": 0.01,
      "description": "Discount amount. Capped at 100 for pct, 10000 for dol."
    },
    "discountType": {
      "type": "string",
      "enum": [
        "pct",
        "dol"
      ],
      "description": "Discount denomination: 'pct' for percentage, 'dol' for dollars off."
    },
    "maxCompletions": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Optional cap on total completions. Null = no cap."
    },
    "expiresInDays": {
      "type": "integer",
      "minimum": 1,
      "maximum": 365,
      "description": "Days until the campaign auto-expires. Default 60."
    }
  },
  "required": [
    "businessId",
    "name",
    "actions",
    "discountValue",
    "discountType"
  ]
}

Submit proof of completion for a campaign action — a public URL to a post, a screenshot, a video, or platform-verified data. The submission enters a review queue (or auto-approves depending on the campaign's verification mode).

{
  "type": "object",
  "properties": {
    "campaignId": {
      "type": "string",
      "description": "Campaign the submission applies to."
    },
    "actionId": {
      "type": "string",
      "description": "Specific action being completed (must be allowed by the campaign)."
    },
    "proofUrl": {
      "type": "string",
      "description": "Public URL of the proof. For url-type submissions, the platform verifier will fetch this.",
      "maxLength": 2048
    },
    "proofType": {
      "type": "string",
      "enum": [
        "screenshot",
        "url",
        "video",
        "api_verified"
      ],
      "description": "How the proof was captured. 'url' triggers automated verification."
    },
    "metadata": {
      "type": "object",
      "description": "Optional bag of context (poster handle, post timestamp, etc.).",
      "additionalProperties": true
    }
  },
  "required": [
    "campaignId",
    "actionId",
    "proofUrl",
    "proofType"
  ]
}

Approve or reject a submission. Approving releases the perk; rejecting requires a reason. Use this when the business chooses manual review over auto-verification.

{
  "type": "object",
  "properties": {
    "submissionId": {
      "type": "string",
      "description": "Submission id from a prior submitProof call."
    },
    "decision": {
      "type": "string",
      "enum": [
        "approve",
        "reject"
      ],
      "description": "Approve releases the perk. Reject explains why the proof was insufficient."
    },
    "reason": {
      "type": "string",
      "description": "Required when decision='reject'. 1-500 chars.",
      "maxLength": 500
    }
  },
  "required": [
    "submissionId",
    "decision"
  ]
}

List submissions for a business or campaign, filterable by state (pending/approved/rejected). Returns paginated results.

{
  "type": "object",
  "properties": {
    "businessId": {
      "type": "string"
    },
    "campaignId": {
      "type": "string"
    },
    "state": {
      "type": "string",
      "enum": [
        "pending",
        "approved",
        "rejected"
      ]
    },
    "page": {
      "type": "integer",
      "minimum": 1,
      "default": 1
    },
    "perPage": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 25
    }
  }
}

Get summary stats for a single campaign — total submissions, approved count, conversion rate, perks issued, and time-to-first-submission. Useful for an agent reporting back to its user.

{
  "type": "object",
  "properties": {
    "campaignId": {
      "type": "string",
      "description": "Campaign to fetch stats for."
    }
  },
  "required": [
    "campaignId"
  ]
}