API Guidelines

Follow these standard guidelines when interacting with LoyaltySurf APIs.

Requests

• All requests should be made using HTTPS.

• JSON objects are recommended for POST requests, but standard parameters are accepted.

• All parameters are required unless otherwise specified.

Responses

• Data is returned in JSON.

• Any non-200 HTTP response code can be considered an error.

Tip: Refer to Response Codes for help in troubleshooting any errors.

Rate Limits

All API requests made to LoyaltySurf (including client and server calls) are appropriately rate-limited to prevent excessive requests. If you exceed those limits, you will start receiving 429 error responses for any API calls that you make. Those 429 responses will have the following format.

{
    "name": "RateLimit",
    "code": "RATE_LIMIT",
    "message": "You have reached your minute limit.",
    "status": 429,
    "supportUrl": "https://loyaltysurf.io/settings#contact_support",
    "policyName": "MINUTE",
    "level": "error",
    "timestamp": "2019-12-08T00:05:45.478Z"
}

The message and policyName will indicate which limit you hit (e.g. second, minute, or hour).

Rate Headers

NOTE: These headers are only included for requests made using an API key.

Header	Description
LoyaltySurf-RateLimit-Second-Limit	The number of API requests that are allowed per second.
LoyaltySurf-RateLimit-Second-Remaining	The number of API requests remaining within the second policy.
LoyaltySurf-Retry-After-Second-Milliseconds	The window of time that the LoyaltySurf-RateLimit-Second-Limit and LoyaltySurf-RateLimit-Second-Remaining headers apply to. For example, a value of 1000 would be a window of 1 second. This value is only provided if the second policy is hit or exceeded.
LoyaltySurf-RateLimit-Minute-Limit	The number of API requests that are allowed per minute.
LoyaltySurf-RateLimit-Minute-Remaining	The number of API requests remaining within the minute policy.
LoyaltySurf-Retry-After-Minute-Milliseconds	The window of time that the LoyaltySurf-RateLimit-Minute-Limit and LoyaltySurf-RateLimit-Minute-Remaining headers apply to. For example, a value of 10000 would be a window of 10 seconds. This value is only provided if the minute policy is hit or exceeded.
LoyaltySurf-RateLimit-Hour-Limit	The number of API requests that are allowed per hour.
LoyaltySurf-RateLimit-Hour-Remaining	The number of API requests remaining within the hour policy.
LoyaltySurf-Retry-After-Hour-Milliseconds	The window of time that the LoyaltySurf-RateLimit-Hour-Limit and LoyaltySurf-RateLimit-Hour-Remaining headers apply to. For example, a value of 600000 would be a window of 10 minutes. This value is only provided if the hour policy is hit or exceeded.

Policies

The following are the rate limits for all API requests made using an API key.

Policy	Limit
Second	30 requests / 5 seconds
Minute	200 requests / minute
Hour	10,000 requests / hour

Slowdown Rate

For operations which update a resource (PUT, POST, DELETE), if the cumulative rate of requests exceed 60 requests per minute, a slowdown delay will be added to each request thereafter. The delay is equal to the number of exceeded requests multiplied by 100 milliseconds (ms).

For example:

• 61st request: 100ms delay

• 63rd request: 300ms delay

• 70th request: 1000ms delay

Max Connections

In addition to the rate limits and slowdown rate, the number of concurrent connections to the REST API allowed per IP address is limited to three (3).

Suggestions

If you find that you are still hitting call limits after implementing the below suggestions, please contact us and let us know as many details as possible (what APIs you are using, your use case, and which limits you are hitting).

1. Cache data for repeat calls

If your site or app uses data from LoyaltySurf on each page load, that data should be cached and loaded from that cache instead of being requested from the LoyaltySurf APIs each time. If you're making repeated requests to get participant information or campaign data for a custom implementation, the information from those calls should also be cached when possible.

2. Use Webhooks to get updated data from LoyaltySurf

Webhooks are an excellent way for your application to receive updated information from LoyaltySurf without needing to call LoyaltySurf APIs. More details about using Webhooks can be found here, with example data here.

Metadata

Certain LoyaltySurf objects, such as Participants and Rewards can have a special metadataparameter, which is useful for storing any custom information.

Here are some examples of how you could use metadata:

• Issue different reward values to participants based on their different metadata properties. Learn more here.

• If you need to save custom data to a participant to display or use later in your own application.

• Attach custom key/value data to rewards in your campaign to retrieve later via the REST API when automating a reward via Webhooks or Zapier.

Participant metadata:

• Can be set via the campaign editor, admin dashboard, and REST API

• Can be retrieved via REST API and is available via Webhooks

• Can be viewed from your admin dashboard and when you download your participants list

Reward metadata:

• Can be set via the campaign editor

• Can be retrieved via REST API and is available via Webhooks

• Can be used within LoyaltySurf emails

Setting participant metadata

There are several different ways to save metadata to a participant.

Campaign Editor

From Campaign Editor > 2. Design, you can update the Signup/Login Form with custom fields. When a participant submits a new task from your advocate portal, they will need to submit the custom fields as well, which will be saved as participant metadata.

Update the Signup/Login Form in the campaign editor

When a participant signs up for the first time on your advocate portal, custom fields will be saved as metadata

Admin Dashboard

When you are viewing a participant from the LoyaltySurf admin dashboard, you can add or update their metadata.

Update a participant in the admin dashboard

REST API

You can use these REST API endpoints to add or update a participant's metadata:

For adding new participants:

• /POST Trigger Loyalty Action by Email

• /POST Add Participant

For updating existing participants:

• /POST Update Participant by ID

• /POST Update Participant by Email

Setting reward metadata

There is only one way to update reward metadata, from Campaign Editor > 1. Rewards.

Add/edit reward metadata from the campaign editor

Policies

The following are the policies when creating or updating metadata.

Policy	Limit
Metadata Key	40 characters
Metadata Value	500 characters
Total Metadata Keys	50 keys / object
Key Characters	Alphanumeric

All metadata keys will be converted to camelCase. For example, if you provide a key "My Metadata Key" that key will be converted to "myMetadataKey".

Note: Do not store any sensitive information (personally identifiable information, such as credit cards and social security numbers) as metadata within LoyaltySurf.