Applying a referral code to an existing user

Contents

• Overview
• Version-specific information
• Permissions and Authentication
• HTTP Parameters
• Headers
• Sample requests
• Sample response
• Possible error responses

Overview

• Call name: apply-referral-code
• Endpoint URL: https://api0.spaaza.com/auth/apply-referral-code
• Request methods: POST
• Request Content-Type: application/json or application/x-www-form-urlencoded
• Response Content-Type: application/json
• Auth required: yes

This endpoint allows a referral code to be applied to an existing user after account creation, rather than at the moment of signup. This is useful in scenarios where a user creates an account first and only later receives or enters a referral code from a friend or other referring user.

In order for this endpoint to work, the chain must have a referral code submission window configured using the alter-chain endpoint (see Chain configuration below). The submission window defines how long after account creation a referral code can still be applied. If the window has expired for a given user, the request will be rejected.

When a referral code is successfully applied, the endpoint creates a referral relation between the referred user and the referring user, and issues any configured rewards (e.g. vouchers) to the referred user. If the referral campaign does not require a purchase by the referred user, the referring user’s reward is also issued immediately.

Chain configuration

Before this endpoint can be used, the chain must be configured with a referral code submission window. This is done by setting two parameters on the chain using the alter-chain endpoint:

• referral_code_submission_window_unit - The time unit for the submission window. Accepted values are: year, month, week, day, hour, minute, second.
• referral_code_submission_window_quantity - A positive integer indicating the number of time units.

Both parameters must be set together, or both must be null. For example, setting referral_code_submission_window_unit to day and referral_code_submission_window_quantity to 7 means that a referral code can be applied up to 7 days after the user’s account was created.

These parameters are returned in the chain object in responses to get-chain and get-card.

Version-specific information

The following version-specific changes apply to this endpoint. See the versioning page for more details.

Permissions and Authentication

This API call requires a valid Spaaza session (see authentication). The session can be as follows:

• User authentication: the logged-in user applies the referral code to their own account. The user must be an end-user (not an admin user).
• Admin authentication: the performing user needs to be logged in and have write access to the chain to which the target user is connected. The target user must be identified using the user parameter block and the chain_id parameter.
• Privileged authentication: the use of privileged authentication is permitted for this endpoint. The target user must be identified using the user parameter block and the chain_id parameter.

HTTP Parameters

The following HTTP parameters can be passed to the API:

User identifier parameters

When using admin or privileged authentication, the target user is identified using the user object. The following fields can be used inside the user object:

Headers

The following headers can/must be passed to the API call:

Sample requests

User authentication

When authenticated as the target user, only the referral_code (and optionally campaign_id) is required:

{
    "referral_code": "an8it2",
    "campaign_id": 3
}

Admin or privileged authentication

When using admin or privileged authentication, chain_id and user must also be supplied:

{
    "chain_id": 1,
    "user": {
        "user_id": 5
    },
    "referral_code": "an8it2",
    "campaign_id": 3
}

Applying to all active referral campaigns

If campaign_id is omitted, the referral code is applied to all currently active referral campaigns on the chain. A referral relation and reward is created for each active referral campaign:

{
    "referral_code": "an8it2"
}

Sample response

When a single referral campaign is matched, the response includes both a referral_relation object and a referral_relations array:

{
    "result": {
        "code": 1,
        "status": "ok"
    },
    "results": {
        "referral_relation": {
            "id": 1,
            "campaign_id": 3,
            "referring_user": {
                "id": 4,
                "first_name": "Janneke",
                "last_name": "De Bruin",
                "username": "testchainuser@acme.com",
                "member_number": "20000000001",
                "referral_code": "an8it2",
                "authentication_point_identifier": "10055501555",
                "auxiliary_identifier": null
            },
            "referred_user": {
                "id": 5,
                "first_name": "Referred",
                "last_name": "User",
                "username": "referraluser@gmail.com",
                "member_number": "20000000002",
                "referral_code": "4910z3",
                "authentication_point_identifier": "6120897249449",
                "auxiliary_identifier": null
            },
            "redeemed": false,
            "redeemed_date": null,
            "created_date": "2026-03-15 10:30:00"
        },
        "referral_relations": [
            {
                "id": 1,
                "campaign_id": 3,
                "referring_user": {
                    "id": 4,
                    "first_name": "Janneke",
                    "last_name": "De Bruin",
                    "username": "testchainuser@acme.com",
                    "member_number": "20000000001",
                    "referral_code": "an8it2",
                    "authentication_point_identifier": "10055501555",
                    "auxiliary_identifier": null
                },
                "referred_user": {
                    "id": 5,
                    "first_name": "Referred",
                    "last_name": "User",
                    "username": "referraluser@gmail.com",
                    "member_number": "20000000002",
                    "referral_code": "4910z3",
                    "authentication_point_identifier": "6120897249449",
                    "auxiliary_identifier": null
                },
                "redeemed": false,
                "redeemed_date": null,
                "created_date": "2026-03-15 10:30:00"
            }
        ],
        "result_type": "apply-referral-code"
    }
}

When multiple referral campaigns are matched (i.e. campaign_id was not supplied and the chain has more than one active referral campaign), the response includes only the referral_relations array (the singular referral_relation field is omitted):

{
    "result": {
        "code": 1,
        "status": "ok"
    },
    "results": {
        "referral_relations": [
            {
                "id": 1,
                "campaign_id": 3,
                "referring_user": { "..." : "..." },
                "referred_user": { "..." : "..." },
                "redeemed": false,
                "redeemed_date": null,
                "created_date": "2026-03-15 10:30:00"
            },
            {
                "id": 2,
                "campaign_id": 7,
                "referring_user": { "..." : "..." },
                "referred_user": { "..." : "..." },
                "redeemed": false,
                "redeemed_date": null,
                "created_date": "2026-03-15 10:30:00"
            }
        ],
        "result_type": "apply-referral-code"
    }
}

Possible error responses

The following represents a list of possible error responses for the apply-referral-code endpoint: