Referral Endpoints

Description of endpoints used to get referral data

Please make sure you've read Data: API so you are familiar with the following types referenced in this documentation:

• ProfileEntryResponse

• PostEntryResponse

• BalanceEntryResponse

• NFTEntryResponse

• NFTCollectionResponse

Get Referral Info For User

POST /api/v0/get-referral-info-for-user

Gets all data about all referral codes for this owner, including users referred by this code.

Endpoint implementation in backend.

Example usages in frontend: - Make request to Get Referral Info For User - Use GetReferralInfoForUser to fetch the current state of all referral links for a user upon login

Request Body

Name	Type	Description
PublicKeyBase58Check*	String	user public key
JWT*	String	JSON web token authenticating user

200: OK Successfully retrieved information about all referral codes a given user has

Sample Response

{
  "ReferralInfoResponses": [{
      "IsActive": true, // If true, this referral code is still valid. If false, this referral code is not valid anymore.
      "ReferredUsers": [<ProfileEntryResponse>, <ProfileEntryResponse>...], // An array of ProfileEntryResponses representing the list of all users who successfully signed up with this referral code.
      "Info": {
        "ReferralHashBase58": "9diWfRVk", // Referral code
        "ReferrerPKID": [3, 35, 87, 246, 229, 114, 151, 131, 149, 22, 174, 63, 215, 30, 118, 206, 71, 228, 63, 136, 30, 139, 232, 104, 119, 240, 14, 196, 86, 89, 75, 16, 201], // PKID of the user who is the referrer for this code. PKID is a unique identity for a user - a user's PKID stays the same even if they have their identity swapped. This field is not particularly useful in this format for frontend consumption.
        "ReferrerAmountUSDCents": 500, // Amount referrer will receive in USD cents for a successful referral. Upon a successful referral, the referrer will receive the DeSo equivalent of $5 in this example. 
        "ReferreeAmountUSDCents": 2500, // Amount the user who was referred will receive in USD cents for a successful referral. Upon a successful referral, the user who signed up with this code will receive $25 in this example.
        "MaxReferrals": 10, // Maximum number of users that can be referred by this code. Note if this value is 0, there is no limit on the number of referrals
        "RequiresJumio": true, // Not implemented, but in a future state, there may be support for referral bonuses without going through the Jumio verification flow.
        "NumJumioAttempts": 100, // Number of times users have tried to sign up with this referral code and entered the Jumio verification flow
        "NumJumioSuccesses": 90, // Number of times users have successfully completed the Jumio verification flow with this referral code
        "TotalReferrals": 90, // Number of users who have been succesfully referred by this code
        "TotalRefererrerDeSoNanos": 900000, // Total amount of DeSo the referrer received from sign-ups with this referral code
        "TotalRefereeDeSoNanos": 180000, // Total amount of DeSo received across all users who have signed up with referral code.
        "DateCreatedTStampNanos": 9127398712983, // Timestamp of creation of this referral code
      }
    }]
}

Response Field Descriptions

400: Bad Request

Get Referral Info For Referral Hash

POST /api/v0/get-referral-info-for-referral-hash

Gets a summary of the current state of a single referral code. This is useful when a user arrives at your site with a referral code. It allows you to tell if the referral code is still valid and how much the user would receive if they signed up.

Endpoint implementation in backend.

Example usages in frontend: - Make request to Get Referral Info For Referral Hash - Use GetReferralInfoForReferralHash to show a new user the amount of money they would receive as a sign-up bonus with this referral code

Request Body

Name	Type	Description
ReferralHash*	String	referral code

200: OK Successfully retrieved referral info about the provided referral hash

Sample Response

{
  "ReferralInfoResponse": {
    "IsActive": true, // If true, this referral code is still valid
    "Info": {
      "ReferralHashBase58": "9diWfRVk", // Referral code
      "ReferreeAmountUSDCents": 2500, // Amount the user who was referred will receive in USD cents for a successful referral. Upon a successful referral, the user who signed up with this code will receive $25 in this example.
      "MaxReferrals": 10, // Maximum number of users that can be referred by this code. Note if this value is 0, there is no limit on the number of referrals
      "TotalReferrals": 90, // Number of users who have been succesfully referred by this code
    }
  },
  "CountrySignUpBonus": { // The CountrySignUpBonus object is based on the IP from which the request is made.
    "AllowCustomReferralAmount": true, // If true, referee amount specified in referral code will be paid to users who sign up with IDs from this country. If false, ReferralAmountOverrideUSDCents will be paid to users who sign up with IDs from this country.
    "ReferralAmountOverrideUSDCents": 100, // Amount all referees will be paid when signing up from this country if AllowCustomReferralAmount is false.
    "AllowCustomKickbackAmount": false, // If true, referrer amount specified in referral code will be paid as a kickback to users who gave out referral code that a user signed up with IDs from this country. If false, KickbackAmountOverrideUSDCents will be paid as a kickback to referrers when a user signs up with an ID from this country.
    "KickbackAmountOverrideUSDCents": 0, // Amount all referrers will be paid when a referee signs up from this country if AllowCustomKickbackAmount is false.
  }
}

Response Field Descriptions

400: Bad Request