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.

Rate Limits

All API requests made to GrowSurf (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://growsurf.com/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

Policies

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

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 GrowSurf on each page load, that data should be cached and loaded from that cache instead of being requested from the GrowSurf 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 GrowSurf

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

Metadata

Certain GrowSurf objects, such as Participants and Rewards can have a special metadataparameter, which is useful for storing any custom information. Metadata is not used by GrowSurf.

Here are some examples of how you could use metadata:

• 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 issuance.

Policies

The following are the policies when creating or updating metadata.

​