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.
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 |
| The number of API requests that are allowed per second. |
| The number of API requests remaining within the second policy. |
| The window of time that the This value is only provided if the second policy is hit or exceeded. |
| The number of API requests that are allowed per minute. |
| The number of API requests remaining within the minute policy. |
| The window of time that the 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. |
| The number of API requests that are allowed per hour. |
| The number of API requests remaining within the hour policy. |
| The window of time that the 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).
Please note that if you hit a rate limit or max connection limit, you will see a 429
error.
Suggestions
Here are some suggestions for using the GrowSurf API within policy limits.
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 receive 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 metadata
parameter, 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, REST API, JavaScript Web API, and embeddable elements
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
Setting participant metadata
There are several different ways to save metadata to a participant.
Campaign Editor
For referred participants:
From Campaign Editor > 5. Installation, navigate to the automagic form detection setup section (the page with the title "Choose forms from your site or web app to automatically track."). This form is for tracking referred people who came to your website through their friend's unique referral link.
Select a form and choose the input fields to save with each form submission. Any custom field that is not "Email", "First Name", or "Last Name" will be saved as metadata.
For referrers (your users/customers):
From Campaign Editor > 2. Design, you can update the Signup Form with custom fields. This signup form is intended for your users/customers who sign up to your referral program in order to refer their friends.
When a participant submits a new task from your referral portal, they will need to submit the custom fields as well, which will be saved as participant metadata.
Admin Dashboard
When you are viewing a participant from the GrowSurf admin dashboard, you can add or update their metadata.
REST API
You can use these REST API endpoints to add or update a participant's metadata:
For adding new participants:
For updating existing participants:
JavaScript Web API
You can use the JavaScript method growsurf.addParticipant()
to add metadata to a participant. Any keys other than email
, firstName
, and lastName
will be saved as metadata. Metadata will only be set for new participants.
Example:
Note: Participant metadata cannot be updated using the JavaScript Web API. You must use the REST API to update metadata for existing participants.
Embeddable Elements
You can pass in custom participant values into any Embeddable Element using the data-grsf-metadata
attribute. Metadata will only be set for new participants.
Example:
Note: Participant metadata cannot be updated using embeddable elements. You must use the REST API to update metadata for existing participants.
Setting reward metadata
There is only one way to update reward metadata, from Campaign Editor > 1. Rewards.
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.
Last updated