API Guidelines

Help Center System Status Contact Support Your Dashboard →
Search…
API Guidelines
Follow these standard guidelines when interacting with GrowSurf 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 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
 NOTE: These headers are only included for requests made using an API key.
Header
Description
GrowSurf-RateLimit-Second-Limit
The number of API requests that are allowed per second.
GrowSurf-RateLimit-Second-Remaining
The number of API requests remaining within the second policy.
GrowSurf-Retry-After-Second-Milliseconds
 The window of time that the  GrowSurf-RateLimit-Second-Limit and Growsurf-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.
GrowSurf-RateLimit-Minute-Limit
The number of API requests that are allowed per minute.
GrowSurf-RateLimit-Minute-Remaining
The number of API requests remaining within the minute policy.
GrowSurf-Retry-After-Minute-Milliseconds
 The window of time that the  GrowSurf-RateLimit-Minute-Limit and Growsurf-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.
GrowSurf-RateLimit-Hour-Limit
The number of API requests that are allowed per hour.
GrowSurf-RateLimit-Hour-Remaining
The number of API requests remaining within the hour policy.
GrowSurf-Retry-After-Hour-Milliseconds
The window of time that the  GrowSurf-RateLimit-Hour-Limit and Growsurf-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
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.
Participant metadata:
Can be set via admin dashboard, REST API and JavaScript Web 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 in pre-populated social share and invite messages, and within GrowSurf emails
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 GrowSurf. 
​
Getting Started for Native Mobile
API Response Codes
Last modified 6mo ago
Copy link
Outline
Requests
Responses
Rate Limits
Rate Headers
Policies
Suggestions
Metadata
Policies