Completing the referral relationship between a referring and referred user.
The result output is a JSON array with its results section being something to the lines of the following:
{
"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,
"award": {
"id": 2,
"user_id": 4,
"currency_id": 2,
"amount": 10,
"progress_type": "referralReward",
"log_message": "Voucher received for signup of Referred User.",
"created_date": "2022-08-04T07:56:13+00:00"
}
},
"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": true,
"redeemed_date": "2022-08-04 07:56:13",
"created_date": "2022-08-04 07:56:11"
},
"result_type": "complete-referral-relation"
}
}
- Call name: complete-referral-relation
- Endpoint URL: https://apistage0.spaaza.com/complete-referral-relation
- Request methods: GET
- Response Content-Type: application/json
- Auth required: yes
This endpoint allows a user with admin or privileged to complete the referral relation between a referring_user and a referred_user for a specific referral campaign. The default behaviour of a Spaaza referral campaign requires a transaction be made by the referred user in order for the referring user to be rewarded. This endpoint will override that requirement and will issue the referring_user their reward provided certain conditions are met.
JSON POST Request
The JSON file posted to the API call should be in the following format. Annotation is provided below:
{
"entity": {
"entity_type": "chain",
"entity_id": "1"
},
"campaign": {
"campaign_id": "3"
},
"referring_user": {
"referral_code": "jpht62",
"authentication_point_identifier": "10055501555",
"user_id": 4,
"username": "testchainuser@acme.com",
"member_number": "20000000001"
},
"referred_user": {
"referral_code": "vf7yxj",
"authentication_point_identifier": "6120897249449",
"user_id": 5,
"username": "referraluser@gmail.com",
"member_number": "20000000002"
}
}
JSON request parameters:
Below is a description of the JSON request paramters for the complete-referral-relation endpoint:
| Field | Description |
|---|---|
| entity (mandatory) | Details of the retailer which is submitting the request. |
| entity_type (mandatory) | The type of entity of the retailer. If the retailer is a chain with branches, this will be “chain”. If the retailer is an independent business with a single branch, this will be “business”. |
| entity_id (mandatory) | The Spaaza ID of the retailer entity. |
| campaign (mandatory) | Details of the referral campaign that that referring_user and referred_user have participated in. |
| campaign_id (mandatory) | The campaign_id of a referral campaign. |
| referring_user (mandatory) | The referring_user is the user who’s referral_code was used by the referred_user during their signup. The referring_user can be identified by either their referral_code, authentication_point_identifier, user_id, username or member_number. |
| referred_user (mandatory) | The referred_user is a user that was referred by the referring_user. The referred_user can be identified by either their referral_code, authentication_point_identifier, user_id, username or member_number. |
Permissions and Authentication
This API call requires a valid Spaaza session. The session can be as follows:
- Admin authentication: the performing user needs to be logged in and have
write accessto the chain to which the user is connected. - Privileged authentication: the use of privileged authentication is permitted for this endpoint.
Permissions
This API call requires the following permissions scenarios: Write permissions for the entity on behalf of which the call is being made.
Possible error responses
The following represents a list of possible error responses for the complete-referral-relation endpoint:
| Code | Name and Description | HTTP Status Code |
|---|---|---|
| 3 | http_vars_missing This script is missing some required variables which must be submitted. | 400 |
| 6 | no_valid_session The user needs to be logged in and a valid session key needs to be sent | 401 |
| 68 | permission_denied_or_non_existent This user has insufficient permissions for this object or the object does not exist. | 500 |
| 403 | campaign_type_not_supported This type of campaign is not supported | 400 |
| 154 | user_id_invalid The user_id passed must be an integer up to 10 digits long | 400 |
| 217 | chain_id_not_found No record has been found for that chain_id | 400 |
| 228 | auth_method_invalid The given auth_method parameter has an invalid value. | 500 |
| 405 | entity_mismatch The entities or chains supplied do not match. Unable to find a user matching the chain_id supplied | 400 |
| 413 | campaign_not_found The campaign was not found | 400 |
| 403 | campaign_type_not_supported This type of campaign is not supported. The campaign must be a referral campaign | 400 |
| 264 | myprice_app_without_entity The requested MyPrice app does not have an entity associated with it. | 400 |
| 265 | authorization_invalid The given authorization header is invalid. | 400 |
| 267 | no_valid_user A valid username needs to be specified | 401 |
| 269 | no_myprice_app Myprice app is required | 400 |
| 270 | user_not_found No user was found | 404 |
| 416 | multiple_parameter_mismatch Multiple parameters supplied when fewer are required | 400 |
| 424 | access_denied Access is denied | 400 |
| 502 | referral_relation_not_found A referral_relation was not found | 400 |
| 504 | referral_relation_already_redeemed AThe referral_relation has already been fully redeemed. | 400 |