SaaSquatch Help Center

The Referral SaaSquatch API is organized around REST. Our API is designed to have predictable, resource-oriented URLs and to use HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which can be understood by off-the-shelf HTTP clients. JSON will be returned in all responses from the API, including errors.

To make the Referral SaaSquatch API as explorable as possible, accounts have test-mode API keys as well as live-mode API keys. These keys are both active at the same time. Data created with test-mode credentials will use your payment system's respective test mode.

Tag Summary

API methods are organized by tags of similar functionality. If you're in a hurry to understand how the SaaSquatch REST API works, then understanding the tags is a great place to start.

Account

Accounts can be shared between users and accumulate credit.

User

Users are the people in your program. In other places a User might also be called a Contact, Lead or Participant.

Referral Code

Referral Codes are unique ids used to track referrals.

Referral

A Referral tracks who has referred whom.

Reward Balance

Reward Balances summarizes the Rewards in someone's account.

Reward

A Reward keeps track of a prize, discount or credit that someone has received.

Open Endpoint

Open Endpoints are special methods designed specifically for Client-facing applications like the Mobile SDK and Javascript SDK.

Webhook

Webhooks can be used to do real time actions and data synchronization from SaaSquatch.

Theme

Themes control the look and feel of your program's widgets.

Discount

Endpoints for working with discounts. Most of these are deprecated in favor of using Reward endpoints.

Authentication Summary

API methods may be used with one or several authentication schemes as defined in this table:

APIKey

Authorize your requests using a tenant's API Key. Use this method of security only in server-to-server interactions.

UserJWT

Authorize your requests using a JWT (JSON Web Token) for a given user. Useful for client-server authorization, such as the Mobile and Web SDKs. Used in Open Endpoints.

Unauthenticated
Does not require any type of authentication to make this API call.

Methods Summary

Method Route Description Auth Tags
POST /api/v1/{tenant_alias}/accountsync Create or Update an account APIKey Account
GET /api/v1/{tenant_alias}/account/{accountId} Lookup an account APIKey Account
POST /api/v1/{tenant_alias}/user Create or Update a User APIKey User
GET /api/v1/{tenant_alias}/user Lookup a user by Referral Code APIKey User
GET /api/v1/{tenant_alias}/account/{accountId}/user/{userId} Lookup a user APIKey User
GET /api/v1/{tenant_alias}/account/{accountId}/user/{userId}/sharelinks Lookup a user's share links APIKey User
GET /api/v1/{tenant_alias}/users List users APIKey User
GET /api/v1/{tenant_alias}/code/{code} Lookup a referral code APIKey Referral Code
GET /api/v1/{tenant_alias}/referrals List referrals APIKey Referral
GET /api/v1/{tenant_alias}/referrals/{referralId} Lookup a Referral APIKey Referral
POST /api/v1/{tenant_alias}/referrals/moderate Moderate referrals APIKey Referral
GET /api/v1/{tenant_alias}/reward/balance List reward balances APIKey Reward Balance
POST /api/v1/{tenant_alias}/credit/bulkredeem Debit a reward balance APIKey Reward Balance
GET /api/v1/{tenant_alias}/reward List an account's rewards APIKey Reward
POST /api/v1/{tenant_alias}/credit/{id}/redeem Redeem a single reward APIKey Reward
POST /api/v1/{tenant_alias}/rewards/account/{accountId}/user/{userId} Create a single reward APIKey Reward
POST /api/v1/{tenant_alias}/open/account/{accountId}/user/{userId} Create a user and account APIKey UserJWT User Open Endpoint
GET /api/v1/{tenant_alias}/open/account/{accountId}/user/{userId} Lookup a user APIKey UserJWT User Open Endpoint
GET /api/v1/{tenant_alias}/open/user Get a user by a referral code Unauthenticated User Open Endpoint
GET /api/v1/{tenant_alias}/open/code/{referral_code} Lookup a referral code Unauthenticated Referral Code Open Endpoint
POST /api/v1/{tenant_alias}/open/code/{referral_code}/account/{account_id}/user/{user_id} Apply a referral code APIKey UserJWT Referral Code Open Endpoint
GET /api/v1/{tenant_alias}/open/referrals List referrals APIKey UserJWT Referral Open Endpoint
POST /api/v1/{tenant_alias}/subscription Create a webhook subscription APIKey Webhook
GET /api/v1/{tenant_alias}/subscription List webhook subscriptions APIKey Webhook
DELETE /api/v1/{tenant_alias}/subscription/{url} Delete a webhook subscription APIKey Webhook
POST /api/v1/{tenant_alias}/subscription/{url}/test Test a webhook subscription APIKey UserJWT Webhook
POST /api/v1/{tenant_alias}/export Create a CSV Export APIKey Export
GET /api/v1/{tenant_alias}/export/{exportId} Lookup a CSV Export APIKey Export
GET /api/v1/{tenant_alias}/export/{exportId}/download Download a CSV Export APIKey Export
GET /api/v1/{tenant_alias}/export/history/list List CSV Exports APIKey Export
GET /api/v1/{tenant_alias}/theme/variables/schema Lookup variables schema APIKey Theme
GET /api/v1/{tenant_alias}/theme/variables/instance Lookup variables values APIKey Theme
PUT /api/v1/{tenant_alias}/theme/variables/instance Replace Variable Values APIKey Theme
PATCH /api/v1/{tenant_alias}/theme/variables/instance Update Variable Values APIKey UserJWT Theme
POST /api/v1/{tenant_alias}/theme/email/{email_type}/preview Preview Theme Email APIKey Theme
GET /api/v1/{tenant_alias}/discount/{code} Lookup a discount code APIKey Discount
POST /api/v1/{tenant_alias}/discount Set discount code on an account APIKey Discount
GET /api/v1/{tenant_alias}/account/{accountId}/discount Lookup an account discount APIKey Discount

Create or Update an account POST /api/v1/{tenant_alias}/accountsync

Use this method to update SaaSquatch when the status of an account changes or when a new account is created.

This call is only available on an API-only program. Making this call on a payment provider program will fail and return a 403 error indicating the call is incompatible with your type of program.

Tags: Account Authentication: APIKey

Arguments

Required account
JSON Body

Account details of the account to be created or updated

Required id
string

Unique identifier for the account

Required subscription
object

An object describing the current subscription for this account

Required status
string

The status of the subscription.

Possible values: PAID, TRIAL, FREE, or CANCELLED

billingIntervalType
string

Type of billing interval.
Required when status: PAID.
Use a placeholder value of DAY for Referral SaaSquatch programs with non-CPA billing

Possible values: DAY, WEEK, MONTH, QUARTER, SEMI_ANNUAL, or YEAR

billingIntervalValue
integer

The value of billing interval.
Required when status: PAID.
Use a placeholder value of 1 for Referral SaaSquatch programs with non-CPA billing

value
number

Dollar value of the subscription per renewal.
Required when status: PAID.
Use a placeholder value of 1 for Referral SaaSquatch programs with non-CPA billing

referral
object

Info about who referred this account. Use this on first signup.

code
string

The referral code of the person that referred this account. Use squatch.js autofill to retrieve this value from the tracking cookie on your checkout form.

currency
string

Default is "USD". Otherwise use an ISO 4217 Standard currency code in uppercase.

Required tenant_alias
string

Tenant being referenced. E.g. "aboih12h16t" or "test_abo912126tastastt"

Example Curl Request

curl -X POST https://app.referralsaasquatch.com/api/v1/{tenant_alias}/accountsync \
-u :API_KEY \
-H "Content-Type: application/json" \
-d '{
    "id": "abc123",
    "subscription": {
        "status": "PAID",
        "billingIntervalType": "DAY",
        "billingIntervalValue": 1,
        "value": 1
    },
    "referral": {
        "code": "BOBTESTERSON"
    },
    "currency": "USD"
}'

Returns

id
string

Unique identifier for the account

subscription
object

An object describing the current subscription for this account

status
string

The status of the subscription.

Possible values: PAID, TRIAL, FREE, or CANCELLED

billingIntervalType
string

Type of billing interval.
Required when status: PAID.
Use a placeholder value of DAY for Referral SaaSquatch programs with non-CPA billing

Possible values: DAY, WEEK, MONTH, QUARTER, SEMI_ANNUAL, or YEAR

billingIntervalValue
integer

The value of billing interval.
Required when status: PAID.
Use a placeholder value of 1 for Referral SaaSquatch programs with non-CPA billing

value
number

Dollar value of the subscription per renewal.
Required when status: PAID.
Use a placeholder value of 1 for Referral SaaSquatch programs with non-CPA billing

referral
object

Info about who referred this account. Use this on first signup.

code
string

The referral code of the person that referred this account. Use squatch.js autofill to retrieve this value from the tracking cookie on your checkout form.

currency
string

Default is "USD". Otherwise use an ISO 4217 Standard currency code in uppercase.

Example Response

HTTP 200
{
    "id": "a1234",
    "currency": "USD",
    "subscription": {
        "status": "PAID",
        "value": 1,
        "billingIntervalType": "DAY",
        "billingIntervalValue": 1
    },
    "referral": {
        "code": "3j033r"
    }
}

Example Response

HTTP 403
{
    "message": "Account sync failed. This push is not valid for your tenant type[STRIPE]",
    "statusCode": 403,
    "apiErrorCode": "API_REQUEST_NOT_SUPPORTED"
}

Lookup an account GET /api/v1/{tenant_alias}/account/{accountId}

Looks up an Account based upon id and returns the stored account information. This method just returns the details of the account in question, and not all associated properties like Rewards, ShareLinks, Balances or Referrals.

This call is only available on an API-only program. Making this call on a payment provider program will fail and return a 403 error indicating the call is incompatible with your type of program.

Tags: Account Authentication: APIKey

Arguments

Required accountId
string

The id of the Account to look up.

Required tenant_alias
string

Tenant being referenced. E.g. "aboih12h16t" or "test_abo912126tastastt"

Example Curl Request

curl -X GET https://app.referralsaasquatch.com/api/v1/{tenant_alias}/account/{accountId} \
-u :API_KEY \

Returns

id
string

Unique identifier for the account

subscription
object

An object describing the current subscription for this account

status
string

The status of the subscription.

Possible values: PAID, TRIAL, FREE, or CANCELLED

billingIntervalType
string

Type of billing interval.
Required when status: PAID.
Use a placeholder value of DAY for Referral SaaSquatch programs with non-CPA billing

Possible values: DAY, WEEK, MONTH, QUARTER, SEMI_ANNUAL, or YEAR

billingIntervalValue
integer

The value of billing interval.
Required when status: PAID.
Use a placeholder value of 1 for Referral SaaSquatch programs with non-CPA billing

value
number

Dollar value of the subscription per renewal.
Required when status: PAID.
Use a placeholder value of 1 for Referral SaaSquatch programs with non-CPA billing

referral
object

Info about who referred this account. Use this on first signup.

code
string

The referral code of the person that referred this account. Use squatch.js autofill to retrieve this value from the tracking cookie on your checkout form.

currency
string

Default is "USD". Otherwise use an ISO 4217 Standard currency code in uppercase.

Example Response

HTTP 200
{
    "id": "89842",
    "currency": "USD",
    "subscription": {
        "status": "PAID",
        "value": 29.99,
        "billingIntervalType": "MONTH",
        "billingIntervalValue": 1
    },
    "referral": {
        "code": "WILLSANDERSON2"
    }
}

Example Response

HTTP 403
{
    "message": "Account sync failed. This push is not valid for your tenant type[STRIPE]",
    "statusCode": 403,
    "apiErrorCode": "API_REQUEST_NOT_SUPPORTED"
}
statusCode
integer

The HTTP status code of the error

message
string

The human-readable description of what went wrong. Use this to help you debug.

apiErrorCode
string

A machine error code

Example Response

HTTP 404

Create or Update a User POST /api/v1/{tenant_alias}/user

This method creates or updates a User object by performing an atomic upsert operation. Using this method will either replace the information stored about a given user, or create a new user if no User with a matching id is found. This method is helpful for synchronizing user information from your database into Referral SaaSquatch. This method will not create or update the Account linked by accountId. When creating users for the first time ensure that the Account already exists or create it before using this call. See the article on Shared vs Solo Accounts for more information on Users and Accounts and how they relate.

Tags: User Authentication: APIKey

Arguments

Required user
JSON Body

Details of the User to be created or updated

Required id
string

The unique identifier provided for this user.

Required accountId
string

The unique identifier of the Account that this user belongs to.

referralCode
string

The referral code used for sharing by this user

email
string

The email address provided for the user. SaaSquatch uses this to notify someone when they have a successful referral.

imageUrl
string

Optionally used in widgets, emails, and themes. If you provide a absolute profile image URL the minimum image size is 80px x 80px.

Required firstName
string

The user's first name

lastName
string

The user's last name

locale
string

The user's locale, used for Internationalization. The locale must be of the format 'language_COUNTRY' where the language code must be lowercase and the country code must be uppercase. The separator must be an underscore.

Required tenant_alias
string

Tenant being referenced. E.g. "aboih12h16t" or "test_abo912126tastastt"

Example Curl Request

curl -X POST https://app.referralsaasquatch.com/api/v1/{tenant_alias}/user \
-u :API_KEY \
-H "Content-Type: application/json" \
-d '{
    "id": "219065",
    "accountId": "accc9065",
    "email": "bob@example.com",
    "firstName": "Bob",
    "lastName": "Testerson",
    "referralCode": "BOBTESTERSON",
    "imageUrl": "https://www.example.com/profiled/ab5111251125",
    "locale": "`en` or `en_US` or `zh_CN`"
}'

Returns

id
string

The unique identifier provided for this user.

accountId
string

The unique identifier of the Account that this user belongs to.

referralCode
string

The referral code used for sharing by this user

email
string

The email address provided for the user. SaaSquatch uses this to notify someone when they have a successful referral.

imageUrl
string

Optionally used in widgets, emails, and themes. If you provide a absolute profile image URL the minimum image size is 80px x 80px.

firstName
string

The user's first name

lastName
string

The user's last name

firstSeenIP
string
readonly

The user's IP address on indentification

lastSeenIP
string
readonly

The user's last known IP address

dateCreated
integer
readonly

The Unix time stamp of when the user was created

emailHash
string
readonly

The hash of the user's email address

referralSource
string
readonly

The domain from which the user was registered

locale
string

The user's locale, used for Internationalization. The locale must be of the format 'language_COUNTRY' where the language code must be lowercase and the country code must be uppercase. The separator must be an underscore.

shareLinks
object
readonly

Share link for an individual user.

shareLink
string

The unique share link the user can refer their friends with. The Share Link contains the Referral Code for making referrals and a source for Analytics purposes.

facebookShareLink
string

The Share Link for Facebook.

twitterShareLink
string

The Share Link for Twitter.

emailShareLink
string

The Share Link for Email.

mobileShareLink
string

The Share Link for mobile devices.

mobileFacebookShareLink
string

The Share Link for Facebook on mobile devices.

mobileTwitterSharelink
string

The Share Link for Twitter on mobile devices.

mobileEmailShareLink
string

The Share Link for Email on mobile devices.

EMBED
object

An individual user's Share links for use in EMBED.

shareLink
string

The unique share link the user can refer their friends with. The Share Link contains the Referral Code for making referrals and a source for Analytics purposes.

facebookShareLink
string

The Share Link for Facebook.

twitterShareLink
string

The Share Link for Twitter.

emailShareLink
string

The Share Link for Email.

linkedinShareLink
string

The Share Link for linkedin.

POPUP
object

An individual user's Share links for use in POPUP.

shareLink
string

The unique share link the user can refer their friends with. The Share Link contains the Referral Code for making referrals and a source for Analytics purposes.

facebookShareLink
string

The Share Link for Facebook.

twitterShareLink
string

The Share Link for Twitter.

emailShareLink
string

The Share Link for Email.

linkedinShareLink
string

The Share Link for linkedin.

HOSTED
object

An individual user's Share links for use in HOSTED.

shareLink
string

The unique share link the user can refer their friends with. The Share Link contains the Referral Code for making referrals and a source for Analytics purposes.

facebookShareLink
string

The Share Link for Facebook.

twitterShareLink
string

The Share Link for Twitter.

emailShareLink
string

The Share Link for Email.

linkedinShareLink
string

The Share Link for linkedin.

MOBILE
object

An individual user's Share links for use in MOBILE.

shareLink
string

The unique share link the user can refer their friends with. The Share Link contains the Referral Code for making referrals and a source for Analytics purposes.

facebookShareLink
string

The Share Link for Facebook.

twitterShareLink
string

The Share Link for Twitter.

emailShareLink
string

The Share Link for Email.

linkedinShareLink
string

The Share Link for linkedin.

EMAIL
object

An individual user's Share links for use in EMAIL.

shareLink
string

The unique share link the user can refer their friends with. The Share Link contains the Referral Code for making referrals and a source for Analytics purposes.

facebookShareLink
string

The Share Link for Facebook.

twitterShareLink
string

The Share Link for Twitter.

emailShareLink
string

The Share Link for Email.

linkedinShareLink
string

The Share Link for linkedin.

Example Response

HTTP 200
{
    "id": "898746321",
    "accountId": "987321",
    "email": "hello@example.com",
    "firstName": "Henk",
    "lastName": "Thompson",
    "referralCode": "HENKTHOMPSON",
    "imageUrl": "",
    "firstSeenIP": "10.230.163.157",
    "lastSeenIP": "184.66.242.57",
    "dateCreated": 1467222395030,
    "emailHash": "180bc1412a038746af9b37fb782724a2",
    "referralSource": "http://unifiedtestapp.herokuapp.com/",
    "locale": null,
    "shareLinks": {
        "shareLink": "http://ssqt.co/mvbcF5",
        "facebookShareLink": "http://ssqt.co/mmbcF5",
        "twitterShareLink": "http://ssqt.co/mRbcF5",
        "emailShareLink": "http://ssqt.co/mLbcF5",
        "linkedinShareLink": "http://ssqt.co/mLbcF5",
        "mobileShareLink": "http://ssqt.co/mebcF5",
        "mobileFacebookShareLink": "http://ssqt.co/mnbcF5",
        "mobileTwitterShareLink": "http://ssqt.co/mCbcF5",
        "mobileEmailShareLink": "http://ssqt.co/mEbcF5",
        "EMBED": {
            "shareLink": "http://ssqt.co/mQbcF5",
            "facebookShareLink": "http://ssqt.co/mwbcF5",
            "twitterShareLink": "http://ssqt.co/mcbcF5",
            "emailShareLink": "http://ssqt.co/mJbcF5",
            "linkedinShareLink": "http://ssqt.co/mHbcF5"
        },
        "POPUP": {
            "shareLink": "http://ssqt.co/m5bcF5",
            "facebookShareLink": "http://ssqt.co/m9bcF5",
            "twitterShareLink": "http://ssqt.co/mMbcF5",
            "emailShareLink": "http://ssqt.co/mobcF5",
            "linkedinShareLink": "http://ssqt.co/m7bcF5"
        },
        "HOSTED": {
            "shareLink": "http://ssqt.co/mtbcF5",
            "facebookShareLink": "http://ssqt.co/mubcF5",
            "twitterShareLink": "http://ssqt.co/mSbcF5",
            "emailShareLink": "http://ssqt.co/mlbcF5",
            "linkedinShareLink": "http://ssqt.co/mYbcF5"
        },
        "MOBILE": {
            "shareLink": "http://ssqt.co/mebcF5",
            "facebookShareLink": "http://ssqt.co/mnbcF5",
            "twitterShareLink": "http://ssqt.co/mCbcF5",
            "emailShareLink": "http://ssqt.co/mEbcF5",
            "linkedinShareLink": "http://ssqt.co/m3bcF5"
        },
        "EMAIL": {
            "shareLink": "http://ssqt.co/mPbcF5",
            "facebookShareLink": "http://ssqt.co/mTbcF5",
            "twitterShareLink": "http://ssqt.co/mGbcF5",
            "emailShareLink": "http://ssqt.co/mbbcF5",
            "linkedinShareLink": "http://ssqt.co/m1bcF5"
        }
    }
}

Lookup a user by Referral Code GET /api/v1/{tenant_alias}/user

Looks up a user based upon their ReferralCode and returns their personal information. This method is useful for retrieving the user when only the Referral Code is available. For example when a referred user enters a Referral Code during checkout and you want to find out who this Referral Code belongs to.

Tags: User Authentication: APIKey

Arguments

Required referralCode
string

The referralCode of the user you want to retrieve. For example BOBTESTERSON.

Required tenant_alias
string

Tenant being referenced. E.g. "aboih12h16t" or "test_abo912126tastastt"

Example Curl Request

curl -X GET https://app.referralsaasquatch.com/api/v1/{tenant_alias}/user?referralCode=BOBTESTERSON \
-u :API_KEY \

Returns

id
string

The unique identifier provided for this user.

accountId
string

The unique identifier of the Account that this user belongs to.

referralCode
string

The referral code used for sharing by this user

email
string

The email address provided for the user. SaaSquatch uses this to notify someone when they have a successful referral.

imageUrl
string

Optionally used in widgets, emails, and themes. If you provide a absolute profile image URL the minimum image size is 80px x 80px.

firstName
string

The user's first name

lastName
string

The user's last name

firstSeenIP
string
readonly

The user's IP address on indentification

lastSeenIP
string
readonly

The user's last known IP address

dateCreated
integer
readonly

The Unix time stamp of when the user was created

emailHash
string
readonly

The hash of the user's email address

referralSource
string
readonly

The domain from which the user was registered

locale
string

The user's locale, used for Internationalization. The locale must be of the format 'language_COUNTRY' where the language code must be lowercase and the country code must be uppercase. The separator must be an underscore.

shareLinks
object
readonly

Share link for an individual user.

shareLink
string

The unique share link the user can refer their friends with. The Share Link contains the Referral Code for making referrals and a source for Analytics purposes.

facebookShareLink
string

The Share Link for Facebook.

twitterShareLink
string

The Share Link for Twitter.

emailShareLink
string

The Share Link for Email.

mobileShareLink
string

The Share Link for mobile devices.

mobileFacebookShareLink
string

The Share Link for Facebook on mobile devices.

mobileTwitterSharelink
string

The Share Link for Twitter on mobile devices.

mobileEmailShareLink
string

The Share Link for Email on mobile devices.

EMBED
object

An individual user's Share links for use in EMBED.

shareLink
string

The unique share link the user can refer their friends with. The Share Link contains the Referral Code for making referrals and a source for Analytics purposes.

facebookShareLink
string

The Share Link for Facebook.

twitterShareLink
string

The Share Link for Twitter.

emailShareLink
string

The Share Link for Email.

linkedinShareLink
string

The Share Link for linkedin.

POPUP
object

An individual user's Share links for use in POPUP.

shareLink
string

The unique share link the user can refer their friends with. The Share Link contains the Referral Code for making referrals and a source for Analytics purposes.

facebookShareLink
string

The Share Link for Facebook.

twitterShareLink
string

The Share Link for Twitter.

emailShareLink
string

The Share Link for Email.

linkedinShareLink
string

The Share Link for linkedin.

HOSTED
object

An individual user's Share links for use in HOSTED.

shareLink
string

The unique share link the user can refer their friends with. The Share Link contains the Referral Code for making referrals and a source for Analytics purposes.

facebookShareLink
string

The Share Link for Facebook.

twitterShareLink
string

The Share Link for Twitter.

emailShareLink
string

The Share Link for Email.

linkedinShareLink
string

The Share Link for linkedin.

MOBILE
object

An individual user's Share links for use in MOBILE.

shareLink
string

The unique share link the user can refer their friends with. The Share Link contains the Referral Code for making referrals and a source for Analytics purposes.

facebookShareLink
string

The Share Link for Facebook.

twitterShareLink
string

The Share Link for Twitter.

emailShareLink
string

The Share Link for Email.

linkedinShareLink
string

The Share Link for linkedin.

EMAIL
object

An individual user's Share links for use in EMAIL.

shareLink
string

The unique share link the user can refer their friends with. The Share Link contains the Referral Code for making referrals and a source for Analytics purposes.

facebookShareLink
string

The Share Link for Facebook.

twitterShareLink
string

The Share Link for Twitter.

emailShareLink
string

The Share Link for Email.

linkedinShareLink
string

The Share Link for linkedin.

Example Response

HTTP 200
{
    "id": "898746321",
    "accountId": "987321",
    "email": "hello@example.com",
    "firstName": "Henk",
    "lastName": "Thompson",
    "referralCode": "HENKTHOMPSON",
    "imageUrl": "",
    "firstSeenIP": "10.230.163.157",
    "lastSeenIP": "184.66.242.57",
    "dateCreated": 1467222395030,
    "emailHash": "180bc1412a038746af9b37fb782724a2",
    "referralSource": "http://unifiedtestapp.herokuapp.com/",
    "locale": null,
    "shareLinks": {
        "shareLink": "http://ssqt.co/mvbcF5",
        "facebookShareLink": "http://ssqt.co/mmbcF5",
        "twitterShareLink": "http://ssqt.co/mRbcF5",
        "emailShareLink": "http://ssqt.co/mLbcF5",
        "linkedinShareLink": "http://ssqt.co/mLbcF5",
        "mobileShareLink": "http://ssqt.co/mebcF5",
        "mobileFacebookShareLink": "http://ssqt.co/mnbcF5",
        "mobileTwitterShareLink": "http://ssqt.co/mCbcF5",
        "mobileEmailShareLink": "http://ssqt.co/mEbcF5",
        "EMBED": {
            "shareLink": "http://ssqt.co/mQbcF5",
            "facebookShareLink": "http://ssqt.co/mwbcF5",
            "twitterShareLink": "http://ssqt.co/mcbcF5",
            "emailShareLink": "http://ssqt.co/mJbcF5",
            "linkedinShareLink": "http://ssqt.co/mHbcF5"
        },
        "POPUP": {
            "shareLink": "http://ssqt.co/m5bcF5",
            "facebookShareLink": "http://ssqt.co/m9bcF5",
            "twitterShareLink": "http://ssqt.co/mMbcF5",
            "emailShareLink": "http://ssqt.co/mobcF5",
            "linkedinShareLink": "http://ssqt.co/m7bcF5"
        },
        "HOSTED": {
            "shareLink": "http://ssqt.co/mtbcF5",
            "facebookShareLink": "http://ssqt.co/mubcF5",
            "twitterShareLink": "http://ssqt.co/mSbcF5",
            "emailShareLink": "http://ssqt.co/mlbcF5",
            "linkedinShareLink": "http://ssqt.co/mYbcF5"
        },
        "MOBILE": {
            "shareLink": "http://ssqt.co/mebcF5",
            "facebookShareLink": "http://ssqt.co/mnbcF5",
            "twitterShareLink": "http://ssqt.co/mCbcF5",
            "emailShareLink": "http://ssqt.co/mEbcF5",
            "linkedinShareLink": "http://ssqt.co/m3bcF5"
        },
        "EMAIL": {
            "shareLink": "http://ssqt.co/mPbcF5",
            "facebookShareLink": "http://ssqt.co/mTbcF5",
            "twitterShareLink": "http://ssqt.co/mGbcF5",
            "emailShareLink": "http://ssqt.co/mbbcF5",
            "linkedinShareLink": "http://ssqt.co/m1bcF5"
        }
    }
}
statusCode
integer

The HTTP status code of the error

message
string

The human-readable description of what went wrong. Use this to help you debug.

apiErrorCode
string

A machine error code

Example Response

HTTP 404

Lookup a user GET /api/v1/{tenant_alias}/account/{accountId}/user/{userId}

Looks up a user based upon their id and returns their personal information. This method just returns the details of the user in question, and not all associated properties like Rewards, Balances, or Referrals.

Tags: User Authentication: APIKey

Arguments

Required accountId
string

The id of the Account that this user is a member of. See Shared vs. Solo accounts for more info.

Required userId
string

The id of the User to find

Required tenant_alias
string

Tenant being referenced. E.g. "aboih12h16t" or "test_abo912126tastastt"

Example Curl Request

curl -X GET https://app.referralsaasquatch.com/api/v1/{tenant_alias}/account/{accountId}/user/{userId} \
-u :API_KEY \

Returns

id
string

The unique identifier provided for this user.

accountId
string

The unique identifier of the Account that this user belongs to.

referralCode
string

The referral code used for sharing by this user

email
string

The email address provided for the user. SaaSquatch uses this to notify someone when they have a successful referral.

imageUrl
string

Optionally used in widgets, emails, and themes. If you provide a absolute profile image URL the minimum image size is 80px x 80px.

firstName
string

The user's first name

lastName
string

The user's last name

firstSeenIP
string
readonly

The user's IP address on indentification

lastSeenIP
string
readonly

The user's last known IP address

dateCreated
integer
readonly

The Unix time stamp of when the user was created

emailHash
string
readonly

The hash of the user's email address

referralSource
string
readonly

The domain from which the user was registered

locale
string

The user's locale, used for Internationalization. The locale must be of the format 'language_COUNTRY' where the language code must be lowercase and the country code must be uppercase. The separator must be an underscore.

shareLinks
object
readonly

Share link for an individual user.

shareLink
string

The unique share link the user can refer their friends with. The Share Link contains the Referral Code for making referrals and a source for Analytics purposes.

facebookShareLink
string

The Share Link for Facebook.

twitterShareLink
string

The Share Link for Twitter.

emailShareLink
string

The Share Link for Email.

mobileShareLink
string

The Share Link for mobile devices.

mobileFacebookShareLink
string

The Share Link for Facebook on mobile devices.

mobileTwitterSharelink
string

The Share Link for Twitter on mobile devices.

mobileEmailShareLink
string

The Share Link for Email on mobile devices.

EMBED
object

An individual user's Share links for use in EMBED.

shareLink
string

The unique share link the user can refer their friends with. The Share Link contains the Referral Code for making referrals and a source for Analytics purposes.

facebookShareLink
string

The Share Link for Facebook.

twitterShareLink
string

The Share Link for Twitter.

emailShareLink
string

The Share Link for Email.

linkedinShareLink
string

The Share Link for linkedin.

POPUP
object

An individual user's Share links for use in POPUP.

shareLink
string

The unique share link the user can refer their friends with. The Share Link contains the Referral Code for making referrals and a source for Analytics purposes.

facebookShareLink
string

The Share Link for Facebook.

twitterShareLink
string

The Share Link for Twitter.

emailShareLink
string

The Share Link for Email.

linkedinShareLink
string

The Share Link for linkedin.

HOSTED
object

An individual user's Share links for use in HOSTED.

shareLink
string

The unique share link the user can refer their friends with. The Share Link contains the Referral Code for making referrals and a source for Analytics purposes.

facebookShareLink
string

The Share Link for Facebook.

twitterShareLink
string

The Share Link for Twitter.

emailShareLink
string

The Share Link for Email.

linkedinShareLink
string

The Share Link for linkedin.

MOBILE
object

An individual user's Share links for use in MOBILE.

shareLink
string

The unique share link the user can refer their friends with. The Share Link contains the Referral Code for making referrals and a source for Analytics purposes.

facebookShareLink
string

The Share Link for Facebook.

twitterShareLink
string

The Share Link for Twitter.

emailShareLink
string

The Share Link for Email.

linkedinShareLink
string

The Share Link for linkedin.

EMAIL
object

An individual user's Share links for use in EMAIL.

shareLink
string

The unique share link the user can refer their friends with. The Share Link contains the Referral Code for making referrals and a source for Analytics purposes.

facebookShareLink
string

The Share Link for Facebook.

twitterShareLink
string

The Share Link for Twitter.

emailShareLink
string

The Share Link for Email.

linkedinShareLink
string

The Share Link for linkedin.

Example Response

HTTP 200
{
    "id": "898746321",
    "accountId": "987321",
    "email": "hello@example.com",
    "firstName": "Henk",
    "lastName": "Thompson",
    "referralCode": "HENKTHOMPSON",
    "imageUrl": "",
    "firstSeenIP": "10.230.163.157",
    "lastSeenIP": "184.66.242.57",
    "dateCreated": 1467222395030,
    "emailHash": "180bc1412a038746af9b37fb782724a2",
    "referralSource": "http://unifiedtestapp.herokuapp.com/",
    "locale": null,
    "shareLinks": {
        "shareLink": "http://ssqt.co/mvbcF5",
        "facebookShareLink": "http://ssqt.co/mmbcF5",
        "twitterShareLink": "http://ssqt.co/mRbcF5",
        "emailShareLink": "http://ssqt.co/mLbcF5",
        "linkedinShareLink": "http://ssqt.co/mLbcF5",
        "mobileShareLink": "http://ssqt.co/mebcF5",
        "mobileFacebookShareLink": "http://ssqt.co/mnbcF5",
        "mobileTwitterShareLink": "http://ssqt.co/mCbcF5",
        "mobileEmailShareLink": "http://ssqt.co/mEbcF5",
        "EMBED": {
            "shareLink": "http://ssqt.co/mQbcF5",
            "facebookShareLink": "http://ssqt.co/mwbcF5",
            "twitterShareLink": "http://ssqt.co/mcbcF5",
            "emailShareLink": "http://ssqt.co/mJbcF5",
            "linkedinShareLink": "http://ssqt.co/mHbcF5"
        },
        "POPUP": {
            "shareLink": "http://ssqt.co/m5bcF5",
            "facebookShareLink": "http://ssqt.co/m9bcF5",
            "twitterShareLink": "http://ssqt.co/mMbcF5",
            "emailShareLink": "http://ssqt.co/mobcF5",
            "linkedinShareLink": "http://ssqt.co/m7bcF5"
        },
        "HOSTED": {
            "shareLink": "http://ssqt.co/mtbcF5",
            "facebookShareLink": "http://ssqt.co/mubcF5",
            "twitterShareLink": "http://ssqt.co/mSbcF5",
            "emailShareLink": "http://ssqt.co/mlbcF5",
            "linkedinShareLink": "http://ssqt.co/mYbcF5"
        },
        "MOBILE": {
            "shareLink": "http://ssqt.co/mebcF5",
            "facebookShareLink": "http://ssqt.co/mnbcF5",
            "twitterShareLink": "http://ssqt.co/mCbcF5",
            "emailShareLink": "http://ssqt.co/mEbcF5",
            "linkedinShareLink": "http://ssqt.co/m3bcF5"
        },
        "EMAIL": {
            "shareLink": "http://ssqt.co/mPbcF5",
            "facebookShareLink": "http://ssqt.co/mTbcF5",
            "twitterShareLink": "http://ssqt.co/mGbcF5",
            "emailShareLink": "http://ssqt.co/mbbcF5",
            "linkedinShareLink": "http://ssqt.co/m1bcF5"
        }
    }
}
statusCode
integer

The HTTP status code of the error

message
string

The human-readable description of what went wrong. Use this to help you debug.

apiErrorCode
string

A machine error code

Example Response

HTTP 404

Gets the share links for a user. Share links are the links that people use to refer their friends and are the same links used in the Referral SaaSquatch widgets. The main use case for this method is to look up share links to include in other channels like email marketing, CRM and product integration when a widget or mobile webview can't be easily used. For example, one could write "Share this link with your friends, and get rewarded when they sign up" and include the share link looked up using this method.

All share links work by dropping a tracking cookie when someone clicks the link and redirecting the new user to a landing page. This cookie includes the value of the referral code of the person that shared it. The cookie can be read using the autofill function of Squatch.js and is also passed along as the rsCode parameter in the redirect. For example http://ssqt.co/pZVp redirects to https://www.google.ca/?rsCode=THIRDUSER.

There are many share links for each user, each one tagged with additional metadata for tracking the effectiveness of sharing channels. For example the facebookShareLink is used in the share on Facebook functionality of the widget. When people share on facebook using the widget that facebookShareLink will be posted on their wall so that when new people click on that link they will be tracked as a referral and attributed back to Facebook. Note that this does not necessarily guarantee tracking; the generic shareLink could simply be copied and pasted on to Facebook, and due to limitation on http referer information passed on by browsers, it may not be possible to determine which share medium a new sign up came from.

In some cases it is preferable to have users share their referral code with friends instead of sharing their referral link. For example mobile apps and cookie blocking may prevent a share link from successfully tracking a referral, and having an input box for "Referral Code" on your product sign up form gets around these limitations and will ensure that more types of referrals can be tracked. Use the Lookup a user API call to find a user's referral code.

Tags: User Authentication: APIKey

Arguments

Required tenant_alias
string

Tenant being referenced. E.g. "aboih12h16t" or "test_abo912126tastastt"

Required accountId
string

The ID of the account to look up

Required userId
string

Filters share links by user.id.

Example Curl Request

curl -X GET https://app.referralsaasquatch.com/api/v1/{tenant_alias}/account/{accountId}/user/{userId}/sharelinks \
-u :API_KEY \

Returns

List users GET /api/v1/{tenant_alias}/users

List all of the Users in your Referral SaaSquatch tenant. This method is the primary way of getting a full list of everyone that has been identified through the API, Squatch.js or mobile widgets. This method supports pagination using the parameters for limit and offset to iterate through a very large list of records. You can also search for particular users using the query method. To find information about which users have completed referrals, use the List referrals method.

Tags: User Authentication: APIKey

Arguments

query
string

A search query that can be used to filter users by email, name or ID.

limit
integer

A limit on the number of results returned. Defaults to 10.

offset
integer

When included offsets the first result returns in the list. Use this to paginate through a long list of results. Defaults to 0

Required tenant_alias
string

Tenant being referenced. E.g. "aboih12h16t" or "test_abo912126tastastt"

Example Curl Request

curl -X GET https://app.referralsaasquatch.com/api/v1/{tenant_alias}/users \
-u :API_KEY \

Returns

users
array

A list of User objects. This is the actual data in this list envelope.

id
string

The unique identifier provided for this user.

accountId
string

The unique identifier of the Account that this user belongs to.

referralCode
string

The referral code used for sharing by this user

email
string

The email address provided for the user. SaaSquatch uses this to notify someone when they have a successful referral.

imageUrl
string

Optionally used in widgets, emails, and themes. If you provide a absolute profile image URL the minimum image size is 80px x 80px.

firstName
string

The user's first name

lastName
string

The user's last name

firstSeenIP
string
readonly

The user's IP address on indentification

lastSeenIP
string
readonly

The user's last known IP address

dateCreated
integer
readonly

The Unix time stamp of when the user was created

emailHash
string
readonly

The hash of the user's email address

referralSource
string
readonly

The domain from which the user was registered

locale
string

The user's locale, used for Internationalization. The locale must be of the format 'language_COUNTRY' where the language code must be lowercase and the country code must be uppercase. The separator must be an underscore.

shareLinks
object
readonly

Share link for an individual user.

shareLink
string

The unique share link the user can refer their friends with. The Share Link contains the Referral Code for making referrals and a source for Analytics purposes.

facebookShareLink
string

The Share Link for Facebook.

twitterShareLink
string

The Share Link for Twitter.

emailShareLink
string

The Share Link for Email.

mobileShareLink
string

The Share Link for mobile devices.

mobileFacebookShareLink
string

The Share Link for Facebook on mobile devices.

mobileTwitterSharelink
string

The Share Link for Twitter on mobile devices.

mobileEmailShareLink
string

The Share Link for Email on mobile devices.

EMBED
object

An individual user's Share links for use in EMBED.

shareLink
string

The unique share link the user can refer their friends with. The Share Link contains the Referral Code for making referrals and a source for Analytics purposes.

facebookShareLink
string

The Share Link for Facebook.

twitterShareLink
string

The Share Link for Twitter.

emailShareLink
string

The Share Link for Email.

linkedinShareLink
string

The Share Link for linkedin.

POPUP
object

An individual user's Share links for use in POPUP.

shareLink
string

The unique share link the user can refer their friends with. The Share Link contains the Referral Code for making referrals and a source for Analytics purposes.

facebookShareLink
string

The Share Link for Facebook.

twitterShareLink
string

The Share Link for Twitter.

emailShareLink
string

The Share Link for Email.

linkedinShareLink
string

The Share Link for linkedin.

HOSTED
object

An individual user's Share links for use in HOSTED.

shareLink
string

The unique share link the user can refer their friends with. The Share Link contains the Referral Code for making referrals and a source for Analytics purposes.

facebookShareLink
string

The Share Link for Facebook.

twitterShareLink
string

The Share Link for Twitter.

emailShareLink
string

The Share Link for Email.

linkedinShareLink
string

The Share Link for linkedin.

MOBILE
object

An individual user's Share links for use in MOBILE.

shareLink
string

The unique share link the user can refer their friends with. The Share Link contains the Referral Code for making referrals and a source for Analytics purposes.

facebookShareLink
string

The Share Link for Facebook.

twitterShareLink
string

The Share Link for Twitter.

emailShareLink
string

The Share Link for Email.

linkedinShareLink
string

The Share Link for linkedin.

EMAIL
object

An individual user's Share links for use in EMAIL.

shareLink
string

The unique share link the user can refer their friends with. The Share Link contains the Referral Code for making referrals and a source for Analytics purposes.

facebookShareLink
string

The Share Link for Facebook.

twitterShareLink
string

The Share Link for Twitter.

emailShareLink
string

The Share Link for Email.

linkedinShareLink
string

The Share Link for linkedin.

count
integer

The number of results returned in this list, see totalCount for all rows.

totalCount
integer

The total number of results available overall, see count for the number of rows in this list.

Example Response

HTTP 200
{
    "count": 1,
    "totalCount": 1,
    "users": [
        {
            "id": "14125",
            "accountId": "89842",
            "email": "mark@example.com",
            "firstName": "Mark",
            "lastName": "Testerson",
            "referralCode": "MARKTESTER",
            "imageUrl": "",
            "dateCreated": 1414452680584,
            "emailHash": "a65a76ba72e5a0b1e6253efce357abb6"
        }
    ]
}

Lookup a referral code GET /api/v1/{tenant_alias}/code/{code}

Looks up a referral code and the attached details

Tags: Referral Code Authentication: APIKey

Arguments

Required code
string

The referral code to look up. E.g. "BOBTESTERSON"

Required tenant_alias
string

Tenant being referenced. E.g. "aboih12h16t" or "test_abo912126tastastt"

Example Curl Request

curl -X GET https://app.referralsaasquatch.com/api/v1/{tenant_alias}/code/{code} \
-u :API_KEY \

Returns

code
string

The unique identifier for the code. E.g. "BOBTESTERSON"

dateCreated
integer

The date the code was created.

referrerName
string

The name of the owner of this code. E.g. "Bob Testerson"

reward
object

Details of the reward that could be earned -- but is not yet earned.

type
string

The type of reward.

Possible values: PCT_DISCOUNT, FEATURE, TIME_CREDIT, or CREDIT

unit
string

An identifier for the unit of the reward. E.g. "credit-in-cents", "freemb", "giftcard20", "tshirt", "freemonth". Only works with types FEATURE, TIME_CREDIT, CREDIT

credit
integer

The amount of credit that this referral code is valid for. e.g. for $20 this object would have credit=2000, unit="cents". Only works for TIME_CREDIT, CREDIT

discountPercent
integer

The percent discount that the referral code is valid for. E.g. "10" for "10%". Only works with PCT_DISCOUNT

monthsDiscountIsValid
integer

When this reward is set to expire.

featureType
string

A unique identifier for the type of feature. Only works with types FEATURE

name
string

The human readable name of the feature. Only works with types FEATURE

description
string

The human readable description of the feature. Only works with types FEATURE

quantity
integer

The quantity of feature that this referral code is valid for. Only works with types FEATURE

Example Response

HTTP 200
{
    "code": "BOBTESTERSON",
    "dateCreated": 1411600868797,
    "referrerName": "Bob Testerson",
    "reward": {
        "id": "5462600de4b09b1c41108f2e",
        "type": "PCT_DISCOUNT",
        "dateGiven": 1415733261275,
        "dateExpires": null,
        "dateCancelled": null,
        "accountId": "613611",
        "userId": "876343",
        "cancellable": true,
        "rewardSource": "REFERRED",
        "discountPercent": 20,
        "unit": "%"
    }
}
statusCode
integer

The HTTP status code of the error

message
string

The human-readable description of what went wrong. Use this to help you debug.

apiErrorCode
string

A machine error code

Example Response

HTTP 404

List referrals GET /api/v1/{tenant_alias}/referrals

List all of the referrals in your Referral SaaSquatch tenant. This method is the primary way of getting a full list of everyone that has made a referral and everyone that has been referred, and supports pagination using the parameters for limit and offset to iterate through a very large list of records. You can also use the query parameters for referringAccountId and referringUserId to filters this list of referrals to only include those made by a given user.

Tags: Referral Authentication: APIKey

Arguments

referringAccountId
string

When included, filters the results to only referrals that were referred users with this AccountId

referringUserId
string

When included, filters the results to only referrals that were referred users with this UserId

dateReferralPaid
string

When included, filters the results either to the exact timestamp if only one value is given, or a range if devided by a comma. I.E. 0,123412451 gives all referrals that converted between 0 and 123412451.

dateReferralEnded
string

When included, filters the results either to the exact timestamp if only one value is given, or a range if devided by a comma. I.E. 0,123412451 gives all referrals that ended between 0 and 123412451.

referredModerationStatus
string

When included, filters the result to only include referred users with that status. Statuses that are accepted: PENDING, APPROVED or DENIED.

referrerModerationStatus
string

When included, filters the result to only include referrers with that status. Statuses that are accepted: PENDING, APPROVED or DENIED.

limit
integer

A limit on the number of results returned. Defaults to 10.

offset
integer

When included offsets the first result returns in the list. Use this to paginate through a long list of results. Defaults to 0

Required tenant_alias
string

Tenant being referenced. E.g. "aboih12h16t" or "test_abo912126tastastt"

Example Curl Request

curl -X GET https://app.referralsaasquatch.com/api/v1/{tenant_alias}/referrals \
-u :API_KEY \

Returns

referrals
array

A list of Referral objects. This is the actual data in this list envelope.

id
string

Unique identifier for the Referral object

referredUser
object

An object describing an individual user. Users are used in SaaSquatch to track people/contacts/leads. When a referral happens, it always happens between two Users.

id
string

The unique identifier provided for this user.

accountId
string

The unique identifier of the Account that this user belongs to.

referralCode
string

The referral code used for sharing by this user

email
string

The email address provided for the user. SaaSquatch uses this to notify someone when they have a successful referral.

imageUrl
string

Optionally used in widgets, emails, and themes. If you provide a absolute profile image URL the minimum image size is 80px x 80px.

firstName
string

The user's first name

lastName
string

The user's last name

firstSeenIP
string
readonly

The user's IP address on indentification

lastSeenIP
string
readonly

The user's last known IP address

dateCreated
integer
readonly

The Unix time stamp of when the user was created

emailHash
string
readonly

The hash of the user's email address

referralSource
string
readonly

The domain from which the user was registered

locale
string

The user's locale, used for Internationalization. The locale must be of the format 'language_COUNTRY' where the language code must be lowercase and the country code must be uppercase. The separator must be an underscore.

shareLinks
object
readonly

Share link for an individual user.

shareLink
string

The unique share link the user can refer their friends with. The Share Link contains the Referral Code for making referrals and a source for Analytics purposes.

facebookShareLink
string

The Share Link for Facebook.

twitterShareLink
string

The Share Link for Twitter.

emailShareLink
string

The Share Link for Email.

mobileShareLink
string

The Share Link for mobile devices.

mobileFacebookShareLink
string

The Share Link for Facebook on mobile devices.

mobileTwitterSharelink
string

The Share Link for Twitter on mobile devices.

mobileEmailShareLink
string

The Share Link for Email on mobile devices.

EMBED
object

An individual user's Share links for use in EMBED.

shareLink
string

The unique share link the user can refer their friends with. The Share Link contains the Referral Code for making referrals and a source for Analytics purposes.

facebookShareLink
string

The Share Link for Facebook.

twitterShareLink
string

The Share Link for Twitter.

emailShareLink
string

The Share Link for Email.

linkedinShareLink
string

The Share Link for linkedin.

POPUP
object

An individual user's Share links for use in POPUP.

shareLink
string

The unique share link the user can refer their friends with. The Share Link contains the Referral Code for making referrals and a source for Analytics purposes.

facebookShareLink
string

The Share Link for Facebook.

twitterShareLink
string

The Share Link for Twitter.

emailShareLink
string

The Share Link for Email.

linkedinShareLink
string

The Share Link for linkedin.

HOSTED
object

An individual user's Share links for use in HOSTED.

shareLink
string

The unique share link the user can refer their friends with. The Share Link contains the Referral Code for making referrals and a source for Analytics purposes.

facebookShareLink
string

The Share Link for Facebook.

twitterShareLink
string

The Share Link for Twitter.

emailShareLink
string

The Share Link for Email.

linkedinShareLink
string

The Share Link for linkedin.

MOBILE
object

An individual user's Share links for use in MOBILE.

shareLink
string

The unique share link the user can refer their friends with. The Share Link contains the Referral Code for making referrals and a source for Analytics purposes.

facebookShareLink
string

The Share Link for Facebook.

twitterShareLink
string

The Share Link for Twitter.

emailShareLink
string

The Share Link for Email.

linkedinShareLink
string

The Share Link for linkedin.

EMAIL
object

An individual user's Share links for use in EMAIL.

shareLink
string

The unique share link the user can refer their friends with. The Share Link contains the Referral Code for making referrals and a source for Analytics purposes.

facebookShareLink
string

The Share Link for Facebook.

twitterShareLink
string

The Share Link for Twitter.

emailShareLink
string

The Share Link for Email.

linkedinShareLink
string

The Share Link for linkedin.

referrerUser
object

An object describing an individual user. Users are used in SaaSquatch to track people/contacts/leads. When a referral happens, it always happens between two Users.

id
string

The unique identifier provided for this user.

accountId
string

The unique identifier of the Account that this user belongs to.

referralCode
string

The referral code used for sharing by this user

email
string

The email address provided for the user. SaaSquatch uses this to notify someone when they have a successful referral.

imageUrl
string

Optionally used in widgets, emails, and themes. If you provide a absolute profile image URL the minimum image size is 80px x 80px.

firstName
string

The user's first name

lastName
string

The user's last name

firstSeenIP
string
readonly

The user's IP address on indentification

lastSeenIP
string
readonly

The user's last known IP address

dateCreated
integer
readonly

The Unix time stamp of when the user was created

emailHash
string
readonly

The hash of the user's email address

referralSource
string
readonly

The domain from which the user was registered

locale
string

The user's locale, used for Internationalization. The locale must be of the format 'language_COUNTRY' where the language code must be lowercase and the country code must be uppercase. The separator must be an underscore.

shareLinks
object
readonly

Share link for an individual user.

shareLink
string

The unique share link the user can refer their friends with. The Share Link contains the Referral Code for making referrals and a source for Analytics purposes.

facebookShareLink
string

The Share Link for Facebook.

twitterShareLink
string

The Share Link for Twitter.

emailShareLink
string

The Share Link for Email.

mobileShareLink
string

The Share Link for mobile devices.

mobileFacebookShareLink
string

The Share Link for Facebook on mobile devices.

mobileTwitterSharelink
string

The Share Link for Twitter on mobile devices.

mobileEmailShareLink
string

The Share Link for Email on mobile devices.

EMBED
object

An individual user's Share links for use in EMBED.

shareLink
string

The unique share link the user can refer their friends with. The Share Link contains the Referral Code for making referrals and a source for Analytics purposes.

facebookShareLink
string

The Share Link for Facebook.

twitterShareLink
string

The Share Link for Twitter.

emailShareLink
string

The Share Link for Email.

linkedinShareLink
string

The Share Link for linkedin.

POPUP
object

An individual user's Share links for use in POPUP.

shareLink
string

The unique share link the user can refer their friends with. The Share Link contains the Referral Code for making referrals and a source for Analytics purposes.

facebookShareLink
string

The Share Link for Facebook.

twitterShareLink
string

The Share Link for Twitter.

emailShareLink
string

The Share Link for Email.

linkedinShareLink
string

The Share Link for linkedin.

HOSTED
object

An individual user's Share links for use in HOSTED.

shareLink
string

The unique share link the user can refer their friends with. The Share Link contains the Referral Code for making referrals and a source for Analytics purposes.

facebookShareLink
string

The Share Link for Facebook.

twitterShareLink
string

The Share Link for Twitter.

emailShareLink
string

The Share Link for Email.

linkedinShareLink
string

The Share Link for linkedin.

MOBILE
object

An individual user's Share links for use in MOBILE.

shareLink
string

The unique share link the user can refer their friends with. The Share Link contains the Referral Code for making referrals and a source for Analytics purposes.

facebookShareLink
string

The Share Link for Facebook.

twitterShareLink
string

The Share Link for Twitter.

emailShareLink
string

The Share Link for Email.

linkedinShareLink
string

The Share Link for linkedin.

EMAIL
object

An individual user's Share links for use in EMAIL.

shareLink
string

The unique share link the user can refer their friends with. The Share Link contains the Referral Code for making referrals and a source for Analytics purposes.

facebookShareLink
string

The Share Link for Facebook.

twitterShareLink
string

The Share Link for Twitter.

emailShareLink
string

The Share Link for Email.

linkedinShareLink
string

The Share Link for linkedin.

referredReward
object

Rewards are used in SaaSquatch to track the credits, discounts, gift cards and other prizes that a User earns.

id
string

The unique identifier for this reward

type
string

The type of reward.

Possible values: PCT_DISCOUNT, FEATURE, TIME_CREDIT, or CREDIT

dateGiven
integer

Timestamp of when this reward was earned.

dateExpires
integer

Timestamp of when this reward is set to expire.

dateCancelled
integer

Timestamp if the reward is cancellable and has been cancelled, the date it was cancelled on. Null if not never cancelled.

cancellable
boolean

If a reward is cancellable then it may be revoked. If it has been cancelled then dateCancelled will be non-null.

rewardSource
string

The type of the source of the reward.

Possible values: FRIEND_SIGNUP, REFERRED, or MANUAL

unit
string

An identifier for the unit of the reward. E.g. 'credit-in-cents', 'freemb', 'giftcard20', 'tshirt', 'freemonth' or '%'

discountPercent
integer

The percent discount. E.g. 10 means 10% Works with: PCT_DISCOUNT

featureType
string

A unique identifier for the type of feature. E.g. 'freeSeats' or 'freeMb'. Works with: FEATURE

name
string

The name of the feature. e.g. 'Free Seats' or 'Free Storage' Works with: FEATURE

description
string

The feature description. e.g. 'Bonus user seats for your account' or 'Extra megabytes of free storage' Works with: FEATURE

quantity
integer

The earned quantity of the feature Works with:FEATURE

assignedCredit
integer

The earned quantity of the feature. Works with: TIME_CREDIT or CREDIT

redeemedCredit
integer

The redeemed quantity of the feature. Works with: TIME_CREDIT or CREDIT

currency
string

For programs that require a currency. Works with: CREDIT

referrerReward
object

Rewards are used in SaaSquatch to track the credits, discounts, gift cards and other prizes that a User earns.

id
string

The unique identifier for this reward

type
string

The type of reward.

Possible values: PCT_DISCOUNT, FEATURE, TIME_CREDIT, or CREDIT

dateGiven
integer

Timestamp of when this reward was earned.

dateExpires
integer

Timestamp of when this reward is set to expire.

dateCancelled
integer

Timestamp if the reward is cancellable and has been cancelled, the date it was cancelled on. Null if not never cancelled.

cancellable
boolean

If a reward is cancellable then it may be revoked. If it has been cancelled then dateCancelled will be non-null.

rewardSource
string

The type of the source of the reward.

Possible values: FRIEND_SIGNUP, REFERRED, or MANUAL

unit
string

An identifier for the unit of the reward. E.g. 'credit-in-cents', 'freemb', 'giftcard20', 'tshirt', 'freemonth' or '%'

discountPercent
integer

The percent discount. E.g. 10 means 10% Works with: PCT_DISCOUNT

featureType
string

A unique identifier for the type of feature. E.g. 'freeSeats' or 'freeMb'. Works with: FEATURE

name
string

The name of the feature. e.g. 'Free Seats' or 'Free Storage' Works with: FEATURE

description
string

The feature description. e.g. 'Bonus user seats for your account' or 'Extra megabytes of free storage' Works with: FEATURE

quantity
integer

The earned quantity of the feature Works with:FEATURE

assignedCredit
integer

The earned quantity of the feature. Works with: TIME_CREDIT or CREDIT

redeemedCredit
integer

The redeemed quantity of the feature. Works with: TIME_CREDIT or CREDIT

currency
string

For programs that require a currency. Works with: CREDIT

moderationStatus
string

When referrals are manually managed, each referral has a PENDING state until it is explicitly moderated.

Possible values: PENDING, or ACTIONED

referredModerationStatus
string

Used to identify the referred user's moderation status and affect Reward cancellation.

Possible values: PENDING, APPROVED, or DENIED

referrerModerationStatus
string

Used to identify the referrer user's moderation status and affect Reward cancellation.

Possible values: PENDING, APPROVED, or DENIED

fraudSignals
object

Information about signals of potential fraud on the referral

name
object

Information about an individual fraud signal on the referral

message
String

A human readable description of the fraud signal. For example: 'Referrer and referred have very similar names'

score
integer

A numeric score that describes the severity of the fraud signal.

ip
object

Information about an individual fraud signal on the referral

message
String

A human readable description of the fraud signal. For example: 'Referrer and referred have very similar names'

score
integer

A numeric score that describes the severity of the fraud signal.

email
object

Information about an individual fraud signal on the referral

message
String

A human readable description of the fraud signal. For example: 'Referrer and referred have very similar names'

score
integer

A numeric score that describes the severity of the fraud signal.

rate
object

Information about an individual fraud signal on the referral

message
String

A human readable description of the fraud signal. For example: 'Referrer and referred have very similar names'

score
integer

A numeric score that describes the severity of the fraud signal.

dateReferralStarted
integer

Timestamp of when this referral was started.

dateReferralPaid
integer

Timestamp of when this referral was marked as PAID.

dateReferralEnded
integer

Timestamp of when this referral was ended.

dateModerated
integer

Timestamp of when this referral was last moderated.

count
integer

The number of results returned in this list, see totalCount for all rows.

totalCount
integer

The total number of results available overall, see count for the number of rows in this list.

Example Response

HTTP 200
{
    "count": 2,
    "totalCount": 4,
    "referrals": [
        {
            "id": "5462600de4b09b1c41108f28",
            "referredUser": {
                "id": "898746321",
                "accountId": "987321",
                "email": "hello@example.com",
                "firstName": "Henk",
                "lastName": "Thompson",
                "referralCode": "HENKTHOMPSON",
                "imageUrl": "",
                "firstSeenIP": "10.230.163.157",
                "lastSeenIP": "184.66.242.57",
                "dateCreated": 1467222395030,
                "emailHash": "180bc1412a038746af9b37fb782724a2",
                "referralSource": "http://unifiedtestapp.herokuapp.com/",
                "locale": null,
                "shareLinks": {
                    "shareLink": "http://ssqt.co/mvbcF5",
                    "facebookShareLink": "http://ssqt.co/mmbcF5",
                    "twitterShareLink": "http://ssqt.co/mRbcF5",
                    "emailShareLink": "http://ssqt.co/mLbcF5",
                    "linkedinShareLink": "http://ssqt.co/mLbcF5",
                    "mobileShareLink": "http://ssqt.co/mebcF5",
                    "mobileFacebookShareLink": "http://ssqt.co/mnbcF5",
                    "mobileTwitterShareLink": "http://ssqt.co/mCbcF5",
                    "mobileEmailShareLink": "http://ssqt.co/mEbcF5",
                    "EMBED": {
                        "shareLink": "http://ssqt.co/mQbcF5",
                        "facebookShareLink": "http://ssqt.co/mwbcF5",
                        "twitterShareLink": "http://ssqt.co/mcbcF5",
                        "emailShareLink": "http://ssqt.co/mJbcF5",
                        "linkedinShareLink": "http://ssqt.co/mHbcF5"
                    },
                    "POPUP": {
                        "shareLink": "http://ssqt.co/m5bcF5",
                        "facebookShareLink": "http://ssqt.co/m9bcF5",
                        "twitterShareLink": "http://ssqt.co/mMbcF5",
                        "emailShareLink": "http://ssqt.co/mobcF5",
                        "linkedinShareLink": "http://ssqt.co/m7bcF5"
                    },
                    "HOSTED": {
                        "shareLink": "http://ssqt.co/mtbcF5",
                        "facebookShareLink": "http://ssqt.co/mubcF5",
                        "twitterShareLink": "http://ssqt.co/mSbcF5",
                        "emailShareLink": "http://ssqt.co/mlbcF5",
                        "linkedinShareLink": "http://ssqt.co/mYbcF5"
                    },
                    "MOBILE": {
                        "shareLink": "http://ssqt.co/mebcF5",
                        "facebookShareLink": "http://ssqt.co/mnbcF5",
                        "twitterShareLink": "http://ssqt.co/mCbcF5",
                        "emailShareLink": "http://ssqt.co/mEbcF5",
                        "linkedinShareLink": "http://ssqt.co/m3bcF5"
                    },
                    "EMAIL": {
                        "shareLink": "http://ssqt.co/mPbcF5",
                        "facebookShareLink": "http://ssqt.co/mTbcF5",
                        "twitterShareLink": "http://ssqt.co/mGbcF5",
                        "emailShareLink": "http://ssqt.co/mbbcF5",
                        "linkedinShareLink": "http://ssqt.co/m1bcF5"
                    }
                }
            },
            "referrerUser": {
                "id": "898746321",
                "accountId": "987321",
                "email": "hello@example.com",
                "firstName": "Henk",
                "lastName": "Thompson",
                "referralCode": "HENKTHOMPSON",
                "imageUrl": "",
                "firstSeenIP": "10.230.163.157",
                "lastSeenIP": "184.66.242.57",
                "dateCreated": 1467222395030,
                "emailHash": "180bc1412a038746af9b37fb782724a2",
                "referralSource": "http://unifiedtestapp.herokuapp.com/",
                "locale": null,
                "shareLinks": {
                    "shareLink": "http://ssqt.co/mvbcF5",
                    "facebookShareLink": "http://ssqt.co/mmbcF5",
                    "twitterShareLink": "http://ssqt.co/mRbcF5",
                    "emailShareLink": "http://ssqt.co/mLbcF5",
                    "linkedinShareLink": "http://ssqt.co/mLbcF5",
                    "mobileShareLink": "http://ssqt.co/mebcF5",
                    "mobileFacebookShareLink": "http://ssqt.co/mnbcF5",
                    "mobileTwitterShareLink": "http://ssqt.co/mCbcF5",
                    "mobileEmailShareLink": "http://ssqt.co/mEbcF5",
                    "EMBED": {
                        "shareLink": "http://ssqt.co/mQbcF5",
                        "facebookShareLink": "http://ssqt.co/mwbcF5",
                        "twitterShareLink": "http://ssqt.co/mcbcF5",
                        "emailShareLink": "http://ssqt.co/mJbcF5",
                        "linkedinShareLink": "http://ssqt.co/mHbcF5"
                    },
                    "POPUP": {
                        "shareLink": "http://ssqt.co/m5bcF5",
                        "facebookShareLink": "http://ssqt.co/m9bcF5",
                        "twitterShareLink": "http://ssqt.co/mMbcF5",
                        "emailShareLink": "http://ssqt.co/mobcF5",
                        "linkedinShareLink": "http://ssqt.co/m7bcF5"
                    },
                    "HOSTED": {
                        "shareLink": "http://ssqt.co/mtbcF5",
                        "facebookShareLink": "http://ssqt.co/mubcF5",
                        "twitterShareLink": "http://ssqt.co/mSbcF5",
                        "emailShareLink": "http://ssqt.co/mlbcF5",
                        "linkedinShareLink": "http://ssqt.co/mYbcF5"
                    },
                    "MOBILE": {
                        "shareLink": "http://ssqt.co/mebcF5",
                        "facebookShareLink": "http://ssqt.co/mnbcF5",
                        "twitterShareLink": "http://ssqt.co/mCbcF5",
                        "emailShareLink": "http://ssqt.co/mEbcF5",
                        "linkedinShareLink": "http://ssqt.co/m3bcF5"
                    },
                    "EMAIL": {
                        "shareLink": "http://ssqt.co/mPbcF5",
                        "facebookShareLink": "http://ssqt.co/mTbcF5",
                        "twitterShareLink": "http://ssqt.co/mGbcF5",
                        "emailShareLink": "http://ssqt.co/mbbcF5",
                        "linkedinShareLink": "http://ssqt.co/m1bcF5"
                    }
                }
            },
            "referredReward": {
                "id": "5462600de4b09b1c41108f2e",
                "type": "PCT_DISCOUNT",
                "dateGiven": 1415733261275,
                "dateExpires": null,
                "dateCancelled": null,
                "accountId": "613611",
                "userId": "876343",
                "cancellable": true,
                "rewardSource": "REFERRED",
                "discountPercent": 20,
                "unit": "%"
            },
            "referrerReward": null,
            "moderationStatus": "ACTIONED",
            "dateReferralStarted": 1415733261238,
            "dateReferralPaid": null,
            "dateReferralEnded": null,
            "dateModerated": 1427410131006,
            "referredModerationStatus": "APPROVED",
            "referrerModerationStatus": "APPROVED"
        },
        {
            "id": "546270a6e4b0c1871186a920",
            "referredUser": {
                "id": "898746321",
                "accountId": "987321",
                "email": "hello@example.com",
                "firstName": "Henk",
                "lastName": "Thompson",
                "referralCode": "HENKTHOMPSON",
                "imageUrl": "",
                "firstSeenIP": "10.230.163.157",
                "lastSeenIP": "184.66.242.57",
                "dateCreated": 1467222395030,
                "emailHash": "180bc1412a038746af9b37fb782724a2",
                "referralSource": "http://unifiedtestapp.herokuapp.com/",
                "locale": null,
                "shareLinks": {
                    "shareLink": "http://ssqt.co/mvbcF5",
                    "facebookShareLink": "http://ssqt.co/mmbcF5",
                    "twitterShareLink": "http://ssqt.co/mRbcF5",
                    "emailShareLink": "http://ssqt.co/mLbcF5",
                    "linkedinShareLink": "http://ssqt.co/mLbcF5",
                    "mobileShareLink": "http://ssqt.co/mebcF5",
                    "mobileFacebookShareLink": "http://ssqt.co/mnbcF5",
                    "mobileTwitterShareLink": "http://ssqt.co/mCbcF5",
                    "mobileEmailShareLink": "http://ssqt.co/mEbcF5",
                    "EMBED": {
                        "shareLink": "http://ssqt.co/mQbcF5",
                        "facebookShareLink": "http://ssqt.co/mwbcF5",
                        "twitterShareLink": "http://ssqt.co/mcbcF5",
                        "emailShareLink": "http://ssqt.co/mJbcF5",
                        "linkedinShareLink": "http://ssqt.co/mHbcF5"
                    },
                    "POPUP": {
                        "shareLink": "http://ssqt.co/m5bcF5",
                        "facebookShareLink": "http://ssqt.co/m9bcF5",
                        "twitterShareLink": "http://ssqt.co/mMbcF5",
                        "emailShareLink": "http://ssqt.co/mobcF5",
                        "linkedinShareLink": "http://ssqt.co/m7bcF5"
                    },
                    "HOSTED": {
                        "shareLink": "http://ssqt.co/mtbcF5",
                        "facebookShareLink": "http://ssqt.co/mubcF5",
                        "twitterShareLink": "http://ssqt.co/mSbcF5",
                        "emailShareLink": "http://ssqt.co/mlbcF5",
                        "linkedinShareLink": "http://ssqt.co/mYbcF5"
                    },
                    "MOBILE": {
                        "shareLink": "http://ssqt.co/mebcF5",
                        "facebookShareLink": "http://ssqt.co/mnbcF5",
                        "twitterShareLink": "http://ssqt.co/mCbcF5",
                        "emailShareLink": "http://ssqt.co/mEbcF5",
                        "linkedinShareLink": "http://ssqt.co/m3bcF5"
                    },
                    "EMAIL": {
                        "shareLink": "http://ssqt.co/mPbcF5",
                        "facebookShareLink": "http://ssqt.co/mTbcF5",
                        "twitterShareLink": "http://ssqt.co/mGbcF5",
                        "emailShareLink": "http://ssqt.co/mbbcF5",
                        "linkedinShareLink": "http://ssqt.co/m1bcF5"
                    }
                }
            },
            "referrerUser": {
                "id": "898746321",
                "accountId": "987321",
                "email": "hello@example.com",
                "firstName": "Henk",
                "lastName": "Thompson",
                "referralCode": "HENKTHOMPSON",
                "imageUrl": "",
                "firstSeenIP": "10.230.163.157",
                "lastSeenIP": "184.66.242.57",
                "dateCreated": 1467222395030,
                "emailHash": "180bc1412a038746af9b37fb782724a2",
                "referralSource": "http://unifiedtestapp.herokuapp.com/",
                "locale": null,
                "shareLinks": {
                    "shareLink": "http://ssqt.co/mvbcF5",
                    "facebookShareLink": "http://ssqt.co/mmbcF5",
                    "twitterShareLink": "http://ssqt.co/mRbcF5",
                    "emailShareLink": "http://ssqt.co/mLbcF5",
                    "linkedinShareLink": "http://ssqt.co/mLbcF5",
                    "mobileShareLink": "http://ssqt.co/mebcF5",
                    "mobileFacebookShareLink": "http://ssqt.co/mnbcF5",
                    "mobileTwitterShareLink": "http://ssqt.co/mCbcF5",
                    "mobileEmailShareLink": "http://ssqt.co/mEbcF5",
                    "EMBED": {
                        "shareLink": "http://ssqt.co/mQbcF5",
                        "facebookShareLink": "http://ssqt.co/mwbcF5",
                        "twitterShareLink": "http://ssqt.co/mcbcF5",
                        "emailShareLink": "http://ssqt.co/mJbcF5",
                        "linkedinShareLink": "http://ssqt.co/mHbcF5"
                    },
                    "POPUP": {
                        "shareLink": "http://ssqt.co/m5bcF5",
                        "facebookShareLink": "http://ssqt.co/m9bcF5",
                        "twitterShareLink": "http://ssqt.co/mMbcF5",
                        "emailShareLink": "http://ssqt.co/mobcF5",
                        "linkedinShareLink": "http://ssqt.co/m7bcF5"
                    },
                    "HOSTED": {
                        "shareLink": "http://ssqt.co/mtbcF5",
                        "facebookShareLink": "http://ssqt.co/mubcF5",
                        "twitterShareLink": "http://ssqt.co/mSbcF5",
                        "emailShareLink": "http://ssqt.co/mlbcF5",
                        "linkedinShareLink": "http://ssqt.co/mYbcF5"
                    },
                    "MOBILE": {
                        "shareLink": "http://ssqt.co/mebcF5",
                        "facebookShareLink": "http://ssqt.co/mnbcF5",
                        "twitterShareLink": "http://ssqt.co/mCbcF5",
                        "emailShareLink": "http://ssqt.co/mEbcF5",
                        "linkedinShareLink": "http://ssqt.co/m3bcF5"
                    },
                    "EMAIL": {
                        "shareLink": "http://ssqt.co/mPbcF5",
                        "facebookShareLink": "http://ssqt.co/mTbcF5",
                        "twitterShareLink": "http://ssqt.co/mGbcF5",
                        "emailShareLink": "http://ssqt.co/mbbcF5",
                        "linkedinShareLink": "http://ssqt.co/m1bcF5"
                    }
                }
            },
            "referredReward": {
                "id": "5462600de4b09b1c41108f2e",
                "type": "PCT_DISCOUNT",
                "dateGiven": 1415733261275,
                "dateExpires": null,
                "dateCancelled": null,
                "accountId": "613611",
                "userId": "876343",
                "cancellable": true,
                "rewardSource": "REFERRED",
                "discountPercent": 20,
                "unit": "%"
            },
            "referrerReward": {
                "id": "5462600de4b09b1c41108f2e",
                "type": "PCT_DISCOUNT",
                "dateGiven": 1415733261275,
                "dateExpires": null,
                "dateCancelled": null,
                "accountId": "613611",
                "userId": "876343",
                "cancellable": true,
                "rewardSource": "REFERRED",
                "discountPercent": 20,
                "unit": "%"
            },
            "moderationStatus": "ACTIONED",
            "dateReferralStarted": 1415737510411,
            "dateReferralPaid": 1415737557217,
            "dateReferralEnded": null,
            "dateModerated": 1427410131029,
            "referredModerationStatus": "APPROVED",
            "referrerModerationStatus": "APPROVED",
            "fraudSignals": {
                "ip": {
                    "message": "Referrer and referred came from the same IP",
                    "score": 50
                }
            }
        }
    ]
}

Lookup a Referral GET /api/v1/{tenant_alias}/referrals/{referralId}

Looks up a single Referral object by it's associated id. This method is helpful for looking into a particular referral of interest. Since it requires the id of the referral to be specified, it isn't applicable for querying all referrals to find those made by a particular user or account. To query for those referrals use the list referrals endpoint instead with query parameters specified.

Tags: Referral Authentication: APIKey

Arguments

Required referralId
string

The id of the referral to look up

Required tenant_alias
string

Tenant being referenced. E.g. "aboih12h16t" or "test_abo912126tastastt"

Example Curl Request

curl -X GET https://app.referralsaasquatch.com/api/v1/{tenant_alias}/referrals/{referralId} \
-u :API_KEY \

Returns

id
string

Unique identifier for the Referral object

referredUser
object

An object describing an individual user. Users are used in SaaSquatch to track people/contacts/leads. When a referral happens, it always happens between two Users.

id
string

The unique identifier provided for this user.

accountId
string

The unique identifier of the Account that this user belongs to.

referralCode
string

The referral code used for sharing by this user

email
string

The email address provided for the user. SaaSquatch uses this to notify someone when they have a successful referral.

imageUrl
string

Optionally used in widgets, emails, and themes. If you provide a absolute profile image URL the minimum image size is 80px x 80px.

firstName
string

The user's first name

lastName
string

The user's last name

firstSeenIP
string
readonly

The user's IP address on indentification

lastSeenIP
string
readonly

The user's last known IP address

dateCreated
integer
readonly

The Unix time stamp of when the user was created

emailHash
string
readonly

The hash of the user's email address

referralSource
string
readonly

The domain from which the user was registered

locale
string

The user's locale, used for Internationalization. The locale must be of the format 'language_COUNTRY' where the language code must be lowercase and the country code must be uppercase. The separator must be an underscore.

shareLinks
object
readonly

Share link for an individual user.

shareLink
string

The unique share link the user can refer their friends with. The Share Link contains the Referral Code for making referrals and a source for Analytics purposes.

facebookShareLink
string

The Share Link for Facebook.

twitterShareLink
string

The Share Link for Twitter.

emailShareLink
string

The Share Link for Email.

mobileShareLink
string

The Share Link for mobile devices.

mobileFacebookShareLink
string

The Share Link for Facebook on mobile devices.

mobileTwitterSharelink
string

The Share Link for Twitter on mobile devices.

mobileEmailShareLink
string

The Share Link for Email on mobile devices.

EMBED
object

An individual user's Share links for use in EMBED.

shareLink
string

The unique share link the user can refer their friends with. The Share Link contains the Referral Code for making referrals and a source for Analytics purposes.

facebookShareLink
string

The Share Link for Facebook.

twitterShareLink
string

The Share Link for Twitter.

emailShareLink
string

The Share Link for Email.

linkedinShareLink
string

The Share Link for linkedin.

POPUP
object

An individual user's Share links for use in POPUP.

shareLink
string

The unique share link the user can refer their friends with. The Share Link contains the Referral Code for making referrals and a source for Analytics purposes.

facebookShareLink
string

The Share Link for Facebook.

twitterShareLink
string

The Share Link for Twitter.

emailShareLink
string

The Share Link for Email.

linkedinShareLink
string

The Share Link for linkedin.

HOSTED
object

An individual user's Share links for use in HOSTED.

shareLink
string

The unique share link the user can refer their friends with. The Share Link contains the Referral Code for making referrals and a source for Analytics purposes.

facebookShareLink
string

The Share Link for Facebook.

twitterShareLink
string

The Share Link for Twitter.

emailShareLink
string

The Share Link for Email.

linkedinShareLink
string

The Share Link for linkedin.

MOBILE
object

An individual user's Share links for use in MOBILE.

shareLink
string

The unique share link the user can refer their friends with. The Share Link contains the Referral Code for making referrals and a source for Analytics purposes.

facebookShareLink
string

The Share Link for Facebook.

twitterShareLink
string

The Share Link for Twitter.

emailShareLink
string

The Share Link for Email.

linkedinShareLink
string

The Share Link for linkedin.

EMAIL
object

An individual user's Share links for use in EMAIL.

shareLink
string

The unique share link the user can refer their friends with. The Share Link contains the Referral Code for making referrals and a source for Analytics purposes.

facebookShareLink
string

The Share Link for Facebook.

twitterShareLink
string

The Share Link for Twitter.

emailShareLink
string

The Share Link for Email.

linkedinShareLink
string

The Share Link for linkedin.

referrerUser
object

An object describing an individual user. Users are used in SaaSquatch to track people/contacts/leads. When a referral happens, it always happens between two Users.

id
string

The unique identifier provided for this user.

accountId
string

The unique identifier of the Account that this user belongs to.

referralCode
string

The referral code used for sharing by this user

email
string

The email address provided for the user. SaaSquatch uses this to notify someone when they have a successful referral.

imageUrl
string

Optionally used in widgets, emails, and themes. If you provide a absolute profile image URL the minimum image size is 80px x 80px.

firstName
string

The user's first name

lastName
string

The user's last name

firstSeenIP
string
readonly

The user's IP address on indentification

lastSeenIP
string
readonly

The user's last known IP address

dateCreated
integer
readonly

The Unix time stamp of when the user was created

emailHash
string
readonly

The hash of the user's email address

referralSource
string
readonly

The domain from which the user was registered

locale
string

The user's locale, used for Internationalization. The locale must be of the format 'language_COUNTRY' where the language code must be lowercase and the country code must be uppercase. The separator must be an underscore.

shareLinks
object
readonly

Share link for an individual user.

shareLink
string

The unique share link the user can refer their friends with. The Share Link contains the Referral Code for making referrals and a source for Analytics purposes.

facebookShareLink
string

The Share Link for Facebook.

twitterShareLink
string

The Share Link for Twitter.

emailShareLink
string

The Share Link for Email.

mobileShareLink
string

The Share Link for mobile devices.

mobileFacebookShareLink
string

The Share Link for Facebook on mobile devices.

mobileTwitterSharelink
string

The Share Link for Twitter on mobile devices.

mobileEmailShareLink
string

The Share Link for Email on mobile devices.

EMBED
object

An individual user's Share links for use in EMBED.

shareLink
string

The unique share link the user can refer their friends with. The Share Link contains the Referral Code for making referrals and a source for Analytics purposes.

facebookShareLink
string

The Share Link for Facebook.

twitterShareLink
string

The Share Link for Twitter.

emailShareLink
string

The Share Link for Email.

linkedinShareLink
string

The Share Link for linkedin.

POPUP
object

An individual user's Share links for use in POPUP.

shareLink
string

The unique share link the user can refer their friends with. The Share Link contains the Referral Code for making referrals and a source for Analytics purposes.

facebookShareLink
string

The Share Link for Facebook.

twitterShareLink
string

The Share Link for Twitter.

emailShareLink
string

The Share Link for Email.

linkedinShareLink
string

The Share Link for linkedin.

HOSTED
object

An individual user's Share links for use in HOSTED.

shareLink
string

The unique share link the user can refer their friends with. The Share Link contains the Referral Code for making referrals and a source for Analytics purposes.

facebookShareLink
string

The Share Link for Facebook.

twitterShareLink
string

The Share Link for Twitter.

emailShareLink
string

The Share Link for Email.

linkedinShareLink
string

The Share Link for linkedin.

MOBILE
object

An individual user's Share links for use in MOBILE.

shareLink
string

The unique share link the user can refer their friends with. The Share Link contains the Referral Code for making referrals and a source for Analytics purposes.

facebookShareLink
string

The Share Link for Facebook.

twitterShareLink
string

The Share Link for Twitter.

emailShareLink
string

The Share Link for Email.

linkedinShareLink
string

The Share Link for linkedin.

EMAIL
object

An individual user's Share links for use in EMAIL.

shareLink
string

The unique share link the user can refer their friends with. The Share Link contains the Referral Code for making referrals and a source for Analytics purposes.

facebookShareLink
string

The Share Link for Facebook.

twitterShareLink
string

The Share Link for Twitter.

emailShareLink
string

The Share Link for Email.

linkedinShareLink
string

The Share Link for linkedin.

referredReward
object

Rewards are used in SaaSquatch to track the credits, discounts, gift cards and other prizes that a User earns.

id
string

The unique identifier for this reward

type
string

The type of reward.

Possible values: PCT_DISCOUNT, FEATURE, TIME_CREDIT, or CREDIT

dateGiven
integer

Timestamp of when this reward was earned.

dateExpires
integer

Timestamp of when this reward is set to expire.

dateCancelled
integer

Timestamp if the reward is cancellable and has been cancelled, the date it was cancelled on. Null if not never cancelled.

cancellable
boolean

If a reward is cancellable then it may be revoked. If it has been cancelled then dateCancelled will be non-null.

rewardSource
string

The type of the source of the reward.

Possible values: FRIEND_SIGNUP, REFERRED, or MANUAL

unit
string

An identifier for the unit of the reward. E.g. 'credit-in-cents', 'freemb', 'giftcard20', 'tshirt', 'freemonth' or '%'

discountPercent
integer

The percent discount. E.g. 10 means 10% Works with: PCT_DISCOUNT

featureType
string

A unique identifier for the type of feature. E.g. 'freeSeats' or 'freeMb'. Works with: FEATURE

name
string

The name of the feature. e.g. 'Free Seats' or 'Free Storage' Works with: FEATURE

description
string

The feature description. e.g. 'Bonus user seats for your account' or 'Extra megabytes of free storage' Works with: FEATURE

quantity
integer

The earned quantity of the feature Works with:FEATURE

assignedCredit
integer

The earned quantity of the feature. Works with: TIME_CREDIT or CREDIT

redeemedCredit
integer

The redeemed quantity of the feature. Works with: TIME_CREDIT or CREDIT

currency
string

For programs that require a currency. Works with: CREDIT

referrerReward
object

Rewards are used in SaaSquatch to track the credits, discounts, gift cards and other prizes that a User earns.

id
string

The unique identifier for this reward

type
string

The type of reward.

Possible values: PCT_DISCOUNT, FEATURE, TIME_CREDIT, or CREDIT

dateGiven
integer

Timestamp of when this reward was earned.

dateExpires
integer

Timestamp of when this reward is set to expire.

dateCancelled
integer

Timestamp if the reward is cancellable and has been cancelled, the date it was cancelled on. Null if not never cancelled.

cancellable
boolean

If a reward is cancellable then it may be revoked. If it has been cancelled then dateCancelled will be non-null.

rewardSource
string

The type of the source of the reward.

Possible values: FRIEND_SIGNUP, REFERRED, or MANUAL

unit
string

An identifier for the unit of the reward. E.g. 'credit-in-cents', 'freemb', 'giftcard20', 'tshirt', 'freemonth' or '%'

discountPercent
integer

The percent discount. E.g. 10 means 10% Works with: PCT_DISCOUNT

featureType
string

A unique identifier for the type of feature. E.g. 'freeSeats' or 'freeMb'. Works with: FEATURE

name
string

The name of the feature. e.g. 'Free Seats' or 'Free Storage' Works with: FEATURE

description
string

The feature description. e.g. 'Bonus user seats for your account' or 'Extra megabytes of free storage' Works with: FEATURE

quantity
integer

The earned quantity of the feature Works with:FEATURE

assignedCredit
integer

The earned quantity of the feature. Works with: TIME_CREDIT or CREDIT

redeemedCredit
integer

The redeemed quantity of the feature. Works with: TIME_CREDIT or CREDIT

currency
string

For programs that require a currency. Works with: CREDIT

moderationStatus
string

When referrals are manually managed, each referral has a PENDING state until it is explicitly moderated.

Possible values: PENDING, or ACTIONED

referredModerationStatus
string

Used to identify the referred user's moderation status and affect Reward cancellation.

Possible values: PENDING, APPROVED, or DENIED

referrerModerationStatus
string

Used to identify the referrer user's moderation status and affect Reward cancellation.

Possible values: PENDING, APPROVED, or DENIED

fraudSignals
object

Information about signals of potential fraud on the referral

name
object

Information about an individual fraud signal on the referral

message
String

A human readable description of the fraud signal. For example: 'Referrer and referred have very similar names'

score
integer

A numeric score that describes the severity of the fraud signal.

ip
object

Information about an individual fraud signal on the referral

message
String

A human readable description of the fraud signal. For example: 'Referrer and referred have very similar names'

score
integer

A numeric score that describes the severity of the fraud signal.

email
object

Information about an individual fraud signal on the referral

message
String

A human readable description of the fraud signal. For example: 'Referrer and referred have very similar names'

score
integer

A numeric score that describes the severity of the fraud signal.

rate
object

Information about an individual fraud signal on the referral

message
String

A human readable description of the fraud signal. For example: 'Referrer and referred have very similar names'

score
integer

A numeric score that describes the severity of the fraud signal.

dateReferralStarted
integer

Timestamp of when this referral was started.

dateReferralPaid
integer

Timestamp of when this referral was marked as PAID.

dateReferralEnded
integer

Timestamp of when this referral was ended.

dateModerated
integer

Timestamp of when this referral was last moderated.

Example Response

HTTP 200
{
    "id": "546270a6e4b0c1871186a920",
    "referredUser": {
        "id": "898746321",
        "accountId": "987321",
        "email": "hello@example.com",
        "firstName": "Henk",
        "lastName": "Thompson",
        "referralCode": "HENKTHOMPSON",
        "imageUrl": "",
        "firstSeenIP": "10.230.163.157",
        "lastSeenIP": "184.66.242.57",
        "dateCreated": 1467222395030,
        "emailHash": "180bc1412a038746af9b37fb782724a2",
        "referralSource": "http://unifiedtestapp.herokuapp.com/",
        "locale": null,
        "shareLinks": {
            "shareLink": "http://ssqt.co/mvbcF5",
            "facebookShareLink": "http://ssqt.co/mmbcF5",
            "twitterShareLink": "http://ssqt.co/mRbcF5",
            "emailShareLink": "http://ssqt.co/mLbcF5",
            "linkedinShareLink": "http://ssqt.co/mLbcF5",
            "mobileShareLink": "http://ssqt.co/mebcF5",
            "mobileFacebookShareLink": "http://ssqt.co/mnbcF5",
            "mobileTwitterShareLink": "http://ssqt.co/mCbcF5",
            "mobileEmailShareLink": "http://ssqt.co/mEbcF5",
            "EMBED": {
                "shareLink": "http://ssqt.co/mQbcF5",
                "facebookShareLink": "http://ssqt.co/mwbcF5",
                "twitterShareLink": "http://ssqt.co/mcbcF5",
                "emailShareLink": "http://ssqt.co/mJbcF5",
                "linkedinShareLink": "http://ssqt.co/mHbcF5"
            },
            "POPUP": {
                "shareLink": "http://ssqt.co/m5bcF5",
                "facebookShareLink": "http://ssqt.co/m9bcF5",
                "twitterShareLink": "http://ssqt.co/mMbcF5",
                "emailShareLink": "http://ssqt.co/mobcF5",
                "linkedinShareLink": "http://ssqt.co/m7bcF5"
            },
            "HOSTED": {
                "shareLink": "http://ssqt.co/mtbcF5",
                "facebookShareLink": "http://ssqt.co/mubcF5",
                "twitterShareLink": "http://ssqt.co/mSbcF5",
                "emailShareLink": "http://ssqt.co/mlbcF5",
                "linkedinShareLink": "http://ssqt.co/mYbcF5"
            },
            "MOBILE": {
                "shareLink": "http://ssqt.co/mebcF5",
                "facebookShareLink": "http://ssqt.co/mnbcF5",
                "twitterShareLink": "http://ssqt.co/mCbcF5",
                "emailShareLink": "http://ssqt.co/mEbcF5",
                "linkedinShareLink": "http://ssqt.co/m3bcF5"
            },
            "EMAIL": {
                "shareLink": "http://ssqt.co/mPbcF5",
                "facebookShareLink": "http://ssqt.co/mTbcF5",
                "twitterShareLink": "http://ssqt.co/mGbcF5",
                "emailShareLink": "http://ssqt.co/mbbcF5",
                "linkedinShareLink": "http://ssqt.co/m1bcF5"
            }
        }
    },
    "referrerUser": {
        "id": "898746321",
        "accountId": "987321",
        "email": "hello@example.com",
        "firstName": "Henk",
        "lastName": "Thompson",
        "referralCode": "HENKTHOMPSON",
        "imageUrl": "",
        "firstSeenIP": "10.230.163.157",
        "lastSeenIP": "184.66.242.57",
        "dateCreated": 1467222395030,
        "emailHash": "180bc1412a038746af9b37fb782724a2",
        "referralSource": "http://unifiedtestapp.herokuapp.com/",
        "locale": null,
        "shareLinks": {
            "shareLink": "http://ssqt.co/mvbcF5",
            "facebookShareLink": "http://ssqt.co/mmbcF5",
            "twitterShareLink": "http://ssqt.co/mRbcF5",
            "emailShareLink": "http://ssqt.co/mLbcF5",
            "linkedinShareLink": "http://ssqt.co/mLbcF5",
            "mobileShareLink": "http://ssqt.co/mebcF5",
            "mobileFacebookShareLink": "http://ssqt.co/mnbcF5",
            "mobileTwitterShareLink": "http://ssqt.co/mCbcF5",
            "mobileEmailShareLink": "http://ssqt.co/mEbcF5",
            "EMBED": {
                "shareLink": "http://ssqt.co/mQbcF5",
                "facebookShareLink": "http://ssqt.co/mwbcF5",
                "twitterShareLink": "http://ssqt.co/mcbcF5",
                "emailShareLink": "http://ssqt.co/mJbcF5",
                "linkedinShareLink": "http://ssqt.co/mHbcF5"
            },
            "POPUP": {
                "shareLink": "http://ssqt.co/m5bcF5",
                "facebookShareLink": "http://ssqt.co/m9bcF5",
                "twitterShareLink": "http://ssqt.co/mMbcF5",
                "emailShareLink": "http://ssqt.co/mobcF5",
                "linkedinShareLink": "http://ssqt.co/m7bcF5"
            },
            "HOSTED": {
                "shareLink": "http://ssqt.co/mtbcF5",
                "facebookShareLink": "http://ssqt.co/mubcF5",
                "twitterShareLink": "http://ssqt.co/mSbcF5",
                "emailShareLink": "http://ssqt.co/mlbcF5",
                "linkedinShareLink": "http://ssqt.co/mYbcF5"
            },
            "MOBILE": {
                "shareLink": "http://ssqt.co/mebcF5",
                "facebookShareLink": "http://ssqt.co/mnbcF5",
                "twitterShareLink": "http://ssqt.co/mCbcF5",
                "emailShareLink": "http://ssqt.co/mEbcF5",
                "linkedinShareLink": "http://ssqt.co/m3bcF5"
            },
            "EMAIL": {
                "shareLink": "http://ssqt.co/mPbcF5",
                "facebookShareLink": "http://ssqt.co/mTbcF5",
                "twitterShareLink": "http://ssqt.co/mGbcF5",
                "emailShareLink": "http://ssqt.co/mbbcF5",
                "linkedinShareLink": "http://ssqt.co/m1bcF5"
            }
        }
    },
    "referredReward": {
        "id": "5462600de4b09b1c41108f2e",
        "type": "PCT_DISCOUNT",
        "dateGiven": 1415733261275,
        "dateExpires": null,
        "dateCancelled": null,
        "accountId": "613611",
        "userId": "876343",
        "cancellable": true,
        "rewardSource": "REFERRED",
        "discountPercent": 20,
        "unit": "%"
    },
    "referrerReward": {
        "id": "5462600de4b09b1c41108f2e",
        "type": "PCT_DISCOUNT",
        "dateGiven": 1415733261275,
        "dateExpires": null,
        "dateCancelled": null,
        "accountId": "613611",
        "userId": "876343",
        "cancellable": true,
        "rewardSource": "REFERRED",
        "discountPercent": 20,
        "unit": "%"
    },
    "moderationStatus": "ACTIONED",
    "dateReferralStarted": 1415737510411,
    "dateReferralPaid": 1415737557217,
    "dateReferralEnded": null,
    "dateModerated": 1427410131029,
    "referredModerationStatus": "APPROVED",
    "referrerModerationStatus": "APPROVED",
    "fraudSignals": null
}
statusCode
integer

The HTTP status code of the error

message
string

The human-readable description of what went wrong. Use this to help you debug.

apiErrorCode
string

A machine error code

Example Response

HTTP 404

Moderate referrals POST /api/v1/{tenant_alias}/referrals/moderate

Moderates one or several referrals by either approving or denying. Moderation can apply to one side of a referral, the other side, or both sides (Referrer and Referred). When a referral is denied, the associated reward will be "cancelled". A referral can be moderated several times, subsequently cancelling and un-cancelling the associated reward or rewards, and can be done as long as the associated reward is cancellable. Some rewards such as the coupons automatically generated by Referral SaaSquatch into Stripe and Recurly are not cancellable and requests to change the moderation will error.

Tags: Referral Authentication: APIKey

Arguments

Required moderationBulkRequest
JSON Body

Details of the referrals to be moderated

Required actions
array

A list of individual moderation actions for specific referrals. Limited to a maximum of 100 actions per request

Required referralId
string

The id of the Referral to be moderated

Required action
string

The type of moderation action.

Possible values: APPROVED, DENIED, REFERRER_APPROVED, REFERRED_APPROVED, REFERRER_DENIED, or REFERRED_DENIED

Required tenant_alias
string

Tenant being referenced. E.g. "aboih12h16t" or "test_abo912126tastastt"

Example Curl Request

curl -X POST https://app.referralsaasquatch.com/api/v1/{tenant_alias}/referrals/moderate \
-u :API_KEY \
-H "Content-Type: application/json" \
-d '{
    "actions": [
        {
            "referralId": "546270a6e4b0c1871186a920",
            "action": "REFERRED_DENIED"
        }
    ]
}'

Returns

Example Response

HTTP 200

List reward balances GET /api/v1/{tenant_alias}/reward/balance

Looks up the balance for all rewards of the same type and units.

Tags: Reward Balance Authentication: APIKey

Arguments

Required accountId
string

The ID of the account to look up

userId
string

Filters rewards by user.id.

rewardTypeFilter
string

Filters rewards by type.

featureTypeFilter
string

Filters rewards by feature type. Works with FEATURE types.

Required tenant_alias
string

Tenant being referenced. E.g. "aboih12h16t" or "test_abo912126tastastt"

Example Curl Request

curl -X GET https://app.referralsaasquatch.com/api/v1/{tenant_alias}/reward/balance?accountId= \
-u :API_KEY \

Returns

type
string

The type of reward.

Possible values: PCT_DISCOUNT, FEATURE, TIME_CREDIT, or CREDIT

unit
string

An identifier for the unit of the reward. E.g. "credit-in-cents", "freemb", "giftcard20", "tshirt", "freemonth". Only works with types FEATURE, TIME_CREDIT, CREDIT

count
integer

"The number of rewards earned. Usually is equal to the number of successful referrals made. E.g. An account has $80 of credit due to the referral program. $60 from making referrals, $20 from being referred. The count would be 4 rewards, each worth $20. Only works for FEATURE, TIME_CREDIT, CREDIT"

featureType
string

A unique identifier for the type of feature. Only works with types FEATURE

totalAssignedCredit
integer

The total assignedCredit for all reward credits of the same unit type. Only works with types: TIME_CREDIT, CREDIT

totalRedeemedCredit
integer

The total redeemedCredit for all reward credits of the same unit type. Only works with types: TIME_CREDIT, CREDIT

totalDiscountPercent
integer

The total discountPercent from all rewards. Only works with types: PCT_DISCOUNT

referredDiscountPercent
integer

The total discountPercent from rewards with rewardSource = REFERRED Only works with types: PCT_DISCOUNT

referrerDiscountPercent
integer

The total discountPercent from rewards with rewardSource = FRIEND_SIGNUP Only works with types: PCT_DISCOUNT

Example Response

HTTP 200
[
    {
        "id": "5462600de4b09b1c41108f2e",
        "type": "PCT_DISCOUNT",
        "dateGiven": 1415733261275,
        "dateExpires": null,
        "dateCancelled": null,
        "accountId": "613611",
        "userId": "876343",
        "cancellable": true,
        "rewardSource": "REFERRED",
        "discountPercent": 20,
        "unit": "%"
    },
    {
        "id": "582142aae4b05442a5fa01a5",
        "type": "CREDIT",
        "dateGiven": 1478574762838,
        "dateExpires": null,
        "dateCancelled": null,
        "accountId": "613611",
        "userId": "876343",
        "cancellable": true,
        "rewardSource": "REFERRED",
        "unit": "CENTS",
        "assignedCredit": 2500,
        "redeemedCredit": 0,
        "name": "Dollar Credit",
        "currency": null
    }
]

Debit a reward balance POST /api/v1/{tenant_alias}/credit/bulkredeem

Used to redeem the credit earned from a referral program. Permanently debits an account balance. Works with: TIME_CREDIT and CREDIT

Tags: Reward Balance Authentication: APIKey

Arguments

Required debit
JSON Body

Details of the debit

Required accountId
string

The ID of the account to be debitted.

Required unit
string

The type of credit to be debitted. E.g. "free-months" or "cents"

Required amount
integer

The amount of credit to be debitted.

Required tenant_alias
string

Tenant being referenced. E.g. "aboih12h16t" or "test_abo912126tastastt"

Example Curl Request

curl -X POST https://app.referralsaasquatch.com/api/v1/{tenant_alias}/credit/bulkredeem \
-u :API_KEY \
-H "Content-Type: application/json" \
-d '{
    "accountId": "abc123",
    "unit": "cents",
    "amount": 200
}'

Returns

creditRedeemed
integer

The amount of credit that was just debitted.

creditAvailable
integer

The remaining credit in this account of the same unit type.

unit
string

The type of credit that was just debitted.

Example Response

HTTP 200
{
    "creditRedeemed": 200,
    "creditAvailable": 0,
    "unit": "cents"
}

List an account's rewards GET /api/v1/{tenant_alias}/reward

Looks up a list of single rewards

Tags: Reward Authentication: APIKey

Arguments

Required accountId
string

The ID of the account to look up

userId
string

Filters rewards by user.id.

rewardTypeFilter
string

Filters rewards by type.

featureTypeFilter
string

Filters rewards by feature type. Works with FEATURE types.

Required tenant_alias
string

Tenant being referenced. E.g. "aboih12h16t" or "test_abo912126tastastt"

Example Curl Request

curl -X GET https://app.referralsaasquatch.com/api/v1/{tenant_alias}/reward?accountId= \
-u :API_KEY \

Returns

id
string

The unique identifier for this reward

type
string

The type of reward.

Possible values: PCT_DISCOUNT, FEATURE, TIME_CREDIT, or CREDIT

dateGiven
integer

Timestamp of when this reward was earned.

dateExpires
integer

Timestamp of when this reward is set to expire.

dateCancelled
integer

Timestamp if the reward is cancellable and has been cancelled, the date it was cancelled on. Null if not never cancelled.

cancellable
boolean

If a reward is cancellable then it may be revoked. If it has been cancelled then dateCancelled will be non-null.

rewardSource
string

The type of the source of the reward.

Possible values: FRIEND_SIGNUP, REFERRED, or MANUAL

unit
string

An identifier for the unit of the reward. E.g. 'credit-in-cents', 'freemb', 'giftcard20', 'tshirt', 'freemonth' or '%'

discountPercent
integer

The percent discount. E.g. 10 means 10% Works with: PCT_DISCOUNT

featureType
string

A unique identifier for the type of feature. E.g. 'freeSeats' or 'freeMb'. Works with: FEATURE

name
string

The name of the feature. e.g. 'Free Seats' or 'Free Storage' Works with: FEATURE

description
string

The feature description. e.g. 'Bonus user seats for your account' or 'Extra megabytes of free storage' Works with: FEATURE

quantity
integer

The earned quantity of the feature Works with:FEATURE

assignedCredit
integer

The earned quantity of the feature. Works with: TIME_CREDIT or CREDIT

redeemedCredit
integer

The redeemed quantity of the feature. Works with: TIME_CREDIT or CREDIT

currency
string

For programs that require a currency. Works with: CREDIT

Example Response

HTTP 200
[
    {
        "id": "5462600de4b09b1c41108f2e",
        "type": "PCT_DISCOUNT",
        "dateGiven": 1415733261275,
        "dateExpires": null,
        "dateCancelled": null,
        "accountId": "613611",
        "userId": "876343",
        "cancellable": true,
        "rewardSource": "REFERRED",
        "discountPercent": 20,
        "unit": "%"
    }
]

Redeem a single reward POST /api/v1/{tenant_alias}/credit/{id}/redeem

Used to redeem an individual credit earned from a referral program. Works with: TIME_CREDIT and CREDIT

Tags: Reward Authentication: APIKey

Arguments

Required id
string

The ID of the specific reward to be redeemed

Required debit
JSON Body

Details of the debit

Required amount
integer

The amount of credit to be debitted.

Required unit
string

The type of credit to be debitted. E.g. "free-months" or "cents"

Required tenant_alias
string

Tenant being referenced. E.g. "aboih12h16t" or "test_abo912126tastastt"

Example Curl Request

curl -X POST https://app.referralsaasquatch.com/api/v1/{tenant_alias}/credit/{id}/redeem \
-u :API_KEY \
-H "Content-Type: application/json" \
-d '{
    "amount": 200,
    "unit": "cents"
}'

Returns

creditRedeemed
integer

The amount of credit that was just debitted.

creditAvailable
integer

The remaining credit in this account of the same unit type.

unit
string

The type of credit that was just debitted.

Example Response

HTTP 200
{
    "creditRedeemed": 200,
    "creditAvailable": 1800,
    "unit": "cents"
}

Create a single reward POST /api/v1/{tenant_alias}/rewards/account/{accountId}/user/{userId}

Used to create a reward for a specified user. Note that the reward will only be redeemed automatically if the default program supports automatic redemption for the provided reward type (see the install guides for more on automatic redemption).

Tags: Reward Authentication: APIKey

Arguments

Required userId
string

The ID of the user that will be given the reward

Required accountId
string

The ID of the account that will be given the reward

Required reward
JSON Body

Details of the reward to create

type
string

The type of reward.

Possible values: PCT_DISCOUNT, FEATURE, TIME_CREDIT, or CREDIT

dateExpires
integer

Timestamp of when this reward is set to expire. Works with: PCT_DISCOUNT or FEATURE

cancellable
boolean

If a reward is cancellable then it may be revoked. If it has been cancelled then dateCancelled will be non-null.

unit
string

An identifier for the unit of the reward. E.g. 'credit-in-cents', 'freemb', 'giftcard20', 'tshirt', 'freemonth' or '%'. Works with: TIME_CREDIT FEATURE or CREDIT

discountPercent
integer

The percent discount. E.g. 10 means 10% Works with: PCT_DISCOUNT

featureType
string

A unique identifier for the type of feature. E.g. 'freeSeats' or 'freeMb'. Works with: FEATURE

quantity
integer

The earned quantity of the feature Works with:FEATURE

assignedCredit
integer

The earned quantity of the feature. Works with: TIME_CREDIT or CREDIT

currency
string

For programs that require a currency. Works with: CREDIT

Required tenant_alias
string

Tenant being referenced. E.g. "aboih12h16t" or "test_abo912126tastastt"

Example Curl Request

curl -X POST https://app.referralsaasquatch.com/api/v1/{tenant_alias}/rewards/account/{accountId}/user/{userId} \
-u :API_KEY \
-H "Content-Type: application/json" \
-d '{
    "type": "PCT_DISCOUNT",
    "dateExpires": 1471028988000,
    "cancellable": true,
    "discountPercent": 15
}'

Returns

id
string

The unique identifier for this reward

type
string

The type of reward.

Possible values: PCT_DISCOUNT, FEATURE, TIME_CREDIT, or CREDIT

dateGiven
integer

Timestamp of when this reward was earned.

dateExpires
integer

Timestamp of when this reward is set to expire.

dateCancelled
integer

Timestamp if the reward is cancellable and has been cancelled, the date it was cancelled on. Null if not never cancelled.

cancellable
boolean

If a reward is cancellable then it may be revoked. If it has been cancelled then dateCancelled will be non-null.

rewardSource
string

The type of the source of the reward.

Possible values: FRIEND_SIGNUP, REFERRED, or MANUAL

unit
string

An identifier for the unit of the reward. E.g. 'credit-in-cents', 'freemb', 'giftcard20', 'tshirt', 'freemonth' or '%'

discountPercent
integer

The percent discount. E.g. 10 means 10% Works with: PCT_DISCOUNT

featureType
string

A unique identifier for the type of feature. E.g. 'freeSeats' or 'freeMb'. Works with: FEATURE

name
string

The name of the feature. e.g. 'Free Seats' or 'Free Storage' Works with: FEATURE

description
string

The feature description. e.g. 'Bonus user seats for your account' or 'Extra megabytes of free storage' Works with: FEATURE

quantity
integer

The earned quantity of the feature Works with:FEATURE

assignedCredit
integer

The earned quantity of the feature. Works with: TIME_CREDIT or CREDIT

redeemedCredit
integer

The redeemed quantity of the feature. Works with: TIME_CREDIT or CREDIT

currency
string

For programs that require a currency. Works with: CREDIT

Example Response

HTTP 201
{
    "id": "5462600de4b09b1c41108f2e",
    "type": "PCT_DISCOUNT",
    "dateGiven": 1415733261275,
    "dateExpires": null,
    "dateCancelled": null,
    "accountId": "613611",
    "userId": "876343",
    "cancellable": true,
    "rewardSource": "REFERRED",
    "discountPercent": 20,
    "unit": "%"
}

Create a user and account POST /api/v1/{tenant_alias}/open/account/{accountId}/user/{userId}

This method creates a user and an account in one call. Because this call creates a user, it requires either a write token or an API key.

This is an Open Endpoint and disabled by default. Contact support to enable the open endpoints.

Tags: User Open Endpoint Authentication: APIKey UserJWT

Arguments

Required accountId
string

The account to create

Required userId
string

The user to create

Required user
JSON Body
Required id
string

The unique identifier provided for this user.

Required accountId
string

The unique identifier of the Account that this user belongs to.

referralCode
string

The referral code used for sharing by this user

email
string

The email address provided for the user. SaaSquatch uses this to notify someone when they have a successful referral.

imageUrl
string

Optionally used in widgets, emails, and themes. If you provide a absolute profile image URL the minimum image size is 80px x 80px.

Required firstName
string

The user's first name

lastName
string

The user's last name

locale
string

The user's locale, used for Internationalization. The locale must be of the format 'language_COUNTRY' where the language code must be lowercase and the country code must be uppercase. The separator must be an underscore.

Required tenant_alias
string

Tenant being referenced. E.g. "aboih12h16t" or "test_abo912126tastastt"

Example Curl Request

curl -X POST https://app.referralsaasquatch.com/api/v1/{tenant_alias}/open/account/{accountId}/user/{userId} \
-u :API_KEY \
-H "Content-Type: application/json" \
-d '{
    "id": "219065",
    "accountId": "accc9065",
    "email": "bob@example.com",
    "firstName": "Bob",
    "lastName": "Testerson",
    "locale": "en_US",
    "referralCode": "BOBTESTERSON",
    "imageUrl": "https://www.example.com/profile/ab5111251125"
}'

Returns

id
string

The unique identifier provided for this user.

accountId
string

The unique identifier of the Account that this user belongs to.

referralCode
string

The referral code used for sharing by this user

email
string

The email address provided for the user. SaaSquatch uses this to notify someone when they have a successful referral.

imageUrl
string

Optionally used in widgets, emails, and themes. If you provide a absolute profile image URL the minimum image size is 80px x 80px.

firstName
string

The user's first name

lastName
string

The user's last name

locale
string

The user's locale, used for Internationalization. The locale must be of the format 'language_COUNTRY' where the language code must be lowercase and the country code must be uppercase. The separator must be an underscore.

shareLinks
object
readonly

Share link for an individual user.

shareLink
string

The unique share link the user can refer their friends with. The Share Link contains the Referral Code for making referrals and a source for Analytics purposes.

facebookShareLink
string

The Share Link for Facebook.

twitterShareLink
string

The Share Link for Twitter.

emailShareLink
string

The Share Link for Email.

mobileShareLink
string

The Share Link for mobile devices.

mobileFacebookShareLink
string

The Share Link for Facebook on mobile devices.

mobileTwitterSharelink
string

The Share Link for Twitter on mobile devices.

mobileEmailShareLink
string

The Share Link for Email on mobile devices.

EMBED
object

An individual user's Share links for use in EMBED.

shareLink
string

The unique share link the user can refer their friends with. The Share Link contains the Referral Code for making referrals and a source for Analytics purposes.

facebookShareLink
string

The Share Link for Facebook.

twitterShareLink
string

The Share Link for Twitter.

emailShareLink
string

The Share Link for Email.

linkedinShareLink
string

The Share Link for linkedin.

POPUP
object

An individual user's Share links for use in POPUP.

shareLink
string

The unique share link the user can refer their friends with. The Share Link contains the Referral Code for making referrals and a source for Analytics purposes.

facebookShareLink
string

The Share Link for Facebook.

twitterShareLink
string

The Share Link for Twitter.

emailShareLink
string

The Share Link for Email.

linkedinShareLink
string

The Share Link for linkedin.

HOSTED
object

An individual user's Share links for use in HOSTED.

shareLink
string

The unique share link the user can refer their friends with. The Share Link contains the Referral Code for making referrals and a source for Analytics purposes.

facebookShareLink
string

The Share Link for Facebook.

twitterShareLink
string

The Share Link for Twitter.

emailShareLink
string

The Share Link for Email.

linkedinShareLink
string

The Share Link for linkedin.

MOBILE
object

An individual user's Share links for use in MOBILE.

shareLink
string

The unique share link the user can refer their friends with. The Share Link contains the Referral Code for making referrals and a source for Analytics purposes.

facebookShareLink
string

The Share Link for Facebook.

twitterShareLink
string

The Share Link for Twitter.

emailShareLink
string

The Share Link for Email.

linkedinShareLink
string

The Share Link for linkedin.

EMAIL
object

An individual user's Share links for use in EMAIL.

shareLink
string

The unique share link the user can refer their friends with. The Share Link contains the Referral Code for making referrals and a source for Analytics purposes.

facebookShareLink
string

The Share Link for Facebook.

twitterShareLink
string

The Share Link for Twitter.

emailShareLink
string

The Share Link for Email.

linkedinShareLink
string

The Share Link for linkedin.

Example Response

HTTP 200
{
    "id": "898746321",
    "accountId": "987321",
    "email": "hello@example.com",
    "firstName": "Henk",
    "lastName": "Thompson",
    "locale": null,
    "referralCode": "HENKTHOMPSON",
    "imageUrl": "",
    "shareLinks": {
        "shareLink": "http://ssqt.co/mvbcF5",
        "facebookShareLink": "http://ssqt.co/mmbcF5",
        "twitterShareLink": "http://ssqt.co/mRbcF5",
        "emailShareLink": "http://ssqt.co/mLbcF5",
        "linkedinShareLink": "http://ssqt.co/mLbcF5",
        "mobileShareLink": "http://ssqt.co/mebcF5",
        "mobileFacebookShareLink": "http://ssqt.co/mnbcF5",
        "mobileTwitterShareLink": "http://ssqt.co/mCbcF5",
        "mobileEmailShareLink": "http://ssqt.co/mEbcF5",
        "EMBED": {
            "shareLink": "http://ssqt.co/mQbcF5",
            "facebookShareLink": "http://ssqt.co/mwbcF5",
            "twitterShareLink": "http://ssqt.co/mcbcF5",
            "emailShareLink": "http://ssqt.co/mJbcF5",
            "linkedinShareLink": "http://ssqt.co/mHbcF5"
        },
        "POPUP": {
            "shareLink": "http://ssqt.co/m5bcF5",
            "facebookShareLink": "http://ssqt.co/m9bcF5",
            "twitterShareLink": "http://ssqt.co/mMbcF5",
            "emailShareLink": "http://ssqt.co/mobcF5",
            "linkedinShareLink": "http://ssqt.co/m7bcF5"
        },
        "HOSTED": {
            "shareLink": "http://ssqt.co/mtbcF5",
            "facebookShareLink": "http://ssqt.co/mubcF5",
            "twitterShareLink": "http://ssqt.co/mSbcF5",
            "emailShareLink": "http://ssqt.co/mlbcF5",
            "linkedinShareLink": "http://ssqt.co/mYbcF5"
        },
        "MOBILE": {
            "shareLink": "http://ssqt.co/mebcF5",
            "facebookShareLink": "http://ssqt.co/mnbcF5",
            "twitterShareLink": "http://ssqt.co/mCbcF5",
            "emailShareLink": "http://ssqt.co/mEbcF5",
            "linkedinShareLink": "http://ssqt.co/m3bcF5"
        },
        "EMAIL": {
            "shareLink": "http://ssqt.co/mPbcF5",
            "facebookShareLink": "http://ssqt.co/mTbcF5",
            "twitterShareLink": "http://ssqt.co/mGbcF5",
            "emailShareLink": "http://ssqt.co/mbbcF5",
            "linkedinShareLink": "http://ssqt.co/m1bcF5"
        }
    }
}
statusCode
integer

The HTTP status code of the error

message
string

The human-readable description of what went wrong. Use this to help you debug.

apiErrorCode
string

A machine error code

Example Response

HTTP 403

Lookup a user GET /api/v1/{tenant_alias}/open/account/{accountId}/user/{userId}

Looks up a user based upon their id and returns their personal information including sharelinks. This endpoint requires a read token or an API key.

This is an Open Endpoint and disabled by default. Contact support to enable the open endpoints.

Tags: User Open Endpoint Authentication: APIKey UserJWT

Arguments

Required accountId
string

A valid Account ID that a user is associated with

Required userId
string

A valid User ID

Required tenant_alias
string

Tenant being referenced. E.g. "aboih12h16t" or "test_abo912126tastastt"

Example Curl Request

curl -X GET https://app.referralsaasquatch.com/api/v1/{tenant_alias}/open/account/{accountId}/user/{userId} \
-u :API_KEY \

Returns

Example Response

HTTP 200
{
    "id": "898746321",
    "accountId": "987321",
    "email": "hello@example.com",
    "firstName": "Henk",
    "lastName": "Thompson",
    "locale": null,
    "referralCode": "HENKTHOMPSON",
    "imageUrl": "",
    "shareLinks": {
        "shareLink": "http://ssqt.co/mvbcF5",
        "facebookShareLink": "http://ssqt.co/mmbcF5",
        "twitterShareLink": "http://ssqt.co/mRbcF5",
        "emailShareLink": "http://ssqt.co/mLbcF5",
        "linkedinShareLink": "http://ssqt.co/mLbcF5",
        "mobileShareLink": "http://ssqt.co/mebcF5",
        "mobileFacebookShareLink": "http://ssqt.co/mnbcF5",
        "mobileTwitterShareLink": "http://ssqt.co/mCbcF5",
        "mobileEmailShareLink": "http://ssqt.co/mEbcF5",
        "EMBED": {
            "shareLink": "http://ssqt.co/mQbcF5",
            "facebookShareLink": "http://ssqt.co/mwbcF5",
            "twitterShareLink": "http://ssqt.co/mcbcF5",
            "emailShareLink": "http://ssqt.co/mJbcF5",
            "linkedinShareLink": "http://ssqt.co/mHbcF5"
        },
        "POPUP": {
            "shareLink": "http://ssqt.co/m5bcF5",
            "facebookShareLink": "http://ssqt.co/m9bcF5",
            "twitterShareLink": "http://ssqt.co/mMbcF5",
            "emailShareLink": "http://ssqt.co/mobcF5",
            "linkedinShareLink": "http://ssqt.co/m7bcF5"
        },
        "HOSTED": {
            "shareLink": "http://ssqt.co/mtbcF5",
            "facebookShareLink": "http://ssqt.co/mubcF5",
            "twitterShareLink": "http://ssqt.co/mSbcF5",
            "emailShareLink": "http://ssqt.co/mlbcF5",
            "linkedinShareLink": "http://ssqt.co/mYbcF5"
        },
        "MOBILE": {
            "shareLink": "http://ssqt.co/mebcF5",
            "facebookShareLink": "http://ssqt.co/mnbcF5",
            "twitterShareLink": "http://ssqt.co/mCbcF5",
            "emailShareLink": "http://ssqt.co/mEbcF5",
            "linkedinShareLink": "http://ssqt.co/m3bcF5"
        },
        "EMAIL": {
            "shareLink": "http://ssqt.co/mPbcF5",
            "facebookShareLink": "http://ssqt.co/mTbcF5",
            "twitterShareLink": "http://ssqt.co/mGbcF5",
            "emailShareLink": "http://ssqt.co/mbbcF5",
            "linkedinShareLink": "http://ssqt.co/m1bcF5"
        }
    }
}
statusCode
integer

The HTTP status code of the error

message
string

The human-readable description of what went wrong. Use this to help you debug.

apiErrorCode
string

A machine error code

Example Response

HTTP 401
statusCode
integer

The HTTP status code of the error

message
string

The human-readable description of what went wrong. Use this to help you debug.

apiErrorCode
string

A machine error code

Example Response

HTTP 403
statusCode
integer

The HTTP status code of the error

message
string

The human-readable description of what went wrong. Use this to help you debug.

apiErrorCode
string

A machine error code

Example Response

HTTP 404

Get a user by a referral code GET /api/v1/{tenant_alias}/open/user

Looks up a user based upon their ReferralCode and returns their personal information. This method is useful for retrieving the user when only the Referral Code is available, for example when a referred user enters a Referral Code during checkout and you want to find out who this Referral Code belongs to.

This is an Open Endpoint and disabled by default. Contact support to enable the open endpoints.

Tags: User Open Endpoint Authentication: Unauthenticated

Arguments

Required referralCode
string

The code with which to lookup the User

Required tenant_alias
string

Tenant being referenced. E.g. "aboih12h16t" or "test_abo912126tastastt"

Example Curl Request

curl -X GET https://app.referralsaasquatch.com/api/v1/{tenant_alias}/open/user?referralCode= \
-u :API_KEY \

Returns

Example Response

HTTP 200
{
    "id": "876343",
    "accountId": "613611",
    "email": "bob@example.com",
    "firstName": "Bob",
    "lastName": "Testerson",
    "referralCode": "BOBTESTERSON",
    "imageUrl": ""
}
statusCode
integer

The HTTP status code of the error

message
string

The human-readable description of what went wrong. Use this to help you debug.

apiErrorCode
string

A machine error code

Example Response

HTTP 403
statusCode
integer

The HTTP status code of the error

message
string

The human-readable description of what went wrong. Use this to help you debug.

apiErrorCode
string

A machine error code

Example Response

HTTP 404

Lookup a referral code GET /api/v1/{tenant_alias}/open/code/{referral_code}

Looks up a referral code and the details of the attached reward.

This is an Open Endpoint and disabled by default. Contact support to enable the open endpoints.

Tags: Referral Code Open Endpoint Authentication: Unauthenticated

Arguments

Required referral_code
string

The code to be validated

Required tenant_alias
string

Tenant being referenced. E.g. "aboih12h16t" or "test_abo912126tastastt"

Example Curl Request

curl -X GET https://app.referralsaasquatch.com/api/v1/{tenant_alias}/open/code/{referral_code} \
-u :API_KEY \

Returns

Example Response

HTTP 200
{
    "code": "BOBTESTERSON",
    "dateCreated": 1411600868797,
    "referrerName": "Bob T",
    "reward": {
        "type": "PCT_DISCOUNT",
        "discountPercent": 10,
        "monthsDiscountIsValid": 12
    }
}
statusCode
integer

The HTTP status code of the error

message
string

The human-readable description of what went wrong. Use this to help you debug.

apiErrorCode
string

A machine error code

Example Response

HTTP 403
statusCode
integer

The HTTP status code of the error

message
string

The human-readable description of what went wrong. Use this to help you debug.

apiErrorCode
string

A machine error code

Example Response

HTTP 404

Apply a referral code POST /api/v1/{tenant_alias}/open/code/{referral_code}/account/{account_id}/user/{user_id}

Apply a ReferralCode to a referred account to attribute a referral.

This endpoint requires a write token or an API key.

This is an Open Endpoint and disabled by default. Contact support to enable the open endpoints.

Tags: Referral Code Open Endpoint Authentication: APIKey UserJWT

Arguments

Required referral_code
string

Referral code to apply to user account.

Required account_id
string

Account to apply referral code to. This account will be marked as "referred by" the owner of the referral_code

Required user_id
string

User to apply referral code to. This user will be marked as "referred by" the owner of the referral_code

Required tenant_alias
string

Tenant being referenced. E.g. "aboih12h16t" or "test_abo912126tastastt"

Example Curl Request

curl -X POST https://app.referralsaasquatch.com/api/v1/{tenant_alias}/open/code/{referral_code}/account/{account_id}/user/{user_id} \
-u :API_KEY \
-H "Content-Type: application/json" \
-d ''

Returns

Example Response

HTTP 200
{
    "code": "BOBTESTERSON",
    "dateCreated": 1411600868797,
    "referrerName": "Bob T",
    "reward": {
        "type": "PCT_DISCOUNT",
        "discountPercent": 10,
        "monthsDiscountIsValid": 12
    }
}
statusCode
integer

The HTTP status code of the error

message
string

The human-readable description of what went wrong. Use this to help you debug.

apiErrorCode
string

A machine error code

Example Response

HTTP 400
statusCode
integer

The HTTP status code of the error

message
string

The human-readable description of what went wrong. Use this to help you debug.

apiErrorCode
string

A machine error code

Example Response

HTTP 401
statusCode
integer

The HTTP status code of the error

message
string

The human-readable description of what went wrong. Use this to help you debug.

apiErrorCode
string

A machine error code

Example Response

HTTP 403
statusCode
integer

The HTTP status code of the error

message
string

The human-readable description of what went wrong. Use this to help you debug.

apiErrorCode
string

A machine error code

Example Response

HTTP 404

List referrals GET /api/v1/{tenant_alias}/open/referrals

List all of the referrals involving the given user. This method is the primary way of getting a list of everyone that has made a referral and everyone that has been referred, and supports pagination using the parameters for limit and offset to iterate through a very large list of records. The referringAccountId and referringUserId parameters are required, along with a read token for authenticaion. This proides a list of referrals made by the given user.

This is an Open Endpoint and disabled by default. Contact support to enable the open endpoints.

Tags: Referral Open Endpoint Authentication: APIKey UserJWT

Arguments

Required referringAccountId
string

When included, filters the results to only referrals that were referred users with this AccountId

Required referringUserId
string

When included, filters the results to only referrals that were referred users with this UserId

dateReferralPaid
string

When included, filters the results either to the exact timestamp if only one value is given, or a range if devided by a comma. I.E. 0,123412451 gives all referrals that converted between 0 and 123412451.

dateReferralEnded
string

When included, filters the results either to the exact timestamp if only one value is given, or a range if devided by a comma. I.E. 0,123412451 gives all referrals that ended between 0 and 123412451.

referredModerationStatus
string

When included, filters the result to only include referred users with that status. Statuses that are accepted: PENDING, APPROVED or DENIED.

referrerModerationStatus
string

When included, filters the result to only include referrers with that status. Statuses that are accepted: PENDING, APPROVED or DENIED.

limit
integer

A limit on the number of results returned. Defaults to 10.

offset
integer

When included offsets the first result returns in the list. Use this to paginate through a long list of results. Defaults to 0

Required tenant_alias
string

Tenant being referenced. E.g. "aboih12h16t" or "test_abo912126tastastt"

Example Curl Request

curl -X GET https://app.referralsaasquatch.com/api/v1/{tenant_alias}/open/referrals?referringAccountId=&referringUserId= \
-u :API_KEY \

Returns

referrals
array

A list of Referral objects. This is the actual data in this list envelope.

id
string

Unique identifier for the Referral object

referredUser
object

An object describing an individual user. Users are used in SaaSquatch to track people/contacts/leads. When a referral happens, it always happens between two Users.

id
string

The unique identifier provided for this user.

accountId
string

The unique identifier of the Account that this user belongs to.

referralCode
string

The referral code used for sharing by this user

email
string

The email address provided for the user. SaaSquatch uses this to notify someone when they have a successful referral.

imageUrl
string

Optionally used in widgets, emails, and themes. If you provide a absolute profile image URL the minimum image size is 80px x 80px.

firstName
string

The user's first name

lastName
string

The user's last name

firstSeenIP
string
readonly

The user's IP address on indentification

lastSeenIP
string
readonly

The user's last known IP address

dateCreated
integer
readonly

The Unix time stamp of when the user was created

emailHash
string
readonly

The hash of the user's email address

referralSource
string
readonly

The domain from which the user was registered

locale
string

The user's locale, used for Internationalization. The locale must be of the format 'language_COUNTRY' where the language code must be lowercase and the country code must be uppercase. The separator must be an underscore.

shareLinks
object
readonly

Share link for an individual user.

shareLink
string

The unique share link the user can refer their friends with. The Share Link contains the Referral Code for making referrals and a source for Analytics purposes.

facebookShareLink
string

The Share Link for Facebook.

twitterShareLink
string

The Share Link for Twitter.

emailShareLink
string

The Share Link for Email.

mobileShareLink
string

The Share Link for mobile devices.

mobileFacebookShareLink
string

The Share Link for Facebook on mobile devices.

mobileTwitterSharelink
string

The Share Link for Twitter on mobile devices.

mobileEmailShareLink
string

The Share Link for Email on mobile devices.

EMBED
object

An individual user's Share links for use in EMBED.

shareLink
string

The unique share link the user can refer their friends with. The Share Link contains the Referral Code for making referrals and a source for Analytics purposes.

facebookShareLink
string

The Share Link for Facebook.

twitterShareLink
string

The Share Link for Twitter.

emailShareLink
string

The Share Link for Email.

linkedinShareLink
string

The Share Link for linkedin.

POPUP
object

An individual user's Share links for use in POPUP.

shareLink
string

The unique share link the user can refer their friends with. The Share Link contains the Referral Code for making referrals and a source for Analytics purposes.

facebookShareLink
string

The Share Link for Facebook.

twitterShareLink
string

The Share Link for Twitter.

emailShareLink
string

The Share Link for Email.

linkedinShareLink
string

The Share Link for linkedin.

HOSTED
object

An individual user's Share links for use in HOSTED.

shareLink
string

The unique share link the user can refer their friends with. The Share Link contains the Referral Code for making referrals and a source for Analytics purposes.

facebookShareLink
string

The Share Link for Facebook.

twitterShareLink
string

The Share Link for Twitter.

emailShareLink
string

The Share Link for Email.

linkedinShareLink
string

The Share Link for linkedin.

MOBILE
object

An individual user's Share links for use in MOBILE.

shareLink
string

The unique share link the user can refer their friends with. The Share Link contains the Referral Code for making referrals and a source for Analytics purposes.

facebookShareLink
string

The Share Link for Facebook.

twitterShareLink
string

The Share Link for Twitter.

emailShareLink
string

The Share Link for Email.

linkedinShareLink
string

The Share Link for linkedin.

EMAIL
object

An individual user's Share links for use in EMAIL.

shareLink
string

The unique share link the user can refer their friends with. The Share Link contains the Referral Code for making referrals and a source for Analytics purposes.

facebookShareLink
string

The Share Link for Facebook.

twitterShareLink
string

The Share Link for Twitter.

emailShareLink
string

The Share Link for Email.

linkedinShareLink
string

The Share Link for linkedin.

referrerUser
object

An object describing an individual user. Users are used in SaaSquatch to track people/contacts/leads. When a referral happens, it always happens between two Users.

id
string

The unique identifier provided for this user.

accountId
string

The unique identifier of the Account that this user belongs to.

referralCode
string

The referral code used for sharing by this user

email
string

The email address provided for the user. SaaSquatch uses this to notify someone when they have a successful referral.

imageUrl
string

Optionally used in widgets, emails, and themes. If you provide a absolute profile image URL the minimum image size is 80px x 80px.

firstName
string

The user's first name

lastName
string

The user's last name

firstSeenIP
string
readonly

The user's IP address on indentification

lastSeenIP
string
readonly

The user's last known IP address

dateCreated
integer
readonly

The Unix time stamp of when the user was created

emailHash
string
readonly

The hash of the user's email address

referralSource
string
readonly

The domain from which the user was registered

locale
string

The user's locale, used for Internationalization. The locale must be of the format 'language_COUNTRY' where the language code must be lowercase and the country code must be uppercase. The separator must be an underscore.

shareLinks
object
readonly

Share link for an individual user.

shareLink
string

The unique share link the user can refer their friends with. The Share Link contains the Referral Code for making referrals and a source for Analytics purposes.

facebookShareLink
string

The Share Link for Facebook.

twitterShareLink
string

The Share Link for Twitter.

emailShareLink
string

The Share Link for Email.

mobileShareLink
string

The Share Link for mobile devices.

mobileFacebookShareLink
string

The Share Link for Facebook on mobile devices.

mobileTwitterSharelink
string

The Share Link for Twitter on mobile devices.

mobileEmailShareLink
string

The Share Link for Email on mobile devices.

EMBED
object

An individual user's Share links for use in EMBED.

shareLink
string

The unique share link the user can refer their friends with. The Share Link contains the Referral Code for making referrals and a source for Analytics purposes.

facebookShareLink
string

The Share Link for Facebook.

twitterShareLink
string

The Share Link for Twitter.

emailShareLink
string

The Share Link for Email.

linkedinShareLink
string

The Share Link for linkedin.

POPUP
object

An individual user's Share links for use in POPUP.

shareLink
string

The unique share link the user can refer their friends with. The Share Link contains the Referral Code for making referrals and a source for Analytics purposes.

facebookShareLink
string

The Share Link for Facebook.

twitterShareLink
string

The Share Link for Twitter.

emailShareLink
string

The Share Link for Email.

linkedinShareLink
string

The Share Link for linkedin.

HOSTED
object

An individual user's Share links for use in HOSTED.

shareLink
string

The unique share link the user can refer their friends with. The Share Link contains the Referral Code for making referrals and a source for Analytics purposes.

facebookShareLink
string

The Share Link for Facebook.

twitterShareLink
string

The Share Link for Twitter.

emailShareLink
string

The Share Link for Email.

linkedinShareLink
string

The Share Link for linkedin.

MOBILE
object

An individual user's Share links for use in MOBILE.

shareLink
string

The unique share link the user can refer their friends with. The Share Link contains the Referral Code for making referrals and a source for Analytics purposes.

facebookShareLink
string

The Share Link for Facebook.

twitterShareLink
string

The Share Link for Twitter.

emailShareLink
string

The Share Link for Email.

linkedinShareLink
string

The Share Link for linkedin.

EMAIL
object

An individual user's Share links for use in EMAIL.

shareLink
string

The unique share link the user can refer their friends with. The Share Link contains the Referral Code for making referrals and a source for Analytics purposes.

facebookShareLink
string

The Share Link for Facebook.

twitterShareLink
string

The Share Link for Twitter.

emailShareLink
string

The Share Link for Email.

linkedinShareLink
string

The Share Link for linkedin.

referredReward
object

Rewards are used in SaaSquatch to track the credits, discounts, gift cards and other prizes that a User earns.

id
string

The unique identifier for this reward

type
string

The type of reward.

Possible values: PCT_DISCOUNT, FEATURE, TIME_CREDIT, or CREDIT

dateGiven
integer

Timestamp of when this reward was earned.

dateExpires
integer

Timestamp of when this reward is set to expire.

dateCancelled
integer

Timestamp if the reward is cancellable and has been cancelled, the date it was cancelled on. Null if not never cancelled.

cancellable
boolean

If a reward is cancellable then it may be revoked. If it has been cancelled then dateCancelled will be non-null.

rewardSource
string

The type of the source of the reward.

Possible values: FRIEND_SIGNUP, REFERRED, or MANUAL

unit
string

An identifier for the unit of the reward. E.g. 'credit-in-cents', 'freemb', 'giftcard20', 'tshirt', 'freemonth' or '%'

discountPercent
integer

The percent discount. E.g. 10 means 10% Works with: PCT_DISCOUNT

featureType
string

A unique identifier for the type of feature. E.g. 'freeSeats' or 'freeMb'. Works with: FEATURE

name
string

The name of the feature. e.g. 'Free Seats' or 'Free Storage' Works with: FEATURE

description
string

The feature description. e.g. 'Bonus user seats for your account' or 'Extra megabytes of free storage' Works with: FEATURE

quantity
integer

The earned quantity of the feature Works with:FEATURE

assignedCredit
integer

The earned quantity of the feature. Works with: TIME_CREDIT or CREDIT

redeemedCredit
integer

The redeemed quantity of the feature. Works with: TIME_CREDIT or CREDIT

currency
string

For programs that require a currency. Works with: CREDIT

referrerReward
object

Rewards are used in SaaSquatch to track the credits, discounts, gift cards and other prizes that a User earns.

id
string

The unique identifier for this reward

type
string

The type of reward.

Possible values: PCT_DISCOUNT, FEATURE, TIME_CREDIT, or CREDIT

dateGiven
integer

Timestamp of when this reward was earned.

dateExpires
integer

Timestamp of when this reward is set to expire.

dateCancelled
integer

Timestamp if the reward is cancellable and has been cancelled, the date it was cancelled on. Null if not never cancelled.

cancellable
boolean

If a reward is cancellable then it may be revoked. If it has been cancelled then dateCancelled will be non-null.

rewardSource
string

The type of the source of the reward.

Possible values: FRIEND_SIGNUP, REFERRED, or MANUAL

unit
string

An identifier for the unit of the reward. E.g. 'credit-in-cents', 'freemb', 'giftcard20', 'tshirt', 'freemonth' or '%'

discountPercent
integer

The percent discount. E.g. 10 means 10% Works with: PCT_DISCOUNT

featureType
string

A unique identifier for the type of feature. E.g. 'freeSeats' or 'freeMb'. Works with: FEATURE

name
string

The name of the feature. e.g. 'Free Seats' or 'Free Storage' Works with: FEATURE

description
string

The feature description. e.g. 'Bonus user seats for your account' or 'Extra megabytes of free storage' Works with: FEATURE

quantity
integer

The earned quantity of the feature Works with:FEATURE

assignedCredit
integer

The earned quantity of the feature. Works with: TIME_CREDIT or CREDIT

redeemedCredit
integer

The redeemed quantity of the feature. Works with: TIME_CREDIT or CREDIT

currency
string

For programs that require a currency. Works with: CREDIT

moderationStatus
string

When referrals are manually managed, each referral has a PENDING state until it is explicitly moderated.

Possible values: PENDING, or ACTIONED

referredModerationStatus
string

Used to identify the referred user's moderation status and affect Reward cancellation.

Possible values: PENDING, APPROVED, or DENIED

referrerModerationStatus
string

Used to identify the referrer user's moderation status and affect Reward cancellation.

Possible values: PENDING, APPROVED, or DENIED

fraudSignals
object

Information about signals of potential fraud on the referral

name
object

Information about an individual fraud signal on the referral

message
String

A human readable description of the fraud signal. For example: 'Referrer and referred have very similar names'

score
integer

A numeric score that describes the severity of the fraud signal.

ip
object

Information about an individual fraud signal on the referral

message
String

A human readable description of the fraud signal. For example: 'Referrer and referred have very similar names'

score
integer

A numeric score that describes the severity of the fraud signal.

email
object

Information about an individual fraud signal on the referral

message
String

A human readable description of the fraud signal. For example: 'Referrer and referred have very similar names'

score
integer

A numeric score that describes the severity of the fraud signal.

rate
object

Information about an individual fraud signal on the referral

message
String

A human readable description of the fraud signal. For example: 'Referrer and referred have very similar names'

score
integer

A numeric score that describes the severity of the fraud signal.

dateReferralStarted
integer

Timestamp of when this referral was started.

dateReferralPaid
integer

Timestamp of when this referral was marked as PAID.

dateReferralEnded
integer

Timestamp of when this referral was ended.

dateModerated
integer

Timestamp of when this referral was last moderated.

count
integer

The number of results returned in this list, see totalCount for all rows.

totalCount
integer

The total number of results available overall, see count for the number of rows in this list.

Example Response

HTTP 200
{
    "count": 2,
    "totalCount": 4,
    "referrals": [
        {
            "id": "5462600de4b09b1c41108f28",
            "referredUser": {
                "id": "898746321",
                "accountId": "987321",
                "email": "hello@example.com",
                "firstName": "Henk",
                "lastName": "Thompson",
                "referralCode": "HENKTHOMPSON",
                "imageUrl": "",
                "firstSeenIP": "10.230.163.157",
                "lastSeenIP": "184.66.242.57",
                "dateCreated": 1467222395030,
                "emailHash": "180bc1412a038746af9b37fb782724a2",
                "referralSource": "http://unifiedtestapp.herokuapp.com/",
                "locale": null,
                "shareLinks": {
                    "shareLink": "http://ssqt.co/mvbcF5",
                    "facebookShareLink": "http://ssqt.co/mmbcF5",
                    "twitterShareLink": "http://ssqt.co/mRbcF5",
                    "emailShareLink": "http://ssqt.co/mLbcF5",
                    "linkedinShareLink": "http://ssqt.co/mLbcF5",
                    "mobileShareLink": "http://ssqt.co/mebcF5",
                    "mobileFacebookShareLink": "http://ssqt.co/mnbcF5",
                    "mobileTwitterShareLink": "http://ssqt.co/mCbcF5",
                    "mobileEmailShareLink": "http://ssqt.co/mEbcF5",
                    "EMBED": {
                        "shareLink": "http://ssqt.co/mQbcF5",
                        "facebookShareLink": "http://ssqt.co/mwbcF5",
                        "twitterShareLink": "http://ssqt.co/mcbcF5",
                        "emailShareLink": "http://ssqt.co/mJbcF5",
                        "linkedinShareLink": "http://ssqt.co/mHbcF5"
                    },
                    "POPUP": {
                        "shareLink": "http://ssqt.co/m5bcF5",
                        "facebookShareLink": "http://ssqt.co/m9bcF5",
                        "twitterShareLink": "http://ssqt.co/mMbcF5",
                        "emailShareLink": "http://ssqt.co/mobcF5",
                        "linkedinShareLink": "http://ssqt.co/m7bcF5"
                    },
                    "HOSTED": {
                        "shareLink": "http://ssqt.co/mtbcF5",
                        "facebookShareLink": "http://ssqt.co/mubcF5",
                        "twitterShareLink": "http://ssqt.co/mSbcF5",
                        "emailShareLink": "http://ssqt.co/mlbcF5",
                        "linkedinShareLink": "http://ssqt.co/mYbcF5"
                    },
                    "MOBILE": {
                        "shareLink": "http://ssqt.co/mebcF5",
                        "facebookShareLink": "http://ssqt.co/mnbcF5",
                        "twitterShareLink": "http://ssqt.co/mCbcF5",
                        "emailShareLink": "http://ssqt.co/mEbcF5",
                        "linkedinShareLink": "http://ssqt.co/m3bcF5"
                    },
                    "EMAIL": {
                        "shareLink": "http://ssqt.co/mPbcF5",
                        "facebookShareLink": "http://ssqt.co/mTbcF5",
                        "twitterShareLink": "http://ssqt.co/mGbcF5",
                        "emailShareLink": "http://ssqt.co/mbbcF5",
                        "linkedinShareLink": "http://ssqt.co/m1bcF5"
                    }
                }
            },
            "referrerUser": {
                "id": "898746321",
                "accountId": "987321",
                "email": "hello@example.com",
                "firstName": "Henk",
                "lastName": "Thompson",
                "referralCode": "HENKTHOMPSON",
                "imageUrl": "",
                "firstSeenIP": "10.230.163.157",
                "lastSeenIP": "184.66.242.57",
                "dateCreated": 1467222395030,
                "emailHash": "180bc1412a038746af9b37fb782724a2",
                "referralSource": "http://unifiedtestapp.herokuapp.com/",
                "locale": null,
                "shareLinks": {
                    "shareLink": "http://ssqt.co/mvbcF5",
                    "facebookShareLink": "http://ssqt.co/mmbcF5",
                    "twitterShareLink": "http://ssqt.co/mRbcF5",
                    "emailShareLink": "http://ssqt.co/mLbcF5",
                    "linkedinShareLink": "http://ssqt.co/mLbcF5",
                    "mobileShareLink": "http://ssqt.co/mebcF5",
                    "mobileFacebookShareLink": "http://ssqt.co/mnbcF5",
                    "mobileTwitterShareLink": "http://ssqt.co/mCbcF5",
                    "mobileEmailShareLink": "http://ssqt.co/mEbcF5",
                    "EMBED": {
                        "shareLink": "http://ssqt.co/mQbcF5",
                        "facebookShareLink": "http://ssqt.co/mwbcF5",
                        "twitterShareLink": "http://ssqt.co/mcbcF5",
                        "emailShareLink": "http://ssqt.co/mJbcF5",
                        "linkedinShareLink": "http://ssqt.co/mHbcF5"
                    },
                    "POPUP": {
                        "shareLink": "http://ssqt.co/m5bcF5",
                        "facebookShareLink": "http://ssqt.co/m9bcF5",
                        "twitterShareLink": "http://ssqt.co/mMbcF5",
                        "emailShareLink": "http://ssqt.co/mobcF5",
                        "linkedinShareLink": "http://ssqt.co/m7bcF5"
                    },
                    "HOSTED": {
                        "shareLink": "http://ssqt.co/mtbcF5",
                        "facebookShareLink": "http://ssqt.co/mubcF5",
                        "twitterShareLink": "http://ssqt.co/mSbcF5",
                        "emailShareLink": "http://ssqt.co/mlbcF5",
                        "linkedinShareLink": "http://ssqt.co/mYbcF5"
                    },
                    "MOBILE": {
                        "shareLink": "http://ssqt.co/mebcF5",
                        "facebookShareLink": "http://ssqt.co/mnbcF5",
                        "twitterShareLink": "http://ssqt.co/mCbcF5",
                        "emailShareLink": "http://ssqt.co/mEbcF5",
                        "linkedinShareLink": "http://ssqt.co/m3bcF5"
                    },
                    "EMAIL": {
                        "shareLink": "http://ssqt.co/mPbcF5",
                        "facebookShareLink": "http://ssqt.co/mTbcF5",
                        "twitterShareLink": "http://ssqt.co/mGbcF5",
                        "emailShareLink": "http://ssqt.co/mbbcF5",
                        "linkedinShareLink": "http://ssqt.co/m1bcF5"
                    }
                }
            },
            "referredReward": {
                "id": "5462600de4b09b1c41108f2e",
                "type": "PCT_DISCOUNT",
                "dateGiven": 1415733261275,
                "dateExpires": null,
                "dateCancelled": null,
                "accountId": "613611",
                "userId": "876343",
                "cancellable": true,
                "rewardSource": "REFERRED",
                "discountPercent": 20,
                "unit": "%"
            },
            "referrerReward": null,
            "moderationStatus": "ACTIONED",
            "dateReferralStarted": 1415733261238,
            "dateReferralPaid": null,
            "dateReferralEnded": null,
            "dateModerated": 1427410131006,
            "referredModerationStatus": "APPROVED",
            "referrerModerationStatus": "APPROVED"
        },
        {
            "id": "546270a6e4b0c1871186a920",
            "referredUser": {
                "id": "898746321",
                "accountId": "987321",
                "email": "hello@example.com",
                "firstName": "Henk",
                "lastName": "Thompson",
                "referralCode": "HENKTHOMPSON",
                "imageUrl": "",
                "firstSeenIP": "10.230.163.157",
                "lastSeenIP": "184.66.242.57",
                "dateCreated": 1467222395030,
                "emailHash": "180bc1412a038746af9b37fb782724a2",
                "referralSource": "http://unifiedtestapp.herokuapp.com/",
                "locale": null,
                "shareLinks": {
                    "shareLink": "http://ssqt.co/mvbcF5",
                    "facebookShareLink": "http://ssqt.co/mmbcF5",
                    "twitterShareLink": "http://ssqt.co/mRbcF5",
                    "emailShareLink": "http://ssqt.co/mLbcF5",
                    "linkedinShareLink": "http://ssqt.co/mLbcF5",
                    "mobileShareLink": "http://ssqt.co/mebcF5",
                    "mobileFacebookShareLink": "http://ssqt.co/mnbcF5",
                    "mobileTwitterShareLink": "http://ssqt.co/mCbcF5",
                    "mobileEmailShareLink": "http://ssqt.co/mEbcF5",
                    "EMBED": {
                        "shareLink": "http://ssqt.co/mQbcF5",
                        "facebookShareLink": "http://ssqt.co/mwbcF5",
                        "twitterShareLink": "http://ssqt.co/mcbcF5",
                        "emailShareLink": "http://ssqt.co/mJbcF5",
                        "linkedinShareLink": "http://ssqt.co/mHbcF5"
                    },
                    "POPUP": {
                        "shareLink": "http://ssqt.co/m5bcF5",
                        "facebookShareLink": "http://ssqt.co/m9bcF5",
                        "twitterShareLink": "http://ssqt.co/mMbcF5",
                        "emailShareLink": "http://ssqt.co/mobcF5",
                        "linkedinShareLink": "http://ssqt.co/m7bcF5"
                    },
                    "HOSTED": {
                        "shareLink": "http://ssqt.co/mtbcF5",
                        "facebookShareLink": "http://ssqt.co/mubcF5",
                        "twitterShareLink": "http://ssqt.co/mSbcF5",
                        "emailShareLink": "http://ssqt.co/mlbcF5",
                        "linkedinShareLink": "http://ssqt.co/mYbcF5"
                    },
                    "MOBILE": {
                        "shareLink": "http://ssqt.co/mebcF5",
                        "facebookShareLink": "http://ssqt.co/mnbcF5",
                        "twitterShareLink": "http://ssqt.co/mCbcF5",
                        "emailShareLink": "http://ssqt.co/mEbcF5",
                        "linkedinShareLink": "http://ssqt.co/m3bcF5"
                    },
                    "EMAIL": {
                        "shareLink": "http://ssqt.co/mPbcF5",
                        "facebookShareLink": "http://ssqt.co/mTbcF5",
                        "twitterShareLink": "http://ssqt.co/mGbcF5",
                        "emailShareLink": "http://ssqt.co/mbbcF5",
                        "linkedinShareLink": "http://ssqt.co/m1bcF5"
                    }
                }
            },
            "referrerUser": {
                "id": "898746321",
                "accountId": "987321",
                "email": "hello@example.com",
                "firstName": "Henk",
                "lastName": "Thompson",
                "referralCode": "HENKTHOMPSON",
                "imageUrl": "",
                "firstSeenIP": "10.230.163.157",
                "lastSeenIP": "184.66.242.57",
                "dateCreated": 1467222395030,
                "emailHash": "180bc1412a038746af9b37fb782724a2",
                "referralSource": "http://unifiedtestapp.herokuapp.com/",
                "locale": null,
                "shareLinks": {
                    "shareLink": "http://ssqt.co/mvbcF5",
                    "facebookShareLink": "http://ssqt.co/mmbcF5",
                    "twitterShareLink": "http://ssqt.co/mRbcF5",
                    "emailShareLink": "http://ssqt.co/mLbcF5",
                    "linkedinShareLink": "http://ssqt.co/mLbcF5",
                    "mobileShareLink": "http://ssqt.co/mebcF5",
                    "mobileFacebookShareLink": "http://ssqt.co/mnbcF5",
                    "mobileTwitterShareLink": "http://ssqt.co/mCbcF5",
                    "mobileEmailShareLink": "http://ssqt.co/mEbcF5",
                    "EMBED": {
                        "shareLink": "http://ssqt.co/mQbcF5",
                        "facebookShareLink": "http://ssqt.co/mwbcF5",
                        "twitterShareLink": "http://ssqt.co/mcbcF5",
                        "emailShareLink": "http://ssqt.co/mJbcF5",
                        "linkedinShareLink": "http://ssqt.co/mHbcF5"
                    },
                    "POPUP": {
                        "shareLink": "http://ssqt.co/m5bcF5",
                        "facebookShareLink": "http://ssqt.co/m9bcF5",
                        "twitterShareLink": "http://ssqt.co/mMbcF5",
                        "emailShareLink": "http://ssqt.co/mobcF5",
                        "linkedinShareLink": "http://ssqt.co/m7bcF5"
                    },
                    "HOSTED": {
                        "shareLink": "http://ssqt.co/mtbcF5",
                        "facebookShareLink": "http://ssqt.co/mubcF5",
                        "twitterShareLink": "http://ssqt.co/mSbcF5",
                        "emailShareLink": "http://ssqt.co/mlbcF5",
                        "linkedinShareLink": "http://ssqt.co/mYbcF5"
                    },
                    "MOBILE": {
                        "shareLink": "http://ssqt.co/mebcF5",
                        "facebookShareLink": "http://ssqt.co/mnbcF5",
                        "twitterShareLink": "http://ssqt.co/mCbcF5",
                        "emailShareLink": "http://ssqt.co/mEbcF5",
                        "linkedinShareLink": "http://ssqt.co/m3bcF5"
                    },
                    "EMAIL": {
                        "shareLink": "http://ssqt.co/mPbcF5",
                        "facebookShareLink": "http://ssqt.co/mTbcF5",
                        "twitterShareLink": "http://ssqt.co/mGbcF5",
                        "emailShareLink": "http://ssqt.co/mbbcF5",
                        "linkedinShareLink": "http://ssqt.co/m1bcF5"
                    }
                }
            },
            "referredReward": {
                "id": "5462600de4b09b1c41108f2e",
                "type": "PCT_DISCOUNT",
                "dateGiven": 1415733261275,
                "dateExpires": null,
                "dateCancelled": null,
                "accountId": "613611",
                "userId": "876343",
                "cancellable": true,
                "rewardSource": "REFERRED",
                "discountPercent": 20,
                "unit": "%"
            },
            "referrerReward": {
                "id": "5462600de4b09b1c41108f2e",
                "type": "PCT_DISCOUNT",
                "dateGiven": 1415733261275,
                "dateExpires": null,
                "dateCancelled": null,
                "accountId": "613611",
                "userId": "876343",
                "cancellable": true,
                "rewardSource": "REFERRED",
                "discountPercent": 20,
                "unit": "%"
            },
            "moderationStatus": "ACTIONED",
            "dateReferralStarted": 1415737510411,
            "dateReferralPaid": 1415737557217,
            "dateReferralEnded": null,
            "dateModerated": 1427410131029,
            "referredModerationStatus": "APPROVED",
            "referrerModerationStatus": "APPROVED",
            "fraudSignals": {
                "ip": {
                    "message": "Referrer and referred came from the same IP",
                    "score": 50
                }
            }
        }
    ]
}

Create a webhook subscription POST /api/v1/{tenant_alias}/subscription

Subscribes a URL to receive events via webhooks

Tags: Webhook Authentication: APIKey

Arguments

Required endpoint
JSON Body

Details of the endpoint to be created

endpointUrl
string

The url of the endpoint that receives events

name
string

Optional name of the endpoint that receives events

Required tenant_alias
string

Tenant being referenced. E.g. "aboih12h16t" or "test_abo912126tastastt"

Example Curl Request

curl -X POST https://app.referralsaasquatch.com/api/v1/{tenant_alias}/subscription \
-u :API_KEY \
-H "Content-Type: application/json" \
-d '{
    "endpointUrl": "http://app.example.com/endpoint/sqtch",
    "name": "Zapier"
}'

Returns

Example Response

HTTP 201

List webhook subscriptions GET /api/v1/{tenant_alias}/subscription

Lists all the URLs that are currently subscribed to receive events via webhooks

Tags: Webhook Authentication: APIKey

Arguments

Required tenant_alias
string

Tenant being referenced. E.g. "aboih12h16t" or "test_abo912126tastastt"

Example Curl Request

curl -X GET https://app.referralsaasquatch.com/api/v1/{tenant_alias}/subscription \
-u :API_KEY \

Returns

endpointUrl
string

The url of the endpoint that receives events

name
string

Optional name of the endpoint that receives events

Example Response

HTTP 200
[
    {
        "endpointUrl": "https://example.com/hook",
        "name": "Zapier"
    },
    {
        "endpointUrl": "https://another.example.com/hook",
        "name": "Example"
    }
]

Delete a webhook subscription DELETE /api/v1/{tenant_alias}/subscription/{url}

Removes a URL from receiving events via webhooks

Tags: Webhook Authentication: APIKey

Arguments

Required url
string

The url of the endpoint that will be removed. Remember to URL-encode this field

Required tenant_alias
string

Tenant being referenced. E.g. "aboih12h16t" or "test_abo912126tastastt"

Example Curl Request

curl -X DELETE https://app.referralsaasquatch.com/api/v1/{tenant_alias}/subscription/{url} \
-u :API_KEY \

Returns

Example Response

HTTP 204

Test a webhook subscription POST /api/v1/{tenant_alias}/subscription/{url}/test

Sends a test event to the specified webhook

Tags: Webhook Authentication: APIKey UserJWT

Arguments

Required url
string

The url of the endpoint to send a test message to. Remember to URL-encode this field

Required tenant_alias
string

Tenant being referenced. E.g. "aboih12h16t" or "test_abo912126tastastt"

Example Curl Request

curl -X POST https://app.referralsaasquatch.com/api/v1/{tenant_alias}/subscription/{url}/test \
-u :API_KEY \
-H "Content-Type: application/json" \
-d ''

Returns

Example Response

HTTP 204

Create a CSV Export POST /api/v1/{tenant_alias}/export

Creates an asynchronous request for an Exports. Depending on the size of the Export and other exports in the export pipeline, it may take awhile for an export request to complete. Once the Export is completed, it can be downloaded as a CSV file using the download url endpoint.

Here are a few ways to check for when an export is ready.

  • Polling - While an export is being prepared you can check the status using the id. Make sure you store the id of the export when you request it.
  • Webhooks - When an export is complete, a webhook event will be fired. Make sure you create a webhook endpoint subscription before you create your export.
  • Listing - You can use the API to list recent exports, and check their status.

Tags: Export Authentication: APIKey

Arguments

Required export
JSON Body

Details of the export to be created

Required type
string

The type of Export that's being requested.

Possible values: REFERRAL, REWARD_BALANCE, or USER

format
string

The format of the Export

Possible values: or CSV

name
string

A user-friendly name for this report. Useful for keeping track of which report is which.

requester
string

Detail on the service or user that requested this report.

params
object

Filter parameters for limiting the types of results returned. When parameters are included, their are grouped by a logical "AND" so it's possible to create situations that return no results.

createdSince
integer

Filters for results that have been created since this date

createdBefore
integer

Filters for results that have been created before this date

updatedSince
integer

Filters for results that have been updated since this date

updatedBefore
integer

Filters for results that have been updated before this date

createdOrUpdatedSince
integer

Filters for results that have been created or updated since this date. Useful for doing incremental exports into a data warehouse.

createdOrUpdatedBefore
integer

Filters for results that have been created or updated before this date. Useful for doing incremental exports into a data warehouse.

Required tenant_alias
string

Tenant being referenced. E.g. "aboih12h16t" or "test_abo912126tastastt"

Example Curl Request

curl -X POST https://app.referralsaasquatch.com/api/v1/{tenant_alias}/export \
-u :API_KEY \
-H "Content-Type: application/json" \
-d '{
    "type": "REFERRAL",
    "format": "CSV",
    "requester": "Referral SaaSquatch for Salesforce",
    "params": {
        "createdOrUpdatedSince": 1471486152087,
        "createdOrUpdatedBefore": 1471486452087
    },
    "id": "57b519f4e4b057c1b63925df",
    "status": "PENDING",
    "dateCreated": 1471486452362,
    "dateCompleted": 1474510479612,
    "dateExpires": 1471486479612
}'

Returns

type
string

The type of Export that's being requested.

Possible values: REFERRAL, REWARD_BALANCE, or USER

format
string

The format of the Export

Possible values: or CSV

name
string

A user-friendly name for this report. Useful for keeping track of which report is which.

requester
string

Detail on the service or user that requested this report.

params
object

Filter parameters for limiting the types of results returned. When parameters are included, their are grouped by a logical "AND" so it's possible to create situations that return no results.

createdSince
integer

Filters for results that have been created since this date

createdBefore
integer

Filters for results that have been created before this date

updatedSince
integer

Filters for results that have been updated since this date

updatedBefore
integer

Filters for results that have been updated before this date

createdOrUpdatedSince
integer

Filters for results that have been created or updated since this date. Useful for doing incremental exports into a data warehouse.

createdOrUpdatedBefore
integer

Filters for results that have been created or updated before this date. Useful for doing incremental exports into a data warehouse.

id
string
readonly

A unique ID used to keep track of an export's life. Can be used to lookup an exports status.

status
string
readonly

The status of this export.

Possible values: PENDING, COMPLETED, or EXPIRED

dateCreated
integer
readonly

The timestamp when this request was created. This field will never change.

dateCompleted
integer
readonly

The timestamp when this report finished processing and had it's status set to COMPLETED.

dateExpires
integer
readonly

The timestamp when this report will expire. By default all reports will eventually expire.

Example Response

HTTP 201

Lookup a CSV Export GET /api/v1/{tenant_alias}/export/{exportId}

Looks up an Export to check its status. Useful when you're generating exports to check when an export is complete. When the status is no longer PENDING so that you can begin to download the export.

Tags: Export Authentication: APIKey

Arguments

Required exportId
string

The id of the export to look up

Required tenant_alias
string

Tenant being referenced. E.g. "aboih12h16t" or "test_abo912126tastastt"

Example Curl Request

curl -X GET https://app.referralsaasquatch.com/api/v1/{tenant_alias}/export/{exportId} \
-u :API_KEY \

Returns

type
string

The type of Export that's being requested.

Possible values: REFERRAL, REWARD_BALANCE, or USER

format
string

The format of the Export

Possible values: or CSV

name
string

A user-friendly name for this report. Useful for keeping track of which report is which.

requester
string

Detail on the service or user that requested this report.

params
object

Filter parameters for limiting the types of results returned. When parameters are included, their are grouped by a logical "AND" so it's possible to create situations that return no results.

createdSince
integer

Filters for results that have been created since this date

createdBefore
integer

Filters for results that have been created before this date

updatedSince
integer

Filters for results that have been updated since this date

updatedBefore
integer

Filters for results that have been updated before this date

createdOrUpdatedSince
integer

Filters for results that have been created or updated since this date. Useful for doing incremental exports into a data warehouse.

createdOrUpdatedBefore
integer

Filters for results that have been created or updated before this date. Useful for doing incremental exports into a data warehouse.

id
string
readonly

A unique ID used to keep track of an export's life. Can be used to lookup an exports status.

status
string
readonly

The status of this export.

Possible values: PENDING, COMPLETED, or EXPIRED

dateCreated
integer
readonly

The timestamp when this request was created. This field will never change.

dateCompleted
integer
readonly

The timestamp when this report finished processing and had it's status set to COMPLETED.

dateExpires
integer
readonly

The timestamp when this report will expire. By default all reports will eventually expire.

Example Response

HTTP 200

Example Response

HTTP 404

Download a CSV Export GET /api/v1/{tenant_alias}/export/{exportId}/download

The endpoint to download a completed export. This method can only be used when an export is COMPLETED. Exports are not always immediately available to download after they have been created, often exports are large files that take time to process and prepare. If you want to check if an export is ready to be downloaded, use the API method to lookup an export or to list exports.

Tags: Export Authentication: APIKey

Arguments

Required exportId
string

The id of the export to look up

Required tenant_alias
string

Tenant being referenced. E.g. "aboih12h16t" or "test_abo912126tastastt"

Example Curl Request

curl -X GET https://app.referralsaasquatch.com/api/v1/{tenant_alias}/export/{exportId}/download \
-u :API_KEY \

Returns

Example Response

HTTP 200

List CSV Exports GET /api/v1/{tenant_alias}/export/history/list

List all of the exports in a tenant. Useful for tracking down exports

Tags: Export Authentication: APIKey

Arguments

limit
integer

A limit on the maximum number of results to return, defaults to 10.

offset
integer

The row number of the first result to return, defaults to 0.

Required tenant_alias
string

Tenant being referenced. E.g. "aboih12h16t" or "test_abo912126tastastt"

Example Curl Request

curl -X GET https://app.referralsaasquatch.com/api/v1/{tenant_alias}/export/history/list \
-u :API_KEY \

Returns

data
array

A list of Export objects. This is the actual data in this list envelope.

type
string

The type of Export that's being requested.

Possible values: REFERRAL, REWARD_BALANCE, or USER

format
string

The format of the Export

Possible values: or CSV

name
string

A user-friendly name for this report. Useful for keeping track of which report is which.

requester
string

Detail on the service or user that requested this report.

params
object

Filter parameters for limiting the types of results returned. When parameters are included, their are grouped by a logical "AND" so it's possible to create situations that return no results.

createdSince
integer

Filters for results that have been created since this date

createdBefore
integer

Filters for results that have been created before this date

updatedSince
integer

Filters for results that have been updated since this date

updatedBefore
integer

Filters for results that have been updated before this date

createdOrUpdatedSince
integer

Filters for results that have been created or updated since this date. Useful for doing incremental exports into a data warehouse.

createdOrUpdatedBefore
integer

Filters for results that have been created or updated before this date. Useful for doing incremental exports into a data warehouse.

id
string
readonly

A unique ID used to keep track of an export's life. Can be used to lookup an exports status.

status
string
readonly

The status of this export.

Possible values: PENDING, COMPLETED, or EXPIRED

dateCreated
integer
readonly

The timestamp when this request was created. This field will never change.

dateCompleted
integer
readonly

The timestamp when this report finished processing and had it's status set to COMPLETED.

dateExpires
integer
readonly

The timestamp when this report will expire. By default all reports will eventually expire.

count
integer

The number of results returned in this list, see totalCount for all rows.

totalCount
integer

The total number of results available overall, see count for the number of rows in this list.

Example Response

HTTP 200

Lookup variables schema GET /api/v1/{tenant_alias}/theme/variables/schema

Returns the variables schema object that is defined in the tenant theme repository. This will be a JSON Schema standards compliant definition.

For the list of current variable values, see the theme variables for more info.

Tags: Theme Authentication: APIKey

Arguments

Required tenant_alias
string

Tenant being referenced. E.g. "aboih12h16t" or "test_abo912126tastastt"

Example Curl Request

curl -X GET https://app.referralsaasquatch.com/api/v1/{tenant_alias}/theme/variables/schema \
-u :API_KEY \

Returns

Example Response

HTTP 200
{
    "title": "Example Theme Variables Schema",
    "type": "object",
    "properties": {
        "jsOptions": {
            "type": "object",
            "properties": {
                "widget": {
                    "type": "object",
                    "properties": {
                        "defaultWidgetType": {
                            "type": "string",
                            "title": "Default Widget Type",
                            "default": "REFERRER_WIDGET",
                            "enum": [
                                "REFERRER_WIDGET",
                                "CONVERSION_WIDGET"
                            ],
                            "options": {
                                "enum_titles": [
                                    "Referrer's Widget",
                                    "Referred User Widget"
                                ]
                            }
                        }
                    }
                },
                "conversionUrls": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                },
                "widgetUrlMappings": {
                    "type": "array",
                    "items": {
                        "type": "object",
                        "properties": {
                            "url": {
                                "type": "string"
                            },
                            "showAsCTA": {
                                "type": "boolean"
                            },
                            "displayOnLoad": {
                                "type": "boolean"
                            },
                            "widgetType": {
                                "type": "string",
                                "enum": [
                                    "REFERRER_WIDGET",
                                    "CONVERSION_WIDGET"
                                ],
                                "options": {
                                    "enum_titles": [
                                        "Referrer's Widget",
                                        "Referred User Widget"
                                    ]
                                }
                            }
                        }
                    }
                }
            }
        },
        "widget": {
            "type": "object",
            "properties": {
                "REFERRER_WIDGET": {
                    "type": "object",
                    "properties": {
                        "configuration": {
                            "properties": {
                                "themeMapping": {
                                    "default": "widget"
                                }
                            }
                        },
                        "content": {
                            "properties": {
                                "widgetCustomization": {
                                    "title": "Customize Referral Widget",
                                    "properties": {
                                        "widgetFont": {
                                            "default": "\"Helvetica Neue\",Helvetica,Arial,sans-serif"
                                        },
                                        "headerColor": {
                                            "default": "#4486E1"
                                        },
                                        "heading": {
                                            "default": "Give ${{math programDetails.referredRewardDetails.credit ' / 100'}} and Get ${{math programDetails.referrerRewardDetails.credit ' / 100'}}!"
                                        },
                                        "headerDetails": {
                                            "default": "Give a friend ${{math programDetails.referredRewardDetails.credit ' / 100'}} credit off {{companyName}} and receive ${{math programDetails.referrerRewardDetails.credit ' / 100'}} for yourself when they pay their first bill."
                                        },
                                        "shareCodeDetails": {
                                            "type": "string",
                                            "format": "markdown",
                                            "title": "Call To Action Text",
                                            "default": "Share the link below or use the code **{{user.referralCode}}**",
                                            "options": {
                                                "input_height": "100px",
                                                "validate": [
                                                    "handlebars"
                                                ]
                                            }
                                        },
                                        "registrationHeader": {
                                            "type": "string",
                                            "format": "markdown",
                                            "title": "Registration Header",
                                            "default": "Thanks for sending your first referral!<br>Give us your email to ensure you get rewarded when your referral is used.",
                                            "options": {
                                                "input_height": "100px",
                                                "validate": [
                                                    "handlebars"
                                                ]
                                            }
                                        }
                                    },
                                    "$ ref": "#/definitions/widget/definitions/content/definitions/generalBody"
                                },
                                "shareMessaging": {
                                    "$ ref": "#/definitions/widget/definitions/content/definitions/shareContent",
                                    "required": [
                                        "emailShareBody",
                                        "emailShareSubject",
                                        "facebookShareSubject",
                                        "facebookShareBody",
                                        "twitterShareBody",
                                        "smsShareBody"
                                    ]
                                }
                            }
                        },
                        "cta": {
                            "type": "object",
                            "properties": {
                                "configuration": {
                                    "$ ref": "#/definitions/widget/definitions/cta/definitions/configuration"
                                },
                                "content": {
                                    "properties": {
                                        "buttonText": {
                                            "default": "Refer Friends For Rewards"
                                        }
                                    },
                                    "$ ref": "#/definitions/widget/definitions/cta/definitions/content"
                                }
                            }
                        }
                    }
                },
                "CONVERSION_WIDGET": {
                    "type": "object",
                    "properties": {
                        "configuration": {
                            "properties": {
                                "themeMapping": {
                                    "default": "conversion-widget"
                                }
                            }
                        },
                        "content": {
                            "properties": {
                                "widgetCustomization": {
                                    "title": "Customize Referred Widget",
                                    "properties": {
                                        "widgetHeaderImage": {
                                            "type": "string",
                                            "format": "text",
                                            "minLength": 1,
                                            "title": "Heading Image Url:",
                                            "default": "{{assets 'images/conversion.png'}}"
                                        },
                                        "widgetFont": {
                                            "default": "\"Helvetica Neue\",Helvetica,Arial,sans-serif"
                                        },
                                        "headerColor": {
                                            "default": "#444"
                                        },
                                        "heading": {
                                            "default": "You were Successfully Referred to {{companyName}}"
                                        },
                                        "headerDetails": {
                                            "default": "Use the Referral Code<br><span id=\"squatch-share-code\">{{referredBy.referredByUser.referralCode}}</span><br>at checkout to receive your referral discount"
                                        },
                                        "buttonCopy": {
                                            "type": "string",
                                            "format": "text",
                                            "minLength": 1,
                                            "title": "Button Copy",
                                            "default": "COPY CODE"
                                        }
                                    },
                                    "$ ref": "#/definitions/widget/definitions/content/definitions/generalBody"
                                }
                            }
                        },
                        "cta": {
                            "type": "object",
                            "properties": {
                                "configuration": {
                                    "$ ref": "#/definitions/widget/definitions/cta/definitions/configuration"
                                },
                                "content": {
                                    "properties": {
                                        "buttonText": {
                                            "default": "Get Rewarded"
                                        }
                                    },
                                    "$ ref": "#/definitions/widget/definitions/cta/definitions/content"
                                }
                            }
                        }
                    }
                }
            }
        },
        "email": {
            "type": "object",
            "properties": {
                "REFERRER_REWARD_LIMIT_REACHED": {
                    "type": "object",
                    "properties": {
                        "configuration": {
                            "properties": {
                                "subject": {
                                    "default": "You have hit the reward limit!"
                                },
                                "themeMapping": {
                                    "default": "emails/referrer-reward-limit"
                                }
                            },
                            "$ ref": "#/definitions/email/definitions/configuration"
                        },
                        "content": {
                            "properties": {
                                "headerImageUrl": {
                                    "default": "{{assets 'images/email/reward-limit-header.png'}}"
                                },
                                "headerContent": {
                                    "default": "#Reward Limit\nYou have successfully referred the maximum!"
                                },
                                "bodyContent": {
                                    "default": "Thanks for spreading the word about {{companyName}}. You've referred so many new people that you've earned the maximum amount of available credit."
                                },
                                "shareCTA": {
                                    "default": "However, you can keep referring new users and giving ${{programDetails.referrerRewardDetails.credit}} off with your code. - **{{user.referralCode}}**"
                                }
                            },
                            "$ ref": "#/definitions/email/definitions/shareContent"
                        }
                    }
                },
                "REFERRAL_CONVERTED": {
                    "type": "object",
                    "properties": {
                        "configuration": {
                            "properties": {
                                "subject": {
                                    "default": "Congrats! You have earned ${{math programDetails.referrerRewardDetails.credit ' / 100'}} of free credit with {{companyName}}"
                                },
                                "themeMapping": {
                                    "default": "emails/referral-converted"
                                }
                            },
                            "$ ref": "#/definitions/email/definitions/configuration"
                        },
                        "content": {
                            "properties": {
                                "headerImageUrl": {
                                    "default": "{{assets 'images/email/referral-converted-header.png'}}"
                                },
                                "headerContent": {
                                    "default": "#Congratulations\nYour friend has signed up for a {{companyName}} Account!"
                                },
                                "bodyContent": {
                                    "default": "You have now earned ${{math programDetails.referrerRewardDetails.credit ' / 100'}} of free credit with {{companyName}}. Refer more friends to save even more!"
                                }
                            },
                            "$ ref": "#/definitions/email/definitions/shareContent"
                        }
                    }
                },
                "REFERRAL_STARTED": {
                    "type": "object",
                    "properties": {
                        "configuration": {
                            "properties": {
                                "subject": {
                                    "default": "​{{stringEmptyHandler newReferral.referredUser.firstName onEmpty='A friend'}}​ helped you get one step closer to free credit with {{companyName}}​!"
                                },
                                "themeMapping": {
                                    "default": "emails/referral-started"
                                }
                            },
                            "$ ref": "#/definitions/email/definitions/configuration"
                        },
                        "content": {
                            "properties": {
                                "headerImageUrl": {
                                    "default": "{{assets 'images/email/referral-started-header.png'}}"
                                },
                                "headerContent": {
                                    "default": "#Good News!\nYour friend has signed up for a free account with {{companyName}}!"
                                },
                                "bodyContent": {
                                    "default": "{{stringEmptyHandler newReferral.referredUser.firstName onEmpty='A friend'}}​ is currently trying out {{companyName}}. As a thank you from us, if they become a paying user, you will automatically receive ${{math programDetails.referrerRewardDetails.credit ' / 100'}} of free credit with {{companyName}}"
                                }
                            },
                            "$ ref": "#/definitions/email/definitions/shareContent"
                        }
                    }
                }
            }
        }
    },
    "definitions": {
        "widget": {
            "definitions": {
                "content": {
                    "definitions": {
                        "generalBody": {
                            "type": "object",
                            "properties": {
                                "widgetFont": {
                                    "type": "string",
                                    "title": "Widget Font:",
                                    "enum": [
                                        "\"Helvetica Neue\",Helvetica,Arial,sans-serif",
                                        "'Lato',sans-serif",
                                        "'Times New Roman'",
                                        "Arial",
                                        "Courier",
                                        "Tahoma",
                                        "Verdana",
                                        "Georgia"
                                    ],
                                    "options": {
                                        "enum_titles": [
                                            "Helvetica Neue",
                                            "Lato",
                                            "Times New Roman",
                                            "Arial",
                                            "Courier",
                                            "Tahoma",
                                            "Verdana",
                                            "Georgia"
                                        ]
                                    }
                                },
                                "headerColor": {
                                    "type": "string",
                                    "format": "text",
                                    "minLength": 1,
                                    "title": "Heading Text Color (hex code):",
                                    "options": {
                                        "validate": [
                                            "hex-color"
                                        ]
                                    }
                                },
                                "heading": {
                                    "type": "string",
                                    "minLength": 1,
                                    "format": "markdown",
                                    "title": "Heading Text:",
                                    "options": {
                                        "input_height": "100px",
                                        "validate": [
                                            "handlebars"
                                        ]
                                    }
                                },
                                "headerDetails": {
                                    "type": "string",
                                    "minLength": 1,
                                    "format": "markdown",
                                    "title": "Body Text:",
                                    "options": {
                                        "input_height": "100px",
                                        "validate": [
                                            "handlebars"
                                        ]
                                    }
                                }
                            }
                        },
                        "shareContent": {
                            "title": "Share Messaging",
                            "type": "object",
                            "properties": {
                                "emailShareSubject": {
                                    "type": "string",
                                    "description": "Email share subject",
                                    "minLength": 4,
                                    "default": "Get ${{math programDetails.referredRewardDetails.credit ' / 100'}} off {{companyName}}"
                                },
                                "emailShareBody": {
                                    "type": "string",
                                    "description": "Email share body",
                                    "minLength": 4,
                                    "default": "Sign up for a {{companyName}} account and we both get ${{math programDetails.referredRewardDetails.credit ' / 100'}} free credit. Use this link {{shareLinks.emailShareLink}}"
                                },
                                "facebookShareImageURL": {
                                    "type": "string",
                                    "description": "Facebook URL Image",
                                    "default": ""
                                },
                                "facebookShareSubject": {
                                    "type": "string",
                                    "description": "Facebook share subject",
                                    "minLength": 4,
                                    "default": "Get ${{math programDetails.referredRewardDetails.credit ' / 100'}} off {{companyName}}"
                                },
                                "facebookShareBody": {
                                    "type": "string",
                                    "description": "Facebook share subject",
                                    "minLength": 4,
                                    "default": "Sign up for a {{companyName}} account and we both get ${{math programDetails.referredRewardDetails.credit ' / 100'}} free credit. Use this link {{shareLinks.facebookShareLink}}"
                                },
                                "twitterShareBody": {
                                    "type": "string",
                                    "description": "Twitter share body",
                                    "minLength": 4,
                                    "default": "Sign up for a {{companyName}} account and we both get ${{math programDetails.referredRewardDetails.credit ' / 100'}} free credit. Use this link {{shareLinks.twitterShareLink}}"
                                },
                                "smsShareBody": {
                                    "type": "string",
                                    "description": "SMS share body",
                                    "minLength": 4,
                                    "default": "Sign up for a {{companyName}} account and we both get ${{math programDetails.referredRewardDetails.credit ' / 100'}} free credit. Use this link {{share-link 'SMS'}}"
                                }
                            }
                        }
                    }
                },
                "cta": {
                    "definitions": {
                        "configuration": {
                            "type": "object",
                            "properties": {
                                "themeMapping": {
                                    "default": "cta-widget"
                                }
                            }
                        },
                        "content": {
                            "type": "object",
                            "title": "Customize CTA Button",
                            "properties": {
                                "buttonSide": {
                                    "type": "string",
                                    "title": "Button Side:",
                                    "default": "right",
                                    "enum": [
                                        "left",
                                        "right",
                                        "center"
                                    ],
                                    "options": {
                                        "enum_titles": [
                                            "Left Side",
                                            "Right Side",
                                            "Center"
                                        ]
                                    }
                                },
                                "buttonPosition": {
                                    "type": "string",
                                    "title": "Button Position:",
                                    "default": "bottom",
                                    "enum": [
                                        "top",
                                        "bottom",
                                        "middle"
                                    ],
                                    "options": {
                                        "enum_titles": [
                                            "Top",
                                            "Bottom",
                                            "Middle"
                                        ]
                                    }
                                },
                                "buttonColor": {
                                    "type": "string",
                                    "format": "text",
                                    "minLength": 1,
                                    "title": "Button Color (hex code):",
                                    "default": "#4486E1",
                                    "options": {
                                        "validate": [
                                            "hex-color"
                                        ]
                                    }
                                },
                                "buttonText": {
                                    "type": "string",
                                    "title": "Button Text",
                                    "format": "markdown",
                                    "propertyOrder": 4,
                                    "options": {
                                        "validate": [
                                            "handlebars"
                                        ],
                                        "input_height": "50px"
                                    }
                                },
                                "buttonWidth": {
                                    "type": "integer",
                                    "title": "Button Width",
                                    "format": "number",
                                    "default": 230
                                }
                            }
                        }
                    }
                }
            }
        },
        "email": {
            "definitions": {
                "configuration": {
                    "type": "object",
                    "title": "Email Defaults",
                    "properties": {
                        "fromName": {
                            "type": "string",
                            "title": "From Name",
                            "default": "{{companyName}}",
                            "propertyOrder": 1,
                            "minLength": 1,
                            "options": {
                                "validate": [
                                    "handlebars"
                                ]
                            }
                        },
                        "fromAddress": {
                            "type": "string",
                            "title": "From Address",
                            "format": "email",
                            "default": "referral@mail.saasquat.ch",
                            "propertyOrder": 2,
                            "minLength": 5,
                            "options": {
                                "validate": [
                                    "email"
                                ]
                            }
                        },
                        "subject": {
                            "type": "string",
                            "title": "Subject",
                            "format": "textarea",
                            "default": "Referral Update",
                            "propertyOrder": 3,
                            "minLength": 1,
                            "options": {
                                "validate": [
                                    "handlebars"
                                ],
                                "input_height": "50px"
                            }
                        },
                        "themeMapping": {
                            "options": {
                                "hidden": true
                            }
                        }
                    }
                },
                "generalContent": {
                    "type": "object",
                    "properties": {
                        "headerImageUrl": {
                            "type": "string",
                            "title": "Header Image URL",
                            "propertyOrder": 1,
                            "options": {
                                "validate": [
                                    "handlebars"
                                ]
                            }
                        },
                        "headerContent": {
                            "type": "string",
                            "title": "Header Content",
                            "format": "markdown",
                            "propertyOrder": 2,
                            "options": {
                                "validate": [
                                    "handlebars"
                                ],
                                "input_height": "50px"
                            }
                        },
                        "bodyContent": {
                            "type": "string",
                            "title": "Body Content",
                            "format": "markdown",
                            "propertyOrder": 3,
                            "options": {
                                "validate": [
                                    "handlebars"
                                ],
                                "input_height": "50px"
                            }
                        },
                        "footer": {
                            "type": "string",
                            "title": "Footer",
                            "format": "markdown",
                            "propertyOrder": 1001,
                            "options": {
                                "validate": [
                                    "handlebars"
                                ],
                                "input_height": "50px"
                            }
                        }
                    }
                },
                "shareContent": {
                    "type": "object",
                    "properties": {
                        "shareCTA": {
                            "type": "string",
                            "title": "Share Code CTA",
                            "format": "markdown",
                            "propertyOrder": 4,
                            "default": "Keep sharing your code and earn more discounts - **{{user.referralCode}}**",
                            "options": {
                                "validate": [
                                    "handlebars"
                                ],
                                "input_height": "50px"
                            }
                        },
                        "hasShareLink": {
                            "type": "boolean",
                            "format": "checkbox",
                            "title": "Enable Share Link",
                            "propertyOrder": 5,
                            "default": true
                        },
                        "shareButtonHeader": {
                            "type": "string",
                            "title": "Share Button Header",
                            "format": "markdown",
                            "propertyOrder": 6,
                            "default": "Refer and Earn ${{math programDetails.referrerRewardDetails.credit ' / 100'}} of Credit",
                            "options": {
                                "validate": [
                                    "handlebars"
                                ],
                                "input_height": "50px"
                            }
                        }
                    }
                }
            }
        }
    },
    "required": [
        "jsOptions",
        "widget",
        "email"
    ]
}

Lookup variables values GET /api/v1/{tenant_alias}/theme/variables/instance

Returns the current variables values stored for the schema object that is defined in the tenant theme repository.

Tags: Theme Authentication: APIKey

Arguments

Required tenant_alias
string

Tenant being referenced. E.g. "aboih12h16t" or "test_abo912126tastastt"

Example Curl Request

curl -X GET https://app.referralsaasquatch.com/api/v1/{tenant_alias}/theme/variables/instance \
-u :API_KEY \

Returns

Example Response

HTTP 200
{
    "jsOptions": {
        "widget": {
            "defaultWidgetType": "REFERRER_WIDGET"
        },
        "conversionUrls": [
            "^https:\\/\\/example\\.com\\/thank\\-you([^a-zA-Z0-9.\\-_~!$&'()*+,;=:@/]+?.*$|$)"
        ],
        "widgetUrlMappings": [
            {
                "widgetType": "CONVERSION_WIDGET",
                "showAsCTA": true,
                "displayOnLoad": true,
                "url": "^https:\\/\\/example\\.com\\/widgetPage\\/([^a-zA-Z0-9.\\-_~!$&'()*+,;=:@/]+?.*$|$)"
            }
        ]
    },
    "widget": {
        "REFERRER_WIDGET": {
            "configuration": {
                "themeMapping": "widget"
            },
            "content": {
                "widgetCustomization": {
                    "widgetFont": "\"Helvetica Neue\",Helvetica,Arial,sans-serif",
                    "headerColor": "#4486E1",
                    "heading": "Give ${{math programDetails.referredRewardDetails.credit ' / 100'}} and Get ${{math programDetails.referrerRewardDetails.credit ' / 100'}}!",
                    "headerDetails": "Give a friend ${{math programDetails.referredRewardDetails.credit ' / 100'}} credit off {{companyName}} and receive ${{math programDetails.referrerRewardDetails.credit ' / 100'}} for yourself when they pay their first bill.",
                    "shareCodeDetails": "Share the link below or use the code **{{user.referralCode}}**",
                    "registrationHeader": "Thanks for sending your first referral!<br>Give us your email to ensure you get rewarded when your referral is used."
                },
                "shareMessaging": {
                    "emailShareSubject": "Get ${{math programDetails.referredRewardDetails.credit ' / 100'}} off {{companyName}}",
                    "emailShareBody": "Sign up for a {{companyName}} account and we both get ${{math programDetails.referredRewardDetails.credit ' / 100'}} free credit. Use this link {{shareLinks.emailShareLink}}",
                    "facebookShareImageURL": "",
                    "facebookShareSubject": "Facebook Title in SaaSquatch Portal",
                    "facebookShareBody": "Facebook Share body in SaaSquatch Portal",
                    "twitterShareBody": "Sign up for a {{companyName}} account and we both get ${{math programDetails.referredRewardDetails.credit ' / 100'}} free credit. Use this link {{shareLinks.twitterShareLink}}",
                    "smsShareBody": "Sign up for a {{companyName}} account and we both get ${{math programDetails.referredRewardDetails.credit ' / 100'}} free credit. Use this link {{share-link 'SMS'}}"
                }
            },
            "cta": {
                "configuration": {
                    "themeMapping": "cta-widget"
                },
                "content": {
                    "buttonSide": "right",
                    "buttonPosition": "bottom",
                    "buttonColor": "#4486E1",
                    "buttonWidth": 230,
                    "buttonText": "Refer Friends For Rewards"
                }
            }
        },
        "CONVERSION_WIDGET": {
            "configuration": {
                "themeMapping": "conversion-widget"
            },
            "content": {
                "widgetCustomization": {
                    "widgetHeaderImage": "{{assets 'images/conversion.png'}}",
                    "widgetFont": "\"Helvetica Neue\",Helvetica,Arial,sans-serif",
                    "headerColor": "#444",
                    "heading": "You were Successfully Referred to {{companyName}}",
                    "headerDetails": "Use the Referral Code<br><span id=\"squatch-share-code\">{{referredBy.referredByUser.referralCode}}</span><br>at checkout to receive your referral discount",
                    "buttonCopy": "COPY CODE"
                }
            },
            "cta": {
                "configuration": {
                    "themeMapping": "cta-widget"
                },
                "content": {
                    "buttonSide": "right",
                    "buttonPosition": "bottom",
                    "buttonColor": "#4486E1",
                    "buttonWidth": 230,
                    "buttonText": "Refer Friends For Rewards"
                }
            }
        }
    },
    "email": {
        "REFERRER_REWARD_LIMIT_REACHED": {
            "configuration": {
                "fromName": "{{companyName}}",
                "fromAddress": "referral@mail.saasquat.ch",
                "subject": "You have hit the reward limit!",
                "themeMapping": "emails/referrer-reward-limit"
            },
            "content": {
                "shareCTA": "However, you can keep referring new users and giving ${{programDetails.referrerRewardDetails.credit}} off with your code. - **{{user.referralCode}}**",
                "hasShareLink": true,
                "shareButtonHeader": "Refer and Earn ${{math programDetails.referrerRewardDetails.credit ' / 100'}} of Credit",
                "headerImageUrl": "{{assets 'images/email/reward-limit-header.png'}}",
                "headerContent": "#Reward Limit\nYou have successfully referred the maximum!",
                "bodyContent": "Thanks for spreading the word about {{companyName}}. You've referred so many new people that you've earned the maximum amount of available credit."
            }
        },
        "REFERRAL_CONVERTED": {
            "configuration": {
                "fromName": "{{companyName}}",
                "fromAddress": "referral@mail.saasquat.ch",
                "subject": "Congrats! You have earned ${{math programDetails.referrerRewardDetails.credit ' / 100'}} of free credit with {{companyName}}",
                "themeMapping": "emails/referral-converted"
            },
            "content": {
                "shareCTA": "Keep sharing your code and earn more discounts - **{{user.referralCode}}**",
                "hasShareLink": true,
                "shareButtonHeader": "Refer and Earn ${{math programDetails.referrerRewardDetails.credit ' / 100'}} of Credit",
                "headerImageUrl": "{{assets 'images/email/referral-converted-header.png'}}",
                "headerContent": "#Congratulations\nYour friend has signed up for a {{companyName}} Account!",
                "bodyContent": "You have now earned ${{math programDetails.referrerRewardDetails.credit ' / 100'}} of free credit with {{companyName}}. Refer more friends to save even more!"
            }
        },
        "REFERRAL_STARTED": {
            "configuration": {
                "fromName": "{{companyName}}",
                "fromAddress": "referral@mail.saasquat.ch",
                "subject": "​{{stringEmptyHandler newReferral.referredUser.firstName onEmpty='A friend'}}​ helped you get one step closer to free credit with {{companyName}}​!",
                "themeMapping": "emails/referral-started"
            },
            "content": {
                "shareCTA": "Keep sharing your code and earn more discounts - **{{user.referralCode}}**",
                "hasShareLink": true,
                "shareButtonHeader": "Refer and Earn ${{math programDetails.referrerRewardDetails.credit ' / 100'}} of Credit",
                "headerImageUrl": "{{assets 'images/email/referral-started-header.png'}}",
                "headerContent": "#Good News!\nYour friend has signed up for a free account with {{companyName}}!",
                "bodyContent": "{{stringEmptyHandler newReferral.referredUser.firstName onEmpty='A friend'}}​ is currently trying out {{companyName}}. As a thank you from us, if they become a paying user, you will automatically receive ${{math programDetails.referrerRewardDetails.credit ' / 100'}} of free credit with {{companyName}}"
            }
        }
    }
}

Replace Variable Values PUT /api/v1/{tenant_alias}/theme/variables/instance

Replaces all of the previously set values. Use this operation only when your goal is to completely replace all variable values, including deleting previous values of othe fields that you're not setting. Prefer to use a PATCH request when you only want to update one variable or a subset of variables. See theme variables for more info.

Tags: Theme Authentication: APIKey

Arguments

Required instance
JSON Body

The variables object to replace all previously stored values.

Required tenant_alias
string

Tenant being referenced. E.g. "aboih12h16t" or "test_abo912126tastastt"

Example Curl Request

curl -X PUT https://app.referralsaasquatch.com/api/v1/{tenant_alias}/theme/variables/instance \
-u :API_KEY \
-H "Content-Type: application/json" \
-d '{
    "jsOptions": {
        "widget": {
            "defaultWidgetType": "REFERRER_WIDGET"
        },
        "conversionUrls": [
            "^https:\\/\\/example\\.com\\/thank\\-you([^a-zA-Z0-9.\\-_~!$&'()*+,;=:@/]+?.*$|$)"
        ],
        "widgetUrlMappings": [
            {
                "widgetType": "CONVERSION_WIDGET",
                "showAsCTA": true,
                "displayOnLoad": true,
                "url": "^https:\\/\\/example\\.com\\/widgetPage\\/([^a-zA-Z0-9.\\-_~!$&'()*+,;=:@/]+?.*$|$)"
            }
        ]
    },
    "widget": {
        "REFERRER_WIDGET": {
            "configuration": {
                "themeMapping": "widget"
            },
            "content": {
                "widgetCustomization": {
                    "widgetFont": "\"Helvetica Neue\",Helvetica,Arial,sans-serif",
                    "headerColor": "#4486E1",
                    "heading": "Give ${{math programDetails.referredRewardDetails.credit ' / 100'}} and Get ${{math programDetails.referrerRewardDetails.credit ' / 100'}}!",
                    "headerDetails": "Give a friend ${{math programDetails.referredRewardDetails.credit ' / 100'}} credit off {{companyName}} and receive ${{math programDetails.referrerRewardDetails.credit ' / 100'}} for yourself when they pay their first bill.",
                    "shareCodeDetails": "Share the link below or use the code **{{user.referralCode}}**",
                    "registrationHeader": "Thanks for sending your first referral!<br>Give us your email to ensure you get rewarded when your referral is used."
                },
                "shareMessaging": {
                    "emailShareSubject": "Get ${{math programDetails.referredRewardDetails.credit ' / 100'}} off {{companyName}}",
                    "emailShareBody": "Sign up for a {{companyName}} account and we both get ${{math programDetails.referredRewardDetails.credit ' / 100'}} free credit. Use this link {{shareLinks.emailShareLink}}",
                    "facebookShareImageURL": "",
                    "facebookShareSubject": "Facebook Title in SaaSquatch Portal",
                    "facebookShareBody": "Facebook Share body in SaaSquatch Portal",
                    "twitterShareBody": "Sign up for a {{companyName}} account and we both get ${{math programDetails.referredRewardDetails.credit ' / 100'}} free credit. Use this link {{shareLinks.twitterShareLink}}",
                    "smsShareBody": "Sign up for a {{companyName}} account and we both get ${{math programDetails.referredRewardDetails.credit ' / 100'}} free credit. Use this link {{share-link 'SMS'}}"
                }
            },
            "cta": {
                "configuration": {
                    "themeMapping": "cta-widget"
                },
                "content": {
                    "buttonSide": "right",
                    "buttonPosition": "bottom",
                    "buttonColor": "#4486E1",
                    "buttonWidth": 230,
                    "buttonText": "Refer Friends For Rewards"
                }
            }
        },
        "CONVERSION_WIDGET": {
            "configuration": {
                "themeMapping": "conversion-widget"
            },
            "content": {
                "widgetCustomization": {
                    "widgetHeaderImage": "{{assets 'images/conversion.png'}}",
                    "widgetFont": "\"Helvetica Neue\",Helvetica,Arial,sans-serif",
                    "headerColor": "#444",
                    "heading": "You were Successfully Referred to {{companyName}}",
                    "headerDetails": "Use the Referral Code<br><span id=\"squatch-share-code\">{{referredBy.referredByUser.referralCode}}</span><br>at checkout to receive your referral discount",
                    "buttonCopy": "COPY CODE"
                }
            },
            "cta": {
                "configuration": {
                    "themeMapping": "cta-widget"
                },
                "content": {
                    "buttonSide": "right",
                    "buttonPosition": "bottom",
                    "buttonColor": "#4486E1",
                    "buttonWidth": 230,
                    "buttonText": "Refer Friends For Rewards"
                }
            }
        }
    },
    "email": {
        "REFERRER_REWARD_LIMIT_REACHED": {
            "configuration": {
                "fromName": "{{companyName}}",
                "fromAddress": "referral@mail.saasquat.ch",
                "subject": "You have hit the reward limit!",
                "themeMapping": "emails/referrer-reward-limit"
            },
            "content": {
                "shareCTA": "However, you can keep referring new users and giving ${{programDetails.referrerRewardDetails.credit}} off with your code. - **{{user.referralCode}}**",
                "hasShareLink": true,
                "shareButtonHeader": "Refer and Earn ${{math programDetails.referrerRewardDetails.credit ' / 100'}} of Credit",
                "headerImageUrl": "{{assets 'images/email/reward-limit-header.png'}}",
                "headerContent": "#Reward Limit\nYou have successfully referred the maximum!",
                "bodyContent": "Thanks for spreading the word about {{companyName}}. You've referred so many new people that you've earned the maximum amount of available credit."
            }
        },
        "REFERRAL_CONVERTED": {
            "configuration": {
                "fromName": "{{companyName}}",
                "fromAddress": "referral@mail.saasquat.ch",
                "subject": "Congrats! You have earned ${{math programDetails.referrerRewardDetails.credit ' / 100'}} of free credit with {{companyName}}",
                "themeMapping": "emails/referral-converted"
            },
            "content": {
                "shareCTA": "Keep sharing your code and earn more discounts - **{{user.referralCode}}**",
                "hasShareLink": true,
                "shareButtonHeader": "Refer and Earn ${{math programDetails.referrerRewardDetails.credit ' / 100'}} of Credit",
                "headerImageUrl": "{{assets 'images/email/referral-converted-header.png'}}",
                "headerContent": "#Congratulations\nYour friend has signed up for a {{companyName}} Account!",
                "bodyContent": "You have now earned ${{math programDetails.referrerRewardDetails.credit ' / 100'}} of free credit with {{companyName}}. Refer more friends to save even more!"
            }
        },
        "REFERRAL_STARTED": {
            "configuration": {
                "fromName": "{{companyName}}",
                "fromAddress": "referral@mail.saasquat.ch",
                "subject": "​{{stringEmptyHandler newReferral.referredUser.firstName onEmpty='A friend'}}​ helped you get one step closer to free credit with {{companyName}}​!",
                "themeMapping": "emails/referral-started"
            },
            "content": {
                "shareCTA": "Keep sharing your code and earn more discounts - **{{user.referralCode}}**",
                "hasShareLink": true,
                "shareButtonHeader": "Refer and Earn ${{math programDetails.referrerRewardDetails.credit ' / 100'}} of Credit",
                "headerImageUrl": "{{assets 'images/email/referral-started-header.png'}}",
                "headerContent": "#Good News!\nYour friend has signed up for a free account with {{companyName}}!",
                "bodyContent": "{{stringEmptyHandler newReferral.referredUser.firstName onEmpty='A friend'}}​ is currently trying out {{companyName}}. As a thank you from us, if they become a paying user, you will automatically receive ${{math programDetails.referrerRewardDetails.credit ' / 100'}} of free credit with {{companyName}}"
            }
        }
    }
}'

Returns

Example Response

HTTP 204
statusCode
integer

The HTTP status code of the error

message
string

The human-readable description of what went wrong. Use this to help you debug.

apiErrorCode
string

A machine error code

validationErrors
array

A list of validation errors

Example Response

HTTP 400
{
    "message": "Your request failed to validate against the current variables schema.",
    "statusCode": 400,
    "apiErrorCode": "VALIDATION_FAILED",
    "validationErrors": [
        "object has missing required properties ([\"emailShareSubject\",\"facebookShareBody\",\"facebookShareSubject\",\"twitterShareBody\"])"
    ]
}

Update Variable Values PATCH /api/v1/{tenant_alias}/theme/variables/instance

Updates the previously stored values for the variables included in this request. Will not override, nullify or delete the other variable values that are not included. This method can be used to selectively set a single variable. See theme variables for more info.

Tags: Theme Authentication: APIKey UserJWT

Arguments

Required instance
JSON Body

The variables object that will update fields included here.

Required tenant_alias
string

Tenant being referenced. E.g. "aboih12h16t" or "test_abo912126tastastt"

Example Curl Request

curl -X PATCH https://app.referralsaasquatch.com/api/v1/{tenant_alias}/theme/variables/instance \
-u :API_KEY \
-H "Content-Type: application/json" \
-d '{
    "jsOptions": {
        "widget": {
            "defaultWidgetType": "REFERRER_WIDGET"
        },
        "conversionUrls": [
            "^https:\\/\\/example\\.com\\/thank\\-you([^a-zA-Z0-9.\\-_~!$&'()*+,;=:@/]+?.*$|$)"
        ],
        "widgetUrlMappings": [
            {
                "widgetType": "CONVERSION_WIDGET",
                "showAsCTA": true,
                "displayOnLoad": true,
                "url": "^https:\\/\\/example\\.com\\/widgetPage\\/([^a-zA-Z0-9.\\-_~!$&'()*+,;=:@/]+?.*$|$)"
            }
        ]
    },
    "widget": {
        "REFERRER_WIDGET": {
            "configuration": {
                "themeMapping": "widget"
            },
            "content": {
                "widgetCustomization": {
                    "widgetFont": "\"Helvetica Neue\",Helvetica,Arial,sans-serif",
                    "headerColor": "#4486E1",
                    "heading": "Give ${{math programDetails.referredRewardDetails.credit ' / 100'}} and Get ${{math programDetails.referrerRewardDetails.credit ' / 100'}}!",
                    "headerDetails": "Give a friend ${{math programDetails.referredRewardDetails.credit ' / 100'}} credit off {{companyName}} and receive ${{math programDetails.referrerRewardDetails.credit ' / 100'}} for yourself when they pay their first bill.",
                    "shareCodeDetails": "Share the link below or use the code **{{user.referralCode}}**",
                    "registrationHeader": "Thanks for sending your first referral!<br>Give us your email to ensure you get rewarded when your referral is used."
                },
                "shareMessaging": {
                    "emailShareSubject": "Get ${{math programDetails.referredRewardDetails.credit ' / 100'}} off {{companyName}}",
                    "emailShareBody": "Sign up for a {{companyName}} account and we both get ${{math programDetails.referredRewardDetails.credit ' / 100'}} free credit. Use this link {{shareLinks.emailShareLink}}",
                    "facebookShareImageURL": "",
                    "facebookShareSubject": "Facebook Title in SaaSquatch Portal",
                    "facebookShareBody": "Facebook Share body in SaaSquatch Portal",
                    "twitterShareBody": "Sign up for a {{companyName}} account and we both get ${{math programDetails.referredRewardDetails.credit ' / 100'}} free credit. Use this link {{shareLinks.twitterShareLink}}",
                    "smsShareBody": "Sign up for a {{companyName}} account and we both get ${{math programDetails.referredRewardDetails.credit ' / 100'}} free credit. Use this link {{share-link 'SMS'}}"
                }
            },
            "cta": {
                "configuration": {
                    "themeMapping": "cta-widget"
                },
                "content": {
                    "buttonSide": "right",
                    "buttonPosition": "bottom",
                    "buttonColor": "#4486E1",
                    "buttonWidth": 230,
                    "buttonText": "Refer Friends For Rewards"
                }
            }
        },
        "CONVERSION_WIDGET": {
            "configuration": {
                "themeMapping": "conversion-widget"
            },
            "content": {
                "widgetCustomization": {
                    "widgetHeaderImage": "{{assets 'images/conversion.png'}}",
                    "widgetFont": "\"Helvetica Neue\",Helvetica,Arial,sans-serif",
                    "headerColor": "#444",
                    "heading": "You were Successfully Referred to {{companyName}}",
                    "headerDetails": "Use the Referral Code<br><span id=\"squatch-share-code\">{{referredBy.referredByUser.referralCode}}</span><br>at checkout to receive your referral discount",
                    "buttonCopy": "COPY CODE"
                }
            },
            "cta": {
                "configuration": {
                    "themeMapping": "cta-widget"
                },
                "content": {
                    "buttonSide": "right",
                    "buttonPosition": "bottom",
                    "buttonColor": "#4486E1",
                    "buttonWidth": 230,
                    "buttonText": "Refer Friends For Rewards"
                }
            }
        }
    },
    "email": {
        "REFERRER_REWARD_LIMIT_REACHED": {
            "configuration": {
                "fromName": "{{companyName}}",
                "fromAddress": "referral@mail.saasquat.ch",
                "subject": "You have hit the reward limit!",
                "themeMapping": "emails/referrer-reward-limit"
            },
            "content": {
                "shareCTA": "However, you can keep referring new users and giving ${{programDetails.referrerRewardDetails.credit}} off with your code. - **{{user.referralCode}}**",
                "hasShareLink": true,
                "shareButtonHeader": "Refer and Earn ${{math programDetails.referrerRewardDetails.credit ' / 100'}} of Credit",
                "headerImageUrl": "{{assets 'images/email/reward-limit-header.png'}}",
                "headerContent": "#Reward Limit\nYou have successfully referred the maximum!",
                "bodyContent": "Thanks for spreading the word about {{companyName}}. You've referred so many new people that you've earned the maximum amount of available credit."
            }
        },
        "REFERRAL_CONVERTED": {
            "configuration": {
                "fromName": "{{companyName}}",
                "fromAddress": "referral@mail.saasquat.ch",
                "subject": "Congrats! You have earned ${{math programDetails.referrerRewardDetails.credit ' / 100'}} of free credit with {{companyName}}",
                "themeMapping": "emails/referral-converted"
            },
            "content": {
                "shareCTA": "Keep sharing your code and earn more discounts - **{{user.referralCode}}**",
                "hasShareLink": true,
                "shareButtonHeader": "Refer and Earn ${{math programDetails.referrerRewardDetails.credit ' / 100'}} of Credit",
                "headerImageUrl": "{{assets 'images/email/referral-converted-header.png'}}",
                "headerContent": "#Congratulations\nYour friend has signed up for a {{companyName}} Account!",
                "bodyContent": "You have now earned ${{math programDetails.referrerRewardDetails.credit ' / 100'}} of free credit with {{companyName}}. Refer more friends to save even more!"
            }
        },
        "REFERRAL_STARTED": {
            "configuration": {
                "fromName": "{{companyName}}",
                "fromAddress": "referral@mail.saasquat.ch",
                "subject": "​{{stringEmptyHandler newReferral.referredUser.firstName onEmpty='A friend'}}​ helped you get one step closer to free credit with {{companyName}}​!",
                "themeMapping": "emails/referral-started"
            },
            "content": {
                "shareCTA": "Keep sharing your code and earn more discounts - **{{user.referralCode}}**",
                "hasShareLink": true,
                "shareButtonHeader": "Refer and Earn ${{math programDetails.referrerRewardDetails.credit ' / 100'}} of Credit",
                "headerImageUrl": "{{assets 'images/email/referral-started-header.png'}}",
                "headerContent": "#Good News!\nYour friend has signed up for a free account with {{companyName}}!",
                "bodyContent": "{{stringEmptyHandler newReferral.referredUser.firstName onEmpty='A friend'}}​ is currently trying out {{companyName}}. As a thank you from us, if they become a paying user, you will automatically receive ${{math programDetails.referrerRewardDetails.credit ' / 100'}} of free credit with {{companyName}}"
            }
        }
    }
}'

Returns

Example Response

HTTP 200
{
    "jsOptions": {
        "widget": {
            "defaultWidgetType": "REFERRER_WIDGET"
        },
        "conversionUrls": [
            "^https:\\/\\/example\\.com\\/thank\\-you([^a-zA-Z0-9.\\-_~!$&'()*+,;=:@/]+?.*$|$)"
        ],
        "widgetUrlMappings": [
            {
                "widgetType": "CONVERSION_WIDGET",
                "showAsCTA": true,
                "displayOnLoad": true,
                "url": "^https:\\/\\/example\\.com\\/widgetPage\\/([^a-zA-Z0-9.\\-_~!$&'()*+,;=:@/]+?.*$|$)"
            }
        ]
    },
    "widget": {
        "REFERRER_WIDGET": {
            "configuration": {
                "themeMapping": "widget"
            },
            "content": {
                "widgetCustomization": {
                    "widgetFont": "\"Helvetica Neue\",Helvetica,Arial,sans-serif",
                    "headerColor": "#4486E1",
                    "heading": "Give ${{math programDetails.referredRewardDetails.credit ' / 100'}} and Get ${{math programDetails.referrerRewardDetails.credit ' / 100'}}!",
                    "headerDetails": "Give a friend ${{math programDetails.referredRewardDetails.credit ' / 100'}} credit off {{companyName}} and receive ${{math programDetails.referrerRewardDetails.credit ' / 100'}} for yourself when they pay their first bill.",
                    "shareCodeDetails": "Share the link below or use the code **{{user.referralCode}}**",
                    "registrationHeader": "Thanks for sending your first referral!<br>Give us your email to ensure you get rewarded when your referral is used."
                },
                "shareMessaging": {
                    "emailShareSubject": "Get ${{math programDetails.referredRewardDetails.credit ' / 100'}} off {{companyName}}",
                    "emailShareBody": "Sign up for a {{companyName}} account and we both get ${{math programDetails.referredRewardDetails.credit ' / 100'}} free credit. Use this link {{shareLinks.emailShareLink}}",
                    "facebookShareImageURL": "",
                    "facebookShareSubject": "Facebook Title in SaaSquatch Portal",
                    "facebookShareBody": "Facebook Share body in SaaSquatch Portal",
                    "twitterShareBody": "Sign up for a {{companyName}} account and we both get ${{math programDetails.referredRewardDetails.credit ' / 100'}} free credit. Use this link {{shareLinks.twitterShareLink}}",
                    "smsShareBody": "Sign up for a {{companyName}} account and we both get ${{math programDetails.referredRewardDetails.credit ' / 100'}} free credit. Use this link {{share-link 'SMS'}}"
                }
            },
            "cta": {
                "configuration": {
                    "themeMapping": "cta-widget"
                },
                "content": {
                    "buttonSide": "right",
                    "buttonPosition": "bottom",
                    "buttonColor": "#4486E1",
                    "buttonWidth": 230,
                    "buttonText": "Refer Friends For Rewards"
                }
            }
        },
        "CONVERSION_WIDGET": {
            "configuration": {
                "themeMapping": "conversion-widget"
            },
            "content": {
                "widgetCustomization": {
                    "widgetHeaderImage": "{{assets 'images/conversion.png'}}",
                    "widgetFont": "\"Helvetica Neue\",Helvetica,Arial,sans-serif",
                    "headerColor": "#444",
                    "heading": "You were Successfully Referred to {{companyName}}",
                    "headerDetails": "Use the Referral Code<br><span id=\"squatch-share-code\">{{referredBy.referredByUser.referralCode}}</span><br>at checkout to receive your referral discount",
                    "buttonCopy": "COPY CODE"
                }
            },
            "cta": {
                "configuration": {
                    "themeMapping": "cta-widget"
                },
                "content": {
                    "buttonSide": "right",
                    "buttonPosition": "bottom",
                    "buttonColor": "#4486E1",
                    "buttonWidth": 230,
                    "buttonText": "Refer Friends For Rewards"
                }
            }
        }
    },
    "email": {
        "REFERRER_REWARD_LIMIT_REACHED": {
            "configuration": {
                "fromName": "{{companyName}}",
                "fromAddress": "referral@mail.saasquat.ch",
                "subject": "You have hit the reward limit!",
                "themeMapping": "emails/referrer-reward-limit"
            },
            "content": {
                "shareCTA": "However, you can keep referring new users and giving ${{programDetails.referrerRewardDetails.credit}} off with your code. - **{{user.referralCode}}**",
                "hasShareLink": true,
                "shareButtonHeader": "Refer and Earn ${{math programDetails.referrerRewardDetails.credit ' / 100'}} of Credit",
                "headerImageUrl": "{{assets 'images/email/reward-limit-header.png'}}",
                "headerContent": "#Reward Limit\nYou have successfully referred the maximum!",
                "bodyContent": "Thanks for spreading the word about {{companyName}}. You've referred so many new people that you've earned the maximum amount of available credit."
            }
        },
        "REFERRAL_CONVERTED": {
            "configuration": {
                "fromName": "{{companyName}}",
                "fromAddress": "referral@mail.saasquat.ch",
                "subject": "Congrats! You have earned ${{math programDetails.referrerRewardDetails.credit ' / 100'}} of free credit with {{companyName}}",
                "themeMapping": "emails/referral-converted"
            },
            "content": {
                "shareCTA": "Keep sharing your code and earn more discounts - **{{user.referralCode}}**",
                "hasShareLink": true,
                "shareButtonHeader": "Refer and Earn ${{math programDetails.referrerRewardDetails.credit ' / 100'}} of Credit",
                "headerImageUrl": "{{assets 'images/email/referral-converted-header.png'}}",
                "headerContent": "#Congratulations\nYour friend has signed up for a {{companyName}} Account!",
                "bodyContent": "You have now earned ${{math programDetails.referrerRewardDetails.credit ' / 100'}} of free credit with {{companyName}}. Refer more friends to save even more!"
            }
        },
        "REFERRAL_STARTED": {
            "configuration": {
                "fromName": "{{companyName}}",
                "fromAddress": "referral@mail.saasquat.ch",
                "subject": "​{{stringEmptyHandler newReferral.referredUser.firstName onEmpty='A friend'}}​ helped you get one step closer to free credit with {{companyName}}​!",
                "themeMapping": "emails/referral-started"
            },
            "content": {
                "shareCTA": "Keep sharing your code and earn more discounts - **{{user.referralCode}}**",
                "hasShareLink": true,
                "shareButtonHeader": "Refer and Earn ${{math programDetails.referrerRewardDetails.credit ' / 100'}} of Credit",
                "headerImageUrl": "{{assets 'images/email/referral-started-header.png'}}",
                "headerContent": "#Good News!\nYour friend has signed up for a free account with {{companyName}}!",
                "bodyContent": "{{stringEmptyHandler newReferral.referredUser.firstName onEmpty='A friend'}}​ is currently trying out {{companyName}}. As a thank you from us, if they become a paying user, you will automatically receive ${{math programDetails.referrerRewardDetails.credit ' / 100'}} of free credit with {{companyName}}"
            }
        }
    }
}
statusCode
integer

The HTTP status code of the error

message
string

The human-readable description of what went wrong. Use this to help you debug.

apiErrorCode
string

A machine error code

validationErrors
array

A list of validation errors

Example Response

HTTP 400
{
    "message": "Your request failed to validate against the current variables schema.",
    "statusCode": 400,
    "apiErrorCode": "VALIDATION_FAILED",
    "validationErrors": [
        "object has missing required properties ([\"emailShareSubject\",\"facebookShareBody\",\"facebookShareSubject\",\"twitterShareBody\"])"
    ]
}

Preview Theme Email POST /api/v1/{tenant_alias}/theme/email/{email_type}/preview

Generates preview content for a themed email. If the sendTo parameter is set this content will be sent to the provided email address otherwise the content will be returned in the response.

Tags: Theme Authentication: APIKey

Arguments

Required tenant_alias
string

Tenant being referenced. E.g. "aboih12h16t" or "test_abo912126tastastt"

Required email_type
string

The type of email to be previwed. E.g. REFERRAL_STARTED or REFERRAL_CONVERTED, see theme mappings in email theming for details.

locale
string

The user locale, used for Internationalization.

sendTo
string

If an email address is set in the sendTo parameter the preview email content will be delivered to the provided address.

Example Curl Request

curl -X POST https://app.referralsaasquatch.com/api/v1/{tenant_alias}/theme/email/{email_type}/preview \
-u :API_KEY \
-H "Content-Type: application/json" \
-d ''

Returns

Example Response

HTTP 200
"<html> <head> ... </head> <body> <h1>Congratulations Mike</h1> Your friend John has accepted your referral. You will now receive 10% off your next bill. ... </body> </body>"

Example Response

HTTP 204

Lookup a discount code GET /api/v1/{tenant_alias}/discount/{code}

This method lets you look up the details of a referral code and to ensure that it is valid. Works with PCT_DISCOUNT

Tags: Discount Authentication: APIKey

Arguments

Required code
string

The coupon/referral code to look up. Eg. BOBTESTERSON

Required tenant_alias
string

Tenant being referenced. E.g. "aboih12h16t" or "test_abo912126tastastt"

Example Curl Request

curl -X GET https://app.referralsaasquatch.com/api/v1/{tenant_alias}/discount/{code} \
-u :API_KEY \

Returns

couponCode
string

The coupon/referral code

referrerName
string

The full name of the referrer who owns this code.

discountPercentage
integer

An integer representing the discount percentage. e.g. For 10% would return the number 10.

dateCreated
integer

Timestamp - The coupon/referral code to look up

ratePlanId
string

Zuora only The Zuora rate plan ID used to apply this coupon.

discountId
string

Braintree only The Braintree discount ID used to apply this coupon.

Example Response

HTTP 200
{
    "couponCode": "BOBTESTERSON",
    "discountPercentage": 20,
    "dateCreated": 1377727546528,
    "discountId": "saasquatch_discount"
}
statusCode
integer

The HTTP status code of the error

message
string

The human-readable description of what went wrong. Use this to help you debug.

apiErrorCode
string

A machine error code

Example Response

HTTP 404

Set discount code on an account POST /api/v1/{tenant_alias}/discount

This method associates a new account with their referrer. Use this method when someone signs up for a paid account to set the coupon code used for them. For Stripe and Recurly do not use this call. Instead during sign-up, just pass the coupon/referral code in your subcribe call. Works with PCT_DISCOUNT

Tags: Discount Authentication: APIKey

Arguments

Required accountDiscount
JSON Body

Account discount details to be updated

Required accountId
string

Unique identifier for the account. We use this ID to link a group of users together. See Shared vs Solo Accounts to see what you should use here.

Required paymentProviderId
string

The payment provider ID of the newly created account from Braintree or Zuora. This will be the Braintree Account ID or the Zuora Account ID of the newly created account.

Required couponCode
string

The coupon/referral code of the user that referred this user. Can be obtained from the referral-tracking cookie using squatch.js coupon autofill.

Required tenant_alias
string

Tenant being referenced. E.g. "aboih12h16t" or "test_abo912126tastastt"

Example Curl Request

curl -X POST https://app.referralsaasquatch.com/api/v1/{tenant_alias}/discount \
-u :API_KEY \
-H "Content-Type: application/json" \
-d '{
    "accountId": "abc123",
    "paymentProviderId": "cus_123",
    "couponCode": "BOBTESTERSON"
}'

Returns

Example Response

HTTP 200

Example Response

HTTP 400

Lookup an account discount GET /api/v1/{tenant_alias}/account/{accountId}/discount

This method information about an account's discount, if any, and what that discount would look like with a couponCode applied. Works with PCT_DISCOUNT

Tags: Discount Authentication: APIKey

Arguments

Required accountId
string

The account to look up

couponCode
string

When included, will return a total reward available including any coupon code.

Required tenant_alias
string

Tenant being referenced. E.g. "aboih12h16t" or "test_abo912126tastastt"

Example Curl Request

curl -X GET https://app.referralsaasquatch.com/api/v1/{tenant_alias}/account/{accountId}/discount \
-u :API_KEY \

Returns

accountId
string

The account id

discountPercentage
integer

An integer representing the total discount percentage from the referral program. e.g. For 10% would return the number 10. discountPercentage = referredDiscountPercent + referrerDiscountPercent

referredDiscountPercent
integer

An integer representing the discount percentage from being referred. This will only have a value if the account has a coupon/referral code already associated with it, or if couponCode was passed as an argument.

referrerDiscountPercent
integer

An integer representing the discount earned from referring other accounts.

ratePlanId
string

Zuora only The Zuora rate plan ID used to apply the discount.

discountId
string

Braintree only The Braintree discount ID used to apply the discount.

referrerName
string

The first and last name of the referrer that referred the user or null if this account was not referred.

Example Response

HTTP 200
{
    "accountId": "SV0TYE5OWI11120144",
    "discountPercentage": 10,
    "referrerDiscountPercent": 0,
    "referredDiscountPercent": 10,
    "discountId": "saasquatch_discount"
}
statusCode
integer

The HTTP status code of the error

message
string

The human-readable description of what went wrong. Use this to help you debug.

apiErrorCode
string

A machine error code

Example Response

HTTP 404