Back to top

API Documentation

Referral API

Get a referral code of a referrer

Get the referral code of a referrer by email
GET/api/referrer/{encodeEmail}/referral-code

Example URI

GET https://referrals.spotahome.com/api/referrer/ZW1haWxAYm9uaWMub20=/referral-code
URI Parameters
HideShow
encodeEmail
string (required) Example: ZW1haWxAYm9uaWMub20=

email encode using base 64 algorithm

Request
HideShow
Headers
Authorization: aa.bb.cc
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "referralCode": "REFERRAL-CODE-MOLT-BONIC"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "referralCode": {
      "type": "string"
    }
  }
}
Response  401
HideShow
Body
Authentication error. Probably the authorization token is not correct or the user does not have the right role to access this service.
Response  404
HideShow
Body
Email not found.
Response  422
HideShow
Body
Unprocessable entity. Email is not valid.
Response  500
HideShow
Body
Server error

Get data of a referrer

Get the referrer data
GET/api/referrer{?referrerCode}

Example URI

GET https://referrals.spotahome.com/api/referrer?referrerCode=ALBE-MQ-X
URI Parameters
HideShow
referrerCode
string (required) Example: ALBE-MQ-X

Criteria by referrer code

Request
HideShow
Headers
Authorization: aa.bb.cc
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "fistName": "Albert",
  "lastName": "Zabala",
  "referralCode": "ALBE-MQ-X",
  "email": "email@molt-bonic.com"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "fistName": {
      "type": "string"
    },
    "lastName": {
      "type": "string"
    },
    "referralCode": {
      "type": "string"
    },
    "email": {
      "type": "string"
    }
  }
}
Response  401
HideShow
Body
Authentication error. Probably the authorization token is not correct or the user does not have the right role to access this service.
Response  404
HideShow
Body
Referrer not found.
Response  422
HideShow
Body
Unprocessable entity. Referral code is not valid.
Response  500
HideShow
Body
Server error

Create a referral code for an email

Create a referrer identified by user email
POST/api/referrer/external/register

Example URI

POST https://referrals.spotahome.com/api/referrer/external/register
Request
HideShow
Headers
Content-Type: application/json
Authorization: aa.bb.cc
Body
{
  "email": "email@bonic.om",
  "firstName": "first name",
  "lastName": "last name"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "email": {
      "type": "string"
    },
    "firstName": {
      "type": "string"
    },
    "lastName": {
      "type": "string"
    }
  },
  "required": [
    "email"
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json
Response  400
HideShow
Body
The body of request is wrong. Check name of field and which fields are required.
Response  401
HideShow
Body
Authentication error. Probably the authorization token is not correct or the user does not have the right role to access this service.
Response  422
HideShow
Body
Unprocessable entity. Email is not valid.
Response  500
HideShow
Body
Server error

DEPRECATED Redeem a referral

DEPRECATED Redeem referral
POST/api/landlord/register

Example URI

POST https://referrals.spotahome.com/api/landlord/register
Request
HideShow
Headers
Content-Type: application/json
Authorization: aa.bb.cc
Body
{
  "accountId": "aaaa-bbbb-cccc-dddd",
  "promoCode": "REFERLAND09283"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "accountId": {
      "type": "string"
    },
    "promoCode": {
      "type": "string"
    }
  },
  "required": [
    "accountId",
    "promoCode"
  ]
}
Response  200
HideShow
Body
The user redeem the referral code.
Response  201
HideShow
Body
The user tries to redeem the same code again.
Response  400
HideShow
Body
Attributes are required
Response  401
HideShow
Body
Authentication error. Probably the authorization token is not correct or the user does not have the right role to access this service.
Response  403
HideShow
Body
The user registered a different code before
Response  404
HideShow
Body
Referral code is not found
Response  422
HideShow
Body
The request body is not valid
Response  500
HideShow
Body
Server error

Redeem a referral code

Redeem referral code
POST/api/referee/redeem

Example URI

POST https://referrals.spotahome.com/api/referee/redeem
Request
HideShow
Headers
Content-Type: application/json
Authorization: aa.bb.cc
Body
{
  "referralCode": "REFERLAND09283"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "referralCode": {
      "type": "string"
    }
  },
  "required": [
    "referralCode"
  ]
}
Response  200
HideShow
Body
The user redeem the referral code.
Response  201
HideShow
Body
The user tries to redeem the same code again.
Response  400
HideShow
Body
Attributes are required
Response  401
HideShow
Body
Authentication error. Probably the authorization token is not correct or the user does not have the right role to access this service.
Response  403
HideShow
Body
The user registered a different code before
Response  404
HideShow
Body
Referral code is not found
Response  422
HideShow
Body
The request body is not valid
Response  500
HideShow
Body
Server error

Apply a referral code

Apply referral code by only an Admin user
POST/api/referee/apply

Example URI

POST https://referrals.spotahome.com/api/referee/apply
Request
HideShow
Headers
Content-Type: application/json
Authorization: aa.bb.cc
Body
{
  "accountId": "aaaa-bbbb-cccc-dddd",
  "referralCode": "REFERLAND09283"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "accountId": {
      "type": "string"
    },
    "referralCode": {
      "type": "string"
    }
  },
  "required": [
    "accountId",
    "referralCode"
  ]
}
Response  200
HideShow
Body
The user redeem the referral code.
Response  201
HideShow
Body
The user tries to redeem the same code again.
Response  400
HideShow
Body
Attributes are required
Response  401
HideShow
Body
Authentication error. Probably the authorization token is not correct or the user does not have the right role to access this service.
Response  403
HideShow
Body
The user registered a different code before
Response  422
HideShow
Body
Referral code is not valid
Response  500
HideShow
Body
Server error

Get a referee

Get the information of a referee
GET/api/referee/u/{userId}

Example URI

GET https://referrals.spotahome.com/api/referee/u/aaaaa-bbbbb-ccccc
URI Parameters
HideShow
userId
string (required) Example: aaaaa-bbbbb-ccccc
Request
HideShow
Headers
Authorization: aa.bb.cc
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "acc-123",
  "referralCode": "referralcode",
  "redeemOn": "2018-01-01 00:00"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "referralCode": {
      "type": "string"
    },
    "redeemOn": {
      "type": "string"
    }
  }
}
Response  401
HideShow
Body
Authentication error. Probably the authorization token is not correct or the user does not have the right role to access this service.
Response  404
HideShow
Body
Referee by user id not found.
Response  500
HideShow
Body
Server error

DEPRECATED Check if a user has redeemed a referral code

DEPRECATED Has the user redeemed a referral code?
GET/api/referee/check/{accountId}

Example URI

GET https://referrals.spotahome.com/api/referee/check/aaaaa-bbbbb-ccccc
URI Parameters
HideShow
accountId
string (required) Example: aaaaa-bbbbb-ccccc
Request
HideShow
Headers
Authorization: aa.bb.cc
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "registered": true
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "registered": {
      "type": "boolean"
    }
  }
}
Response  401
HideShow
Body
Authentication error. Probably the authorization token is not correct or the user does not have the right role to access this service.
Response  500
HideShow
Body
Server error

DEPRECATED Check if a user has redeemed a referral code

DEPRECATED Has the user redeemed a referral code?
GET/api/landlord/check/{accountId}

Example URI

GET https://referrals.spotahome.com/api/landlord/check/aaaaa-bbbbb-ccccc
URI Parameters
HideShow
accountId
string (required) Example: aaaaa-bbbbb-ccccc
Request
HideShow
Headers
Authorization: aa.bb.cc
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "registered": true
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "registered": {
      "type": "boolean"
    }
  }
}
Response  401
HideShow
Body
Authentication error. Probably the authorization token is not correct or the user does not have the right role to access this service.
Response  500
HideShow
Body
Server error

Create a referral code for internal user

Create a referrer for internal user, identified by token
POST/api/referrer/internal/register

Example URI

POST https://referrals.spotahome.com/api/referrer/internal/register
Request
HideShow
Headers
Content-Type: application/json
Authorization: aa.bb.cc
Response  200
HideShow
Headers
Content-Type: application/json
Response  401
HideShow
Body
Authentication error. Probably the authorization token is not correct or the user does not have the right role to access this service.
Response  500
HideShow
Body
Server error

Get a referral code for internal in user

Get referral code for internal user, identified by token
GET/api/referrer/internal/referral-code

Example URI

GET https://referrals.spotahome.com/api/referrer/internal/referral-code
Request
HideShow
Headers
Content-Type: application/json
Authorization: aa.bb.cc
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "referralCode": "ABC-6add-T"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "referralCode": {
      "type": "string"
    }
  }
}
Response  401
HideShow
Body
Authentication error. Probably the authorization token is not correct or the user does not have the right role to access this service.
Response  500
HideShow
Body
Server error

Generated by aglio on 28 Nov 2025