Rest API Reference

Delete an account in your SaaSquatch project. This endpoint will delete the account and all users on the account. Learn more about Accounts vs. Users in our article on Account Structure.

To delete only a specific User on the Account use the Delete User endpoint.

Learn more about deleting participants within your SaaSquatch project in our article on Participant Deletion

Include the doNotTrack query parameter as true to indicate to the SaaSquatch system that all currently-registered Users on this Account should not be able to be re-registered on the same Account. Learn more about doNotTrack in our article on Participant Deletion

Returns details of the Personally identifiable information stored in the SaaSquatch system for a specific SaaSquatch user.

Warning! This method should only be used in connection with data protection and privacy compliance.

For programatically looking up information about users within your SaaSquatch project, please use the Lookup User endpoint

Block a user from making successful referrals based upon their user and account id. More information about blocking users from participating in your referral program can be found in the SaaSquatch docs.

Unblock a user based upon their user and account id. More information about blocking users from participating in your referral program can be found in the SaaSquatch docs.

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.

This method updates/creates a user and an account and returns the user object representing that newly created user/account.

You can provide vanity referral codes and sharelinks in a user upsert. Make sure to check the tenant setting allowReferralCodeEditOnUserUpsert, if it is set to FALSE then referral codes added when upserting an existing user will be ignored. New sharelinks and referral codes will be set as primary for the upserted user. If a referral code is passed without an associated sharelink for that program, then one will be generated and vice versa for sharelinks.

Because this call creates a user, it requires either a write token or an API key.

This method creates a user and an account and returns the user object representing that newly created user/account.

You can provide vanity referral codes and sharelinks when creating a user and account. Make sure to check the tenant setting allowReferralCodeEditOnUserUpsert, if it is set to FALSE then referral codes added when using this method on an existing user will be ignored. New sharelinks and referral codes will be set as primary for the given user. If a referral code is passed without an associated sharelink for that program, then one will be generated and vice versa for sharelinks.

Because this call creates a user, it requires either a write token or an API key.

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.

Delete a user in your SaaSquatch project. By default this endpoint only deletes a User on an Account (and not the Account itself). Learn more about Accounts vs. Users in our article on Account Structure.

To delete both the Account (and all the users on the account), use the Delete Account endpoint.

Learn more about deleting participants within your SaaSquatch project in our article on Participant Deletion

Include the doNotTrack query parameter as true to indicate to SaaSquatch that the user should not be able to be re-registered on the same account. Learn more about doNotTrack in our article on Participant Deletion

Include the preserveEmptyAccount query parameter as false to indicate to SaaSquatch that the users account should be deleted if there are no other users in the account.

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.

This API method returns the full list of referral share links for a user. Optional filter parameters are available to return only links of a specific share or engagement medium.

Share links are made available to a Referrer to provide to their friends and family to click and be directed to your referral program landing page.

The sharelinks are segmented by Engagement Medium, which is the channel the Referrer accessed the program to be able to share out their referral through. For each Engagment Medium, like EMBED, a link is provided for each available Share Medium. This segmentation is used to power the SaaSquatch analytics platform to provide information about how, and where, your users are interacting with your referral program. For example, The WHATSAPP link from the MOBILE section is intended to be used to indicated to our system that the Referrer accessed the referral program from a mobile device and shared their referral with their friend using Whatsapp. More information about available Engagement Mediums and Share Mediums can be found in our success center.

Additionally, a clean share link is provided. If the given link is a vanity link, then the clean share link will have no encoding, for example http://example.com/free. The clean share link will have the UNKNOWN Share Medium and UNKNOWN Engagement Medium link.

Share links work by dropping a tracking cookie in the user's browser when the user clicks the link and is directed to your referral program's landing page. This cookie includes the referral code of the Referrer that shared it. Once on your website this cookie can be read using the squatch.js autofill method and is also automatically picked up by our squatch.js library to connect referrals.

The referral code is also passed along to your referral program landing page as the URL parameter rsCode. For example http://ssqt.co/pZVp redirects to https://www.google.ca/?rsCode=JOHNDOE.

This API method returns the full list of referral share links for a user. Optional filter parameters are available to return only links of a specific share or engagement medium.

Share links are made available to a Referrer to provide to their friends and family to click and be directed to your referral program landing page.

The sharelinks are segmented by Engagement Medium, which is the channel the Referrer accessed the program to be able to share out their referral through. For each Engagment Medium, like EMBED, a link is provided for each available Share Medium. This segmentation is used to power the SaaSquatch analytics platform to provide information about how, and where, your users are interacting with your referral program. For example, The WHATSAPP link from the MOBILE section is intended to be used to indicated to our system that the Referrer accessed the referral program from a mobile device and shared their referral with their friend using Whatsapp. More information about available Engagement Mediums and Share Mediums can be found in our success center.

Additionally, a clean share link is provided. If the given link is a vanity link, then the clean share link will have no encoding, for example http://example.com/free. The clean share link will be the UNKNOWN Share Medium and UNKNOWN Engagement Medium link.

Share links work by dropping a tracking cookie in the user's browser when the user clicks the link and is directed to your referral program's landing page. This cookie includes the referral code of the Referrer that shared it. Once on your website this cookie can be read using the squatch.js autofill method and is also automatically picked up by our squatch.js library to connect referrals.

The referral code is also passed along to your referral program landing page as the URL parameter rsCode. For example http://ssqt.co/pZVp redirects to https://www.google.ca/?rsCode=JOHNDOE.

This method can be used to track when users make purchases, download items, or take other meaningful actions that you want to use to trigger your programs.

To prevent processing an event more than once, you can provide an idempotency key to achieve "at most once" processing semantics. The idempotency key uniquely identifies the event, and is generated by the caller.

The idempotency key can be any string identifier that your system associates with the event, with the following restrictions:

• It must be at least 8 characters long
• It must be no more than 64 characters long
• It can only contain alphanumerics characters, as well as the ., -, or _ characters

For example, a good choice for an idempotency key is a UUID, in particular a random version 4 UUID like ec524601-975c-458a-9948-ae4448ce8944.

Idempotency keys are guaranteed to be stored by SaaSquatch for at least 24 hours, such that any event inputs with the same idempotency key within 24 hours will be guaranteed to process the events only once.

Subsequent attempts to process an event with an idempotency key that has already been processed once will result in an HTTP 409 Conflict response, so you will need to ensure that you are handling this status code in your request logic.

Looks up a referral code and the attached details. Deprecated in favour of its Open Endpoint equivalent.

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.

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.

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.

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.

Lists 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.

Note: Either the referringAccountId and referringUserId or referredAccountId and referredUserId parameters are required, along with a read token for authenticaion.

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

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

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

Looks up a list of single rewards

Used to lookup an individual reward using the ID of the reward. Works with: CREDIT, PCT_DISCOUNT, and FUELTANK

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

Used to cancel an individual reward earned from a referral program. Works with: CREDIT, PCT_DISCOUNT, and FUELTANK

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).

Subscribes a URL to receive events via webhooks

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

Removes a URL from receiving events via webhooks

Sends a test event to the specified webhook

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 in the requested format (CSV or zipped XLSX) 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.

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.

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.

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