Sign in

API Reference

This reference comprehensively documents the ReferralAPI Web-Script & NPM Package, encompassing all publicly available methods along with their corresponding potential responses.

This function generates a unique referral link tailored for your campaign. Each referral link combines the campaign URL with a distinct referral code.

  • Name
    referrer_user_id
    Type
    string
    Description

    [Optional] You can associate the Referral link with any arbitary value based on your internal representation, that uniquely identifies user of your website. Within a camapaign, a referrer_id, could be associated with multiple referral links.

Output

Case

Response

Referral Link gets created successfully

Referral Link Object

Maximum Referral Link capacity reached under current organization plan

Error Object

  • Name
    error_code
    Type
    INSUFFICIENT_PLAN
    Description

If the number of referral links associated with your organization exceeds 25,000

Error Object

  • Name
    error_code
    Type
    MAXIMUM_CAPACITY
    Description

This function retrieves all referral links associated with a user ID for your campaign.

  • Name
    referrer_user_id
    Type
    string
    Description

    [Required] The user ID for which you want to retrieve referral links.

Output

Case

Response

Referral Links gets retrieved successfully

List of Referral Link Object. Empty in case no referral link exists for given ID.

createReferredUser

This function associates a unique identifier for a user with a referral link from a campaign. This function is used for tracking the acquisition of new users through referral links.

  • Name
    referred_user_id
    Type
    string
    Description

    [Required] Any arbitary value based on your internal representation, that uniquely identifies user of your website. Within a camapaign, a referrered_used_id, could only be associated with one referral link.

Output

Case

Response

Referred User gets created successfully

Referred User Object

In case the current user is not accessing the website through a referral link, i.e., the presence of a referral cookie is not found.

Null

Case where referral link is wrong or doesn't belong to your campaign.

Error Object with either of the following error code

  • Name
    error_code
    Type
    NO_REFERRAL_LINK_FOUND
    Description
  • Name
    error_code
    Type
    KEY_INVALID
    Description

Case where referred user id already exists.

Error Object

  • Name
    error_code
    Type
    REFERRED_USER_EXISTS
    Description

createAction

It facilitates tracking and rewarding user actions beyond sign-ups, allowing the recording of actions with or without specifying a referred user ID.

  • Name
    action_type
    Type
    string
    Description

    [Required] Descriptive name to be assigned to the action.

  • Name
    metadata
    Type
    JSON
    Description

    [Required] Any metadata to be associated with the action.

  • Name
    referred_user_id
    Type
    JSON
    Description

    [Optional] The id of the user you wish to link the action to. It is the same id that you used to create the Referred user.

Output in case no referred_user_id is provided

When utilizing the createAction function without specifying a referred_user_id, it records an action for any user browsing your website while a referral cookie is present. This method treats both existing users and referred users equally, as they are both identified by the presence of the referral cookie.

Case

Response

Action gets created successfully

Action Object

In case the current user is not accessing the website through a referral link, i.e., the presence of a referral cookie is not found.

Null

Case where referral link is wrong or doesn't belong to your campaign.

Error Object with either of the following error code

  • Name
    error_code
    Type
    NO_REFERRAL_LINK_FOUND
    Description
  • Name
    error_code
    Type
    KEY_INVALID
    Description

Output in case referred_user_id is provided

Case

Response

Action gets created successfully

Action Object

Case where referred user id doesn't exist

Error Object

  • Name
    error_code
    Type
    NO_REFERRED_USER_FOUND
    Description

Handling different outputs

First of all, when we say Response would be Error Object we don't mean any error would be thrown by the function. When referring to the response as Error Object, it signifies that the function returns a JSON object resembling an error structure in case the desired operation cannot be completed due to various reasons. Errors are thrown only in instances where incorrect API-KEY or CAMPAIGN_ID are provided, or syntax errors occur during method invocation from your side.

Now, it is definitely not required to keep track and handle all Error Object. Error Object itself indicates that ReferralAPI have already handled edge cases for you. For eg. For example, encountering the error code NO_REFERRED_USER_FOUND during action creation indicates that the provided referred_user_id does not exist for the campaign, implying that the action is invoked by a non-referred user. Thus that means we can ignore this action and that is why ReferralAPI didn't POST this action in first place.

We provide this information to support customization of referral programs for specific use cases, such as monitoring the INSUFFICIENT_PLAN error code for timely actions.

Error Object

  • Name
    error_code
    Type
    string
    Description

    [Required] Short name describing the error.

  • Name
    status_code
    Type
    int
    Description

    [Required] HTTP status code, mostly 400.

  • Name
    field_key
    Type
    string
    Description

    [Optional] Name of the field, the error is associated with.

  • Name
    error_string
    Type
    string
    Description

    [Optional] Detailed description of the error.