👥 Referrals

Reward your members with tokens when guests redeem referral codes

Suggest Edits

Overview

Referrals are a powerful way to grow your user base and create incentives for existing users. With Co:Create's robust tool set, you can set up and manage referral campaigns tailored to your needs. Whether you're looking to boost event attendance, increase user engagement, or drive new sign-ups, you can use referral campaigns to streamline your development and expand your community.

Workflow

At a high level, the referral campaign workflow has four phases:

  1. Set up the referral campaign: Make a POST request to /alpha/campaign to define the parameters of your referral campaign, including rewards and conditions. For more details, see Create a Campaign.
  2. Distribute referral codes: When you create your new campaign, the API generates unique referral codes. Distribute these to your existing user base using your preferred method. For example, you can send codes via email or text, or provide them in your app.
  3. Track and verify referrals: Monitor referrals in real time with the /referrals endpoint. Check the validity of referral codes and claims with the campaign /verify endpoint. For more details, see Retrieve Referral Codes and Verify Referral Eligibility.
  4. Automatically distribute rewards: After verifying codes and claims, the API automatically distributes rewards according to your campaign settings. Rewards can be distributed to both referrers and referrals. For more details, see the next section.

Referral Parties

Referrals involve two parties: the referrer and the referral. You can also think of these users as members and guests.

  • The referrer is the existing user who gives the referral code to another user. The referrer is a current member of your community.
  • The referral is the user who redeems the referral code. The referral is a potential guest of your community, event, or other referral use case.

Referrers (referring members) and referrals (referred guests) can both receive rewards, depending on how you configure your campaign.

Rewards are defined by the action within the campaign condition. The referrer does not need to claim the campaign reward separately — the corresponding eligible member claim happens automatically when a guest redeems a valid referral code.

Retrieve Referral Codes

To retrieve referral codes, make a GET request to the /alpha/referrals endpoint. To limit the results to a specific campaign, include the campaign_id as a query parameter.

GET /alpha/referral?campaign_id={campaign_id}

Example request

curl --request GET \
     --url 'https://api.testcocrt.xyz/alpha/referral?campaign_id=fefae7b1-c946-44f1-9477-4ce29e62596b' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --header 'accept: application/json'

For complete parameters, see the interactive API reference.

Verify a Referral

To validate a referral code and the corresponding referrer claim, make a POST request to the campaign /verify endpoint. Verification includes making sure the code has not yet been redeemed, confirming that the member and guest have different email addresses and the member is eligible to claim the reward, and applying the claim frequency setting (one claim per referral code or one claim per campaign).

POST /alpha/campaign/{campaign_id}/verify
  • Specify the campaign_id in the path.
  • Include the email of the referral (the guest who wants to redeem the referral code) in the request body. Specify the referral_code in the additional_data object within the request body.

Example request

curl --request POST \
     --url 'https://api.testcocrt.xyz/alpha/campaign/fefae7b1-c946-44f1-9477-4ce29e62596b/verify' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "email": "[email protected]",
  "additional_data": {
    "referral_code": "EVENT-dsobid2n"
  }
}
'

The /verify response includes information about the claim history.

Examples

Use Case: Event Attendance

Suppose you're organizing an event and want to boost attendance through referrals. You can set up a referral campaign to give members event-specific referral codes to share with potential guests.

In this example, when a guest signs up for the event using a valid referral code, they gain free entry to the event. Simultaneously, the referring member receives token rewards in their wallet.

Set up the event campaign and generate referral codes

Make a POST request to the /alpha/campaign endpoint to create a new referral campaign. For more details, see Create a Campaign.

Request body

{
    // A name or label that summarizes the campaign.
    "title": "Event Guest Campaign",

    // The status of the campaign upon creation, either 'active' or 'draft'.
    // The default value is 'draft'.
    "status": "active",

    // The campaign condition that must be fulfilled in order to claim a
    // campaign reward. In referral campaigns, includes configuration details
    // for referral codes.
    "condition": {
        "type": "referral",
        
        // Configure referral codes, including how they are generated and assigned.
        // Because codes trigger campaign reward claims, the configuration includes
        // setting a claim frequency.
        "referral_code_configuration": {

            // A human-readable prefix for randomly generated referral codes.
            "referral_code_prefix": "EVENT-DEMO-",

            // Indicate how many times a referrer can receive token rewards for
            // referrals. Valid claims occur automatically when a code is redeemed.
            // 'per-referral' = one reward claim for each referral code
            // 'once' = one reward claim for the entire campaign (only the 
            // first redeemed code results in a reward claim)
            "claim_frequency": "per-referral",

            // Set the strategy for generating referral codes and assigning them to 
            // referrers. The 'all-users' strategy creates and assigns a quantity
            // of 'per_user_count' codes for each member, up to the 
            // 'max_assigned_per_user' quantity across all campaigns. In this 
            // example, 2 codes are generated per user, up to a max of 2 codes
            // across campaigns.
            "assignment_strategy": {
                "strategy": "all-users",
                "per_user_count": 2,
                "max_assigned_per_user": 2
            }
        }
    },
    // Define the campaign claim action for the referrer. This example
    // mints an erc-20 token and pays out 50 tokens on claim success.
    "action": {
        "type": "mint",
        "token_type": "erc20",
        "id": "xxxxxxxx-xxxx-4xxx-xxxx-xxxxxxxxxxxx",
        "payout_amount": 50
    }
}

Response body

{
    "data": {
        // The unique identifier (UUID) of the referral campaign.
        "id": "xxxxxxxx-xxxx-4xxx-xxxx-xxxxxxxxxxxx",
        "title": "Event Referral Campaign",
        "status": "active",
        "action": {
            "type": "mint",
            "token_type": "erc20",
            "id": "xxxxxxxx-xxxx-4xxx-xxxx-xxxxxxxxxxxx",
            "payout_amount": 50
        },
        "condition": {
            "type": "referral",
            "claim_frequency": "per-referral",
            "referral_code_generation": {
                // The results of referral code generation, including the quantity
                // generated and the assignment status.
                "generate_results": {
                    "referral_codes_generated": 4,
                    "status": "assigned"
                }
            }
        }
    }
}

Retrieve event campaign referral codes

When you make the POST request to create the referral campaign, the API automatically generates referral codes. You can retrieve the codes with a GET request to the referrals endpoint. For more information, see Retrieve Referral Codes.

Request URI

GET /alpha/referral?campaign_id={campaign_id}

Response body

{
    "data": [
        {
            // The 'id' is the referral code that member referrers
            // can give to guest referrals.
            "id": "EVENT-DEMO-jkuxzw2m",
            "status": "assigned",
            // The 'assigned_user' is the member the referral code is assigned 
            // to. This user is the referrer who gives codes to referrals.
            "assigned_user": "[email protected]",
            "created": "2023-09-28T19:36:21.65697+00:00"
        }
    ]
}

Verify event campaign referrals

For an overview of /verify requests, see Verify a Referral.

Request body

{
    // The email address of the referral (the guest user who wants to
    // redeem the code).
    "email": "[email protected]",
    "additional_data": {
        // The referral code to verify.
        "referral_code": "EVENT-DEMO-jkuxzw2m"
    }
}

Response body

{
    "data": {
        // The campaign status, either 'active' or 'draft'.
        "campaign_status": "active",
        
        // Indicates whether the referrer can claim the reward, based on
        // referral code validity and the campaign configuration. 
        "can_claim": true,
        
        // Details of previous claims for this campaign, if any.
        "claim_history": [],

        // The condition defined for the campaign, and whether
        // this claim meets the condition.
        "condition": {
            "claim_frequency": "per-referral",
            "meets_condition": true,
            "type": "referral"
        },

        // Indicates whether the referrer has already claimed rewards 
        // from this campaign.
        "has_claimed": false
    }
}

Sequence diagram

This diagram shows the sequence of requests and responses for the event attendance example. Campaign requests and actions move vertically down the diagram, and the horizontal arrows show the flow of interactions and data.

The sequence diagram for this use case.

The sequence of requests and flow of data in the event referral use case.

Use Case: Give Tokens, Get Tokens

Suppose you want to boost your user base through a referral system where both the referrer and the referee get tokens. In this "Give Tokens, Get Tokens" example campaign, when a new user signs up using a referral code, both the referrer and the new user are rewarded with tokens.

Set up the Give/Get campaign and generate referral codes

Make a POST request to the alpha/campaign endpoint to create a new referral campaign. For more details, see Create a Campaign.

Request body

{
    // A name or label that summarizes the campaign.
    "title": "Event Give/Get Campaign",

    // The status of the campaign upon creation, either 'active' or 'draft'.
    // The default value is 'draft'.
    "status": "active",

    // The campaign condition that must be fulfilled in order to claim a
    // campaign reward. In referral campaigns, includes configuration details
    // for referral codes.
    "condition": {
        "type": "referral",
     
        // Configure referral codes, including how they are generated and assigned.
        // Because codes trigger campaign reward claims, the configuration includes
        // setting a claim frequency.
        "referral_code_configuration": {

            // A human-readable prefix for randomly generated referral codes.
            "referral_code_prefix": "GIVEGET-DEMO-",

            // Indicate how many times a referrer can receive token rewards for
            // referrals. Valid claims occur automatically when a code is redeemed.
            // 'per-referral' = one reward claim for each referral code
            // 'once' = one reward claim for the entire campaign (only the 
            // first redeemed code results in a reward claim)
            "claim_frequency": "per-referral",

            // Set the strategy for generating referral codes and assigning them to 
            // referrers. The 'all-users' strategy creates and assigns a quantity
            // of 'per_user_count' codes for each member, up to the 
            // 'max_assigned_per_user' quantity across all campaigns. In this 
            // example, 2 codes are generated per user, up to a max of 2 codes
            // across campaigns.
            "assignment_strategy": {
                "strategy": "all-users",
                "per_user_count": 2,
                "max_assigned_per_user": 2
            }
        }
    },
    // Define the campaign claim action for the referrer. This example
    // mints an erc-20 token and pays out 50 tokens to the referrer on 
    // claim success. Additionally, 1 ERC-1155 token is minted and
    // paid out to the referral.
    "action": {
        "type": "dual-mint",
        "recipient_actions": {
          "sender": {
            "token_type": "erc20",
            "id": "xxxxxxxx-xxxx-4xxx-xxxx-xxxxxxxxxxx1",
            "payout_amount": 50
          },
          "receiver": {
            "token_type": "erc1155",
            "id": "xxxxxxxx-xxxx-4xxx-xxxx-xxxxxxxxxxx2",
            "token_id": 0,
            "payout_amount": 1
          }
        }
    }
}

Response Body

{
    "data": {
        // The unique identifier (UUID) of the referral campaign.
        "id": "xxxxxxxx-xxxx-4xxx-xxxx-xxxxxxxxxxxx",
        "title": "Event Give/Get Campaign",
        "status": "active",
        "action": {
            "type": "dual-mint"
        },
        "condition": {
            "type": "referral",
            "claim_frequency": "per-referral",
            "referral_code_generation": {
                // The results of the referral code generation, including the quantity
                // generated and the assignment status.
                "generate_results": {
                    "referral_codes_generated": 4,
                    "status": "assigned"
                }
            }
        }
    }
}

Retrieve Give/Get referral codes

When you make the POST request to create the referral campaign, the API automatically generates referral codes. You can retrieve the codes with a GET request to the referrals endpoint. For more information, see Retrieve Referral Codes.

Request URI

GET /alpha/referral?campaign_id={campaign_id}

Response body

{
    "data": [
        {
            // The 'id' is the referral code that member referrers
            // can give to guest referrals.
            "id": "GIVEGET-DEMO-jkuxzw2m",
            "status": "assigned",
            // The 'assigned_user' is the member the referral code is assigned 
            // to. This user is the referrer who gives codes to referrals.
            "assigned_user": "[email protected]",
            "created": "2023-09-28T19:36:21.65697+00:00"
        }
    ]
}

Verify Give/Get referrals

For an overview of /verify requests, see Verify a Referral.

Request body

{
    // The email address of the referral (the guest user who wants to
    // redeem the code).
    "email": "[email protected]",
    "additional_data": {
        // The referral code to verify.
        "referral_code": "GIVEGET-DEMO-jkuxzw2m"
    }
}

Response body

{
    "data": {
        // The campaign status, either 'active' or 'draft'.'
        "campaign_status": "active",
        
        // Indicates whether the referrer can claim the reward, based on
        // referral code validity and the campaign configuration.
        "can_claim": true,
        
        // Details of previous claims for this campaign, if any.
        "claim_history": [],

        // The condition defined for the campaign, and whether
        // this claim meets the condition.
        "condition": {
            "claim_frequency": "per-referral",
            "meets_condition": true,
            "type": "referral"
        },

        // Indicates whether the referrer has already claimed rewards 
        // from this campaign.
        "has_claimed": false
    }
}

Sequence diagram

This diagram shows the sequence of requests and responses for the give/get example. Campaign requests and actions move vertically down the diagram, and the horizontal arrows show the flow of interactions and data.

The sequence diagram for the Give / Get use case.

The sequence of requests and flow of data in the Give/Get use case.

👍

Get Help

If you get stuck, contact us on Discord or email us at [email protected].

Updated 6 months ago

What’s Next