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 the Co:Create Platform's Campaign API come into play.

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.

How It Works

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

Campaign Structure

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

Currently, the following conditions are available:

Campaign Actions

Currently, the following actions are available:

Using the Campaign API

At a simplified level, the Campaign API workflow is the following:

1. Create a campaign - Select your condition & action, providing specified parameters.
2. Verify user eligibility - Provide the campaign ID & the user's email to get information about whether the user has met the conditions required to claim from the campaign.
3. Claim campaign - Provide the campaign ID & the user's email to trigger the campaign action.

Endpoints

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

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

Campaign Creation

To create a Campaign, make a POST request to https://api.testcocrt.xyz/alpha/campaign with the body parameters listed below.

Request Body Parameters

The main body of the request has the following parameters.

(*) denotes required.

Furthermore, conditions and actions objects are structured as follows:

Condition

Action

Example Request

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"
}
'

Creation Response

A successful request will return 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

All campaigns must be claimed for the action to take place. Before claiming, you may want to check the user's campaign eligibility -- for instance, if you would like to display this status within your application.

To verify a user's eligibility for claiming a campaign, make a GET request to https://api.testcocrt.xyz/alpha/campaign/{campaign_id}/verify. Include the campaign_id as a path param and the user email for whom you are checking as a query param.

Example Request

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'

Verify Response

A successful request will return 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
  }
}

Campaign Claiming

For a user to be rewarded for completing the campaign, they must claim the campaign.

To claim the campaign, make a POST request to https://api.testcocrt.xyz/alpha/campaign/{campaign_id}/claim with the campaign_id as a path param and the following in the body:

Example Request

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"
}
'

Claim Response

A successful request will return 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].