🎁 Campaigns

Reward your users with out-of-the-box business logic

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.

ObjectDescriptionExample
ConditionA rule that the user must meet to be eligible for claiming the campaignHold a Main Character, Zaddy, or ZINE NFT
ActionThe task that will be triggered once the user claims the campaignMint 200 DIMES to user's Co:Create Wallet

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:

ConditionDescription
sign_upReward a user for signing up for your community or program.
profile_updateReward a user for providing their name, address, or phone number. Choose one, two, or three criteria for reward claims.
token_gatedReward a user for holding tokens of a specified token contract -- ERC-20, ERC-721, or ERC-1155. Supports Ethereum, Polygon, and Gnosis Chain.
generalCreate 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_linkReward a user for connecting their Twitter account to their Co:Create profile. (Requires use of the Co:Create SDK.)
discord_social_linkReward a user for connecting their Discord account to their Co:Create profile. (Requires use of the Co:Create SDK.)
instagram_social_linkReward a user for connecting their Instagram account to their Co:Create profile. (Requires use of the Co:Create SDK.)
unverified_social_linkReward users for social posts without specifying a social platform or verifying an account.
referralReward 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.

ActionDescription
mintMint Co:Create-issued tokens to a specified user's wallet.
dual-mintMint Co:Create-issued tokens to two users' wallets, the sender and the receiver. This action supports "Give/Get" referral campaigns or can be configured to fit your community's specific needs.

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.

TypeEndpointDescription
POST/campaignCreate a campaign.
GET/campaignList all campaigns that have been created.
GET/campaign/{campaign_id}Retrieve a campaign by campaign ID, to fetch detailed information about a specific campaign.
PATCH/campaign/{campaign_id}Update an existing campaign to make modifications to a campaign after it has been created.
DELETE/campaign/{campaign_id}Remove a campaign that is no longer needed. After you make a DELETE request, the campaign's data is no longer available.

To terminate a campaign without deleting it, use a /cancel request.
POST/campaign/{campaign_id}/cancelPermanently terminate a campaign. Canceled campaigns cannot be resumed. The campaign's data remains available (compare the Delete endpoint in the preceding row).
POST/campaign/{campaign_id}/resumeResume a paused campaign or start a campaign that was created in an draft state.
POST/campaign/{campaign_id}/pauseTemporarily suspend all activities for the specified campaign ID. Paused campaigns can be resumed later; canceled campaigns cannot be resumed.
GET/campaign/{campaign_id}/verifyCheck whether a user is eligible to claim a campaign reward and get the user's claim history. Make a verify request before making a claim request.
POST/campaign/{campaign_id}/claimClaim a campaign reward for users who have completed the necessary steps to claim a campaign.

Before making a claim request, make a verify request to be sure the user is eligible for a reward.

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.

ParameterTypeDescription
title
Required
stringA name or overall label for the campaign.
subtitle
Required
stringAn additional label or explanatory text that supplements the title. Use this to show more information about the campaign in your app.
description
Required
stringA summary of the campaign's goal, purpose, or details. Use this to provide more details about the campaign in your app and guide users to next steps.
media_urlstringAn optional URL of a media file. Use this to display campaign-related media in your app.
condition
Required
objectAn object representing the condition that must be met for a user to be eligible for the campaign reward.
action
Required
objectAn object representing the action that will be taken when a user claims a campaign reward.

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

Condition

ParameterTypeDescription
type
Required
enumThe type of condition (you can also think of this as the overall campaign type). Valid values:
sign_up
profile_update
token_gated
general
twitter_social_link
discord_social_link
instagram_social_link
unverified_social_link
referral
manual_social_post (content creation)
namestringAn optional name for the condition. Use this to help users understand the purpose of the condition.
descriptionstringAn optional description of the condition. Use this to help users understand how the condition works.

Action

ParameterTypeDescription
type
Required
enumThe type of campaign action to take when a reward is claimed. Valid values: mint, dual-mint
token_type
Required
enumThe type of token to mint. Valid values:
erc20
erc721
id
Required
string (UUID)The UUID of the token to mint. You can get this value with a List ERC20 or List ERC721 request.
payout_amount
Requiired
numberThe amount of tokens of the specified id to mint to a user who claims a campaign reward.

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:

NameFormatDescription
campaign_statusenumDescribes the status of the campaign.

Valid values:
paused
active
draft
complete
conditionobjectObject containing condition data. Includes meets_condition and type.
meets_conditionBooleanIndicates whether the user meets the condition of the campaign.
typeenumThe type of condition defined for the campaign.
can_claimBooleanIndicates whether the user can claim a campaign reward.
has_claimedBooleanIndicates whether the user has already claimed a reward for the campaign. If so, details of the claim_history are also returned.

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:

ParameterTypeDescription
emailstringThe email address of the user who is claiming a campaign reward.
wallet_addressstringThe wallet address the campaign reward will be minted to.
idempotency_keystring (UUID)General unlimited campaigns only:
An optional key to ensure claim uniqueness. For more information, see Claims for General Campaigns.

The idempotency_key is relevant only when claim_frequency is set to unlimited. The key is disregarded if the frequency is once or daily because those frequencies already limit claims in the specified time period.
additional_dataobjectGeneral campaigns only:
Custom data that provides more details about the claim or campaign as key-value pairs.

In general campaigns, in which claim frequency is more important than other details, you can use this parameter to supply more contextual data than the campaign condition requires.

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].