Campaign API Overview

Co:Create's Campaign API aims to simplify the creation and management of reward campaigns by offering built-in business logic, resulting in improved user insights on how your web3 program is driving business value.

Campaigns form an integral part of user engagement and retention strategies. They offer a way to reward users for taking specific actions, thus encouraging desired behaviors and fostering a sense of loyalty. However, designing and managing these campaigns can be a complex and time-consuming process. This is where Co:Create's Campaign API can help.

Streamlined Development Process

The Campaign API is designed to simplify the creation and management of reward campaigns. By offering built-in business logic, the API eliminates the need for you to build additional application logic yourself, saving significant time and resources. They are built on the foundation of Co:Create Platform's existing user and token management capabilities.

Imagine, for instance, a scenario where you're tasked with creating a system to reward users with tokens for following your brand on Twitter. Traditionally, this would involve setting up a Twitter developer account, implementing the OAuth connection flow within your application, integrating the Twitter API to check the user is following your account, and then distributing the token rewards by minting tokens to the user wallet. With the Campaign API, this process is streamlined - developers can easily set up the campaign, and the APIs will handle the tracking, validation, and reward distribution.

Enhanced User Insights

The value of the Campaign API extends beyond just simplifying the development process. The API is designed to provide valuable insights about end users to Co:Create Platform's developers. By leveraging the Campaign API, businesses can gain a better understanding of their users' behaviors and preferences. This, in turn, can inform strategic business decisions and help optimize future campaigns.

For instance, using the Campaign API, a business could discover that users are more likely to invite friends to join the platform when a certain type of reward is offered. This insight could help the business refine its reward strategy to further boost user referrals.

Campaign Structure

Campaigns are created by you, with rewards claimed by your users (when eligible).

Campaigns are structured around two main fundamental objects: Conditions & Actions.

When creating a campaign, you will decide the type of condition you would like to have the user meet. You will also decide on the action which you want to take place as a user claims the campaign.

Campaign Conditions

You can set the following conditions on a campaign:

Condition	Description
sign_up	Reward a user for signing up for your community or program.
profile_update	Reward a user for providing their name, address, or phone number. Choose one, two, or three criteria for reward claims.
token_gated	Reward a user for holding tokens of a specified token contract -- ERC-20, ERC-721, or ERC-1155. Supports Ethereum, Polygon, and Gnosis Chain.
general	Create a flexible general campaign in which the frequency of reward claims is more important than user actions like signing up or sharing a link. Set the claim_frequency to once (default), daily, or unlimited. When making a claim request for an unlimited campaign, you can set an idempotency_key to prevent duplicate claims. For more information, see Claims for General Campaigns.
twitter_social_link	Reward a user for connecting their Twitter account to their Co:Create profile. (Requires use of the Co:Create SDK.)
discord_social_link	Reward a user for connecting their Discord account to their Co:Create profile. (Requires use of the Co:Create SDK.)
instagram_social_link	Reward a user for connecting their Instagram account to their Co:Create profile. (Requires use of the Co:Create SDK.)
unverified_social_link	Reward users for social posts without specifying a social platform or verifying an account.
referral	Reward existing users and new users with a referral program. For more information, see 👥 Referrals.
manual_social_post (content creation)	Reward users for including specific content in social posts, such as a hashtag or media. Either a hashtag or tag is required; if you omit both, an error is returned. In manual social post campaigns, reward claims must be verified manually. Payouts are processed as soon as your organization approves the claim.

The various conditions reflect common user engagement scenarios, so you can quickly spin up the right type of campaign. For complete parameter details, try out a Create Campaign request in the interactive API reference.

Campaign Actions

The current version of the Campaign API supports two actions: mint and dualmint.

Workflow

Here's a high-level summary of the campaign workflow:

1. Create a campaign: Define the condition and action using the available parameters.
2. Verify user eligibility: Provide the campaign ID and the claimant's email address to check whether the user has met the conditions of the campaign and can claim a reward.
3. Claim a campaign reward for a user: Provide the campaign ID and the claimant's email address to trigger the campaign action.

Endpoints

The base URL for the Campaign API is /alpha/campaign.

Click an endpoint to see details in the interactive API reference.

For more information about the /pause, /resume, and /cancel endpoints, see Campaign State Management.

Create a Campaign

To create a campaign, make a POST request to /alpha/campaign with the body parameters listed below.

Request Body Parameters

The main body of the request has the following parameters.

Use the following parameters to define the campaign conditions and actions:

Condition

Action

Example Request: Create a Campaign

curl --request POST \
     --url https://api.testcocrt.xyz/alpha/campaign \
     --header 'Authorization: Bearer <YOUR_KEY_HERE>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "condition": {
    "type": "sign_up",
    "name": "Sign up for my test",
    "description": "Description for signing up for my test"
  },
  "action": {
    "type": "mint",
    "token_type": "erc20",
    "id": "782f9579-6674-4b42-b4bf-49ef0079d64e",
    "payout_amount": 123
  },
  "title": "Campaign Test 1",
  "subtitle": "Testing my first campaign",
  "description": "Description for testing my first campaign"
}
'

Example Response: Create a Campaign

A successful request returns a 200 OK response with a JSON object containing the campaignId of the newly created campaign.

Example 200 Response

{
  "data": {
    "id": "a158c590-f7eb-4bf7-9442-3c8a80f60855",
    "title": "Campaign Test 1",
    "subtitle": "Testing my first campaign",
    "description": "Description for testing my first campaign",
    "media_url": "",
    "action": {
      "type": "mint",
      "token_type": "erc20",
      "id": "782f9579-6674-4b42-b4bf-49ef0079d64e",
      "payout_amount": 123
    },
    "condition": {
      "type": "sign_up",
      "name": "Sign up for my test",
      "description": "Description for signing up for my test"
    }
  }
}

Verify Campaign Eligibility

Before claiming a campaign reward on behalf of a user, you can check the user's eligibility with the /verify endpoint. You can optionally use this request to share eligibility details with the user, so they can better understand the campaign and address any issues.

To verify a user's eligibility to claim a campaign reward, make a GET request to /alpha/campaign/{campaign_id}/verify. Include the campaign_id as a path parameter and the claimant's email as a query parameter.

📘

Verifying manual social post campaigns

Social post / content creation campaigns must be verified outside of the Co:Create platform. You'll need to manually verify each potentially eligible post, to make sure it contains a tag and any media required by the campaign condition.

Eligibility responses also includes the user's claim_history.

Example Request: Verify Eligibility

curl --request GET \
     --url 'https://api.testcocrt.xyz/alpha/campaign/a158c590-f7eb-4bf7-9442-3c8a80f60855/verify?email=foo%40bar.com' \
     --header 'Authorization: Bearer <YOUR_KEY_HERE>' \
     --header 'accept: application/json'

Example Response: Verify Eligibility

A successful request returns a 200 OK response with a JSON object containing the following:

Example 200 Response

{
  "data": {
    "campaign_status": "active",
    "can_claim": true,
    "condition": {
      "meets_condition": true,
      "type": "sign_up"
    },
    "has_claimed": false
  }
}

Claim a Campaign Reward

To claim a campaign reward for a user, make a POST request to /alpha/campaign/{campaign_id}/claim with the campaign_id as a path parameter and the following parameters in the request body:

Claims for General Campaigns

As noted in the table above, claim requests for general campaigns can include an optional idempotency_key and additional_data.

• Use the idempotency_key to ensure claim uniqueness when the claim_frequency is set to unlimited. This field helps you guard against accidental duplicate claims. If you try to make a second claim with the same key, an error is returned.

💡

If you need to ensure that each claim in a general unlimited campaign is unique, set an idempotency_key every time you make a /claim request.

• Use the additional_data to supply metadata about the campaign or claim in a JSON object. This same object is returned as part of the claim_history when you make a /verify request to check the user's eligibility.

Example Request: Claim a Campaign Reward

curl --request POST \
     --url https://api.testcocrt.xyz/alpha/campaign/a158c590-f7eb-4bf7-9442-3c8a80f60855/claim \
     --header 'Authorization: Bearer <YOUR_KEY_HERE>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "email": "[email protected]",
  "wallet_address": "0xa9989a7d4fba7b84fa798ee98b4df7c148516dcf"
}
'

Example Response: Claim a Campaign Reward

A successful request returns a 200 OK response with a JSON object containing information about the reward.

Example Response

{
  "data": {
    "erc20_id": "782f9579-6674-4b42-b4bf-49ef0079d64e",
    "contract_address": "0xbf0bccc77bc2bbaa4894ee6dffdc6db787b89403",
    "num_tokens": [
      123
    ],
    "wallet_addresses": [
      "0xa9989a7d4fba7b84fa798ee98b4df7c148516dcf"
    ]
  }
}

👍

Get Help

If you get stuck at any time, reach out to us on Discord or contact us via email at [email protected].