Gleam API
The Gleam API is available on the Premium plan. If you would like to suggest changes or additional endpoints, please don't hesitate to contact us.
It is accessed via Site Settings sidebar option -> API (BETA) tab.
This tab contains:
- The ability to generate API tokens.
- An API Explorer for testing interactions with the API.
- Automatically generated code Snippets (currently in Ruby and Node.js).
Authentication is handled via the Authorization
header. The value uses the word "Token" followed by a space then the token. E.g. Token h0GKz4dQuItT6DUH
GET https://gleam.io/api/v2/sites/[site_id]/competitions/[competition_key]/actions
Parameter | Format | Default | Description |
---|---|---|---|
page | integer | 1 | The page number to display |
per_page | integer | 20 | The number of entries returned per page. Maximum of 500. |
string | The user's email to filter on. | ||
entry_method_id | integer | The ID of the action you wish to filter on. You can get this ID using the Competitions API endpoint. |
Expand
{
"data": [
{
"id": 2002939101,
"created_at": "2018-12-04T04:16:26Z",
"value": null,
"name": "John Sherwood",
"email": "john@gleam.io",
"username": "Ponny",
"user_id": "16584810",
"status": "Valid",
"country_code": "AU",
"city": "Carlton North",
"region": "VIC",
"country": "Australia",
"avatar_url": "https://user-assets.out.sh/twitter/d4/6f/06fd45fce5d6f1e80ab7f3105ef1/avatar.jpg",
"archived": false,
"worth": 1,
"action": {
"id": 800,
"type": "twitter_follow",
"worth": 1,
"mandatory": false,
"config1": "GleamApp",
"config2": null,
"config3": null,
"config4": null,
"config5": null,
"config6": null,
"config7": null,
"config8": null,
"config9": null,
"config_selections": [],
"image": null,
"config_toggle": false,
"actions_required": 0
}
},
{
"id": 2002938826,
"created_at": "2018-12-04T04:16:12Z",
"value": "It's okay...",
"name": "John Sherwood",
"email": "john@gleam.io",
"username": null,
"user_id": null,
"status": "Valid",
"fraud_type": null,
"fraud_description": null,
"country_code": "AU",
"city": "Carlton North",
"region": "VIC",
"country": "Australia",
"avatar_url": "https://user-assets.out.sh/twitter/d4/6f/06fd45fce5d6f1e80ab7f3105ef1/avatar.jpg",
"archived": false,
"worth": 1,
"action": {
"id": 793,
"type": "question",
"worth": 1,
"mandatory": false,
"config1": "What Do You Think Of Gleam?",
"config2": null,
"config3": null,
"config4": "Tell us what you think of Gleam!",
"config5": null,
"config6": null,
"config7": null,
"config8": null,
"config9": null,
"config_selections": [],
"image": null,
"config_toggle": false,
"actions_required": 0
}
},
],
"pagination": {
"results": 2,
"page": 1,
"page_size": 20,
"total_pages": 1,
"total_count": 2
}
}
POST https://gleam.io/api/v2/sites/[site_id]/competitions/[competition_key]/actions
Parameter | Format | Default | Description |
---|---|---|---|
string | The user's email. Required. | ||
name | string | The user's name. | |
entry_method_id | integer | A generated action | The ID of the action you wish to add to. If not specified, a generated 'API Import' action will be created if it does not already exist. Otherwise, actions will be added to the existing 'API Import' action. |
worth | integer | 1 | Will default to the Entry Method's default worth if specified |
repeatable | true/false | false | Mutually exclusive with entry_method_id. If entry_method_id is specified, the entry interval for the Entry Method will be used. |
value | string | The value to set for the Action. Handled differently per Action type. |
Expand
{
"name": "Jill Bloggs",
"email": "hello@example.com",
"worth": 100,
"value": "Order ID 123456",
"entry_method_id": "12345",
"repeatable": "true"
}
Expand
{
"success": true,
"result": {
"id": 124392
}
}
GET https://gleam.io/api/v2/sites/[site_id]/rewards/[reward_key]/actions
Parameter | Format | Default | Description |
---|---|---|---|
page | integer | 1 | The page number to display |
per_page | integer | 20 | The number of entries returned per page. Maximum of 500. |
string | The user's email to filter on. | ||
entry_method_id | integer | The ID of the action you wish to filter on. You can get this ID using the Rewards API endpoint. |
Expand
{
"data": [
{
"id": 2005022797,
"created_at": "2018-12-05T02:21:03Z",
"value": null,
"name": "John Sherwood",
"email": "john@gleam.io",
"username": null,
"user_id": null,
"status": "Valid",
"country_code": "AU",
"city": "Carlton North",
"region": "VIC",
"country": "Australia",
"avatar_url": "https://user-assets.out.sh/twitter/d4/6f/06fd45fce5d6f1e80ab7f3105ef1/avatar.jpg",
"archived": false,
"action": {
"id": 150302,
"type": "email_subscribe",
"worth": 1,
"mandatory": false,
"config1": "Get Our Game Development Updates!",
"config2": null,
"config3": null,
"config4": "Off",
"config5": null,
"config6": null,
"config7": null,
"config8": null,
"config9": null,
"config_selections": [],
"image": null,
"config_toggle": false,
"actions_required": 0
}
},
{
"id": 2005022645,
"created_at": "2018-12-05T02:20:58Z",
"value": "It looks fun, I suppose",
"name": "John Sherwood",
"email": "john@gleam.io",
"username": null,
"user_id": null,
"status": "Valid",
"country_code": "AU",
"city": "Carlton North",
"region": "VIC",
"country": "Australia",
"avatar_url": "https://user-assets.out.sh/twitter/d4/6f/06fd45fce5d6f1e80ab7f3105ef1/avatar.jpg",
"archived": false,
"action": {
"id": 150301,
"type": "question",
"worth": 1,
"mandatory": false,
"config1": "Why Do You Want To Play?",
"config2": null,
"config3": null,
"config4": "Tell us what you like about the game? What makes you want to play it?",
"config5": null,
"config6": null,
"config7": null,
"config8": null,
"config9": null,
"config_selections": [],
"image": null,
"config_toggle": false,
"actions_required": 0
}
},
],
"pagination": {
"results": 2,
"page": 1,
"page_size": 20,
"total_pages": 1,
"total_count": 2
}
}
POST https://gleam.io/api/v2/sites/[site_id]/rewards/[reward_key]/actions
Parameter | Format | Default | Description |
---|---|---|---|
string | The user's email. Required. | ||
name | string | The user's name. | |
entry_method_id | integer | A generated action | The ID of the action you wish to add to. If not specified, a generated 'API Import' action will be created if it does not already exist. Otherwise, actions will be added to the existing 'API Import' action. |
repeatable | true/false | false | Mutually exclusive with entry_method_id. If entry_method_id is specified, the entry interval for the Entry Method will be used. |
value | string | The value to set for the Action. Handled differently per Action type. |
Expand
{
"name": "Jill Bloggs",
"email": "hello@example.com",
"value": "Order ID 123456",
"entry_method_id": "12345",
"repeatable": "true"
}
Expand
{
"success": true,
"result": {
"id": 124392
}
}
GET https://gleam.io/api/v2/sites/[site_id]/captures/[capture_key]/actions
Parameter | Format | Default | Description |
---|---|---|---|
page | integer | 1 | The page number to display |
per_page | integer | 20 | The number of entries returned per page. Maximum of 500. |
string | The user's email to filter on. | ||
entry_method_id | integer | The ID of the action you wish to filter on. You can get this ID using the Captures API endpoint. |
Expand
{
"data": [
{
{
"id": 2266773446,
"created_at": "2019-06-18T05:35:51Z",
"name": "John Sherwood",
"email": "john@gleam.io",
"country_code": "AU",
"city": "Melbourne",
"region": "VIC",
"country": "Australia",
"location": "https://gleam.io/blog/"
}
],
"pagination": {
"results": 1,
"page": 1,
"page_size": 20,
"total_pages": 1,
"total_count": 1
}
}
POST https://gleam.io/api/v2/sites/[site_id]/captures/[capture_key]/actions
Parameter | Format | Default | Description |
---|---|---|---|
string | The user's email. Required. | ||
name | string | The user's name. | |
entry_method_id | integer | A generated action | The ID of the action you wish to add to. If not specified, a generated 'API Import' action will be created if it does not already exist. Otherwise, actions will be added to the existing 'API Import' action. |
repeatable | true/false | false | Mutually exclusive with entry_method_id. If entry_method_id is specified, the entry interval for the Entry Method will be used. |
value | string | The value to set for the Action. Handled differently per Action type. |
Expand
{
"name": "Jill Bloggs",
"email": "hello@example.com",
"value": "Order ID 123456",
"entry_method_id": "12345",
"repeatable": "true"
}
Expand
{
"success": true,
"result": {
"id": 124392
}
}
GET https://gleam.io/api/v2/sites/[site_id]/competitions
Parameter | Format | Default | Description |
---|---|---|---|
page | integer | 1 | The page number to display |
per_page | integer | 20 | The number of Competitions returned per page. Maximum of 500. |
Expand
{
"data": [
{
"key": "PSkQl",
"name": "Win a Playstation 14",
"created_at": "2018-12-05T02:36:33Z",
"reporting": {
"impressions": 10,
"actions": 3,
"entries": 30,
"users": 2
},
"starts_at": "2018-12-04T13:00:00Z",
"ends_at": "2019-01-04T12:59:59Z",
"prize": {
"name": "Win a Playstation 14!!!",
"description": "<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam faucibus pulvinar tortor, vel aliquam urna. Morbi sagittis iaculis lacinia. Aenean sed dui placerat, vulputate dui vel, tempor nisi. In nec magna tristique, interdum elit at, molestie nisl. Vestibulum vestibulum eget orci vitae imperdiet. <br></p>",
"quantity": 1,
"images": []
},
"entry_methods": [
{
"id": 3844619,
"type": "email_subscribe",
"worth": 1,
"mandatory": true,
"config1": "Join The Gleam.io Growth List",
"config2": null,
"config3": null,
"config4": "Off",
"config5": null,
"config6": null,
"config7": null,
"config8": null,
"config9": null,
"config_selections": [],
"image": null,
"config_toggle": false,
"actions_required": 0
},
{
"id": 3844620,
"type": "share_action",
"worth": 1,
"mandatory": false,
"config1": "Refer Friends For Extra Entries",
"config2": null,
"config3": "Hey,\r\n\r\nHave you entered this competition to win %{incentive} yet?\r\n\r\nIf you refer friends you get more chances to win :)\r\n\r\n%{link}",
"config4": null,
"config5": null,
"config6": null,
"config7": null,
"config8": null,
"config9": null,
"config_selections": [
"EMAIL",
"FACEBOOK",
"TWITTER",
"GOOGLE_PLUS"
],
"image": null,
"config_toggle": false,
"actions_required": 0
}
],
"allowed_countries": null,
"disallowed_countries": null
},
{
"key": "u7lRq",
"name": "Nintendo Switch + Super Smash Bros. Giveaway",
"created_at": "2018-12-04T00:36:11Z",
"reporting": {
"impressions": 0,
"actions": 0,
"entries": 0
},
"starts_at": "2018-12-04T08:00:00Z",
"ends_at": "2018-12-22T07:59:59Z",
"prize": {
"name": "Nintendo Switch + Super Smash Bros. Ultimate",
"description": "<p>To celebrate the holiday season we're giving away a Nintendo Switch and 6 copies of Super Smash Bros. Ultimate.</p><p><b>One lucky winner</b> will receive the Nintendo Switch and Super Smash Bros. and <b>five runners-up</b> will each get a copy of Super Smash Bros.</p><p>Enter below for your chance to win the ultimate Christmas present!</p><p>Contest is open worldwide 🌎</p><p>Don't forget to complete every action and share with your friends for more chances to win 😎</p>",
"quantity": 6,
"images": [
"https://gleam-prod-user-assets.s3.amazonaws.com/user-assets/579570/BGCNG5Tj9Utoqg1q/switch-smash-giveaway-5.png"
]
},
"entry_methods": [
{
"id": 3840631,
"type": "bonus",
"worth": 1,
"mandatory": true,
"config1": "Click Here to Confirm Your Entry // Entry Confirmed - More Ways to Enter Below",
"config2": null,
"config3": null,
"config4": null,
"config5": null,
"config6": null,
"config7": null,
"config8": null,
"config9": null,
"config_selections": [],
"image": null,
"config_toggle": false,
"actions_required": 0
},
{
"id": 3840632,
"type": "facebook_visit",
"worth": 1,
"mandatory": false,
"config1": "https://www.facebook.com/Gleamapp/",
"config2": "Gleam",
"config3": "609377439072390",
"config4": "Complete",
"config5": "Complete",
"config6": "5",
"config7": null,
"config8": null,
"config9": null,
"config_selections": [],
"image": null,
"config_toggle": false,
"actions_required": 0
},
{
"id": 3840633,
"type": "twitter_follow",
"worth": 1,
"mandatory": false,
"config1": "gleamapp",
"config2": "0",
"config3": null,
"config4": null,
"config5": null,
"config6": null,
"config7": null,
"config8": null,
"config9": null,
"config_selections": [],
"image": null,
"config_toggle": false,
"actions_required": 0
},
{
"id": 3840634,
"type": "twitter_tweet",
"worth": 2,
"mandatory": false,
"config1": "Want to get your hands on #SuperSmashBrosUltimate and a brand new Nintendo Switch? Then look no further than this awesome @Gleamapp contest ๐",
"config2": "0",
"config3": null,
"config4": null,
"config5": null,
"config6": null,
"config7": null,
"config8": null,
"config9": null,
"config_selections": [],
"image": null,
"config_toggle": false,
"actions_required": 0
},
{
"id": 3840635,
"type": "visit",
"worth": 2,
"mandatory": false,
"config1": "Find Out How to Run Your Own Holiday Giveaway",
"config2": "visit-111177872211",
"config3": "<p>Get an entry when you visit this page:</p>\n<div class='og-widget'>\n<a href='https://gleam.io/stories/adoreme'>\n<img src="https://user-assets.out.sh/asset/2240x1120/adoreme-feature-image.jpg" class="og-widget__image">\n</a>\n<div class='og-widget__wrapper'>\n<div class='og-widget__title'>\n<a href='https://gleam.io/stories/adoreme'>\nRunning The Perfect Holiday Giveaway With Adore Me\n</a>\n</div>\n<div class='og-widget__description'>\n<a href='https://gleam.io/stories/adoreme'>\nTake a look at how Adore Me used giveaways to promote their Valentine's Day product line and capitalize on their peak season.\n</a>\n</div>\n<div class='og-widget__bottom'>\n<div class='og-widget__host'>\n<a href='https://gleam.io/stories/adoreme'>\ngleam.io\n</a>\n</div>\n<div class='og-widget__visit-btn'>\n<a class='btn btn-large visit-bg' href='https://gleam.io/stories/adoreme'>\n<i class='fa fa-external-link-square'></i>\nClick Here\n</a>\n</div>\n</div>\n</div>\n</div>\n",
"config4": "What was your biggest takeaway from the case study?",
"config5": null,
"config6": "open_graph",
"config7": null,
"config8": "{\"source_url\":\"https://gleam.io/stories/adoreme\",\"host\":\"gleam.io\",\"title\":\"Running The Perfect Holiday Giveaway With Adore Me\",\"description\":\"Take a look at how Adore Me used giveaways to promote their Valentine's Day product line and capitalize on their peak season.\",\"images\":[\"https://user-assets.out.sh/asset/2240x1120/adoreme-feature-image.jpg\"],\"videos\":[],\"url\":\"https://gleam.io/stories/adoreme\"}",
"config9": null,
"config_selections": [],
"image": null,
"config_toggle": false,
"actions_required": 0
},
{
"id": 3840636,
"type": "twitter_retweet",
"worth": 1,
"mandatory": false,
"config1": "https://twitter.com/gleamapp/status/1070082654995771392",
"config2": "๐ ๐ SWITCH GIVEAWAY ๐ ๐\n\nOne lucky winner has the chance to win a Nintendo Switch with Super Smash Bros + 5 runnersโฆ https://t.co/sS2cK2CDYS",
"config3": "0",
"config4": null,
"config5": null,
"config6": null,
"config7": null,
"config8": null,
"config9": null,
"config_selections": [],
"image": null,
"config_toggle": false,
"actions_required": 0
},
{
"id": 3840637,
"type": "linkedin_share",
"worth": 2,
"mandatory": false,
"config1": "Share this article on LinkedIn",
"config2": "https://gleam.io/stories/jane",
"config3": "Click the button below to post this awesom guide to your LinkedIn contacts",
"config4": null,
"config5": null,
"config6": null,
"config7": null,
"config8": null,
"config9": null,
"config_selections": [],
"image": null,
"config_toggle": false,
"actions_required": 0
},
{
"id": 3840638,
"type": "share_action",
"worth": 3,
"mandatory": false,
"config1": "Refer 3 Friends For Extra Entries",
"config2": "@Gleamapp is giving away a Nintendo Switch + Super Smash Bros. Ultimate and I want to #win it. Help me out:",
"config3": "Hey,\r\n\r\nAre you excited to play Super Smash Bros. Ultimate?\r\n\r\nThese guys are giving away a free copy, along with a brand new Nintendo Switch to play it on. Want to enter?\r\n\r\n%{link}",
"config4": null,
"config5": null,
"config6": null,
"config7": null,
"config8": null,
"config9": null,
"config_selections": [
"EMAIL",
"FACEBOOK",
"TWITTER",
"WHATSAPP",
"MESSENGER",
"SMS"
],
"image": null,
"config_toggle": false,
"actions_required": 3
},
{
"id": 3840639,
"type": "bonus",
"worth": 20,
"mandatory": false,
"config1": "Get a Bonus 20 Entries For Completing Everything",
"config2": null,
"config3": null,
"config4": null,
"config5": null,
"config6": null,
"config7": null,
"config8": null,
"config9": null,
"config_selections": [],
"image": null,
"config_toggle": false,
"actions_required": 7
}
],
"allowed_countries": null,
"disallowed_countries": null
}
],
"pagination": {
"results": 1,
"page": 1,
"page_size": 20,
"total_pages": 1,
"total_count": 1
}
}
GET https://gleam.io/api/v2/sites/[site_id]/rewards
Parameter | Format | Default | Description |
---|---|---|---|
page | integer | 1 | The page number to display |
per_page | integer | 20 | The number of Rewards returned per page. Maximum of 500. |
Expand
{
"data": [
{
"key": "9Qhyc",
"name": "Tiered Reward Demo",
"created_at": "2018-11-26T02:05:30Z",
"reporting": {
"impressions": 4,
"actions": 2,
"claims": 1,
"users": 1
},
"starts_at": "2018-11-25T13:00:00Z",
"ends_at": null,
"reward": {
"name": "Earn Up to 20% Off Your Order",
"description": "<p>Complete the actions below to progress though the tiers and earn bigger and bigger rewards.<br></p>",
"quantity": 1000,
"images": []
},
"entry_methods": [
{
"id": 3812581,
"type": "facebook_visit",
"worth": 1,
"mandatory": false,
"config1": "https://www.facebook.com/Gleamapp/",
"config2": "Gleam",
"config3": "609377439072390",
"config4": "Complete",
"config5": "Complete",
"config6": "5",
"config7": null,
"config8": null,
"config9": null,
"config_selections": [],
"image": null,
"config_toggle": false,
"actions_required": 0
},
{
"id": 3812582,
"type": "coupon_action",
"worth": 1,
"mandatory": false,
"config1": "Tier 1 - Get 5% Off Your Order",
"config2": "<p>Get 5% off your next purchase with this coupon!</p>",
"config3": "button",
"config4": null,
"config5": null,
"config6": null,
"config7": null,
"config8": null,
"config9": null,
"config_selections": [],
"image": null,
"config_toggle": false,
"actions_required": 1
},
{
"id": 3812583,
"type": "instagram_visit_profile",
"worth": 1,
"mandatory": false,
"config1": "thegyppo",
"config2": "31288554",
"config3": "thegyppo",
"config4": "Stuart McKeown",
"config5": "Complete",
"config6": "5",
"config7": null,
"config8": null,
"config9": null,
"config_selections": [],
"image": null,
"config_toggle": false,
"actions_required": 0
},
{
"id": 3812584,
"type": "coupon_action",
"worth": 1,
"mandatory": false,
"config1": "Tier 2 - Get 10% Off Your Order",
"config2": "<p>Get 10% off your next purchase with this coupon!</p>",
"config3": "button",
"config4": null,
"config5": null,
"config6": null,
"config7": null,
"config8": null,
"config9": null,
"config_selections": [],
"image": null,
"config_toggle": false,
"actions_required": 2
},
{
"id": 3812585,
"type": "youtube_watch",
"worth": 1,
"mandatory": false,
"config1": "Watch a Video",
"config2": "https://youtu.be/nMEHJPuggHQ",
"config3": "nMEHJPuggHQ",
"config4": null,
"config5": null,
"config6": null,
"config7": null,
"config8": null,
"config9": null,
"config_selections": [],
"image": null,
"config_toggle": false,
"actions_required": 0
},
{
"id": 3812586,
"type": "bonus",
"worth": 1,
"mandatory": false,
"config1": "Highest Tier - Get 20% Off Your Order",
"config2": null,
"config3": null,
"config4": null,
"config5": null,
"config6": null,
"config7": null,
"config8": null,
"config9": null,
"config_selections": [],
"image": null,
"config_toggle": false,
"actions_required": 3
}
],
"allowed_countries": null,
"disallowed_countries": null
},
{
"key": "meuAl",
"name": "Spotify Pre-Save Reward",
"created_at": "2018-11-23T00:15:45Z",
"reporting": {
"impressions": 0,
"actions": 0,
"claims": 2
},
"starts_at": "2018-11-22T13:00:00Z",
"ends_at": null,
"reward": {
"name": "Unlock Our Exclusive New Track",
"description": "<p>Pre-Save our upcoming album on Spotify to unlock our exclusive new remix <span style=\"font-size: 18px;\">😎</span></p>",
"quantity": 100000,
"images": [
"https://gleam-prod-user-assets.s3.amazonaws.com/user-assets/579570/TcTkAs7eDRoAtqb9/presave-reward-image.jpg"
]
},
"entry_methods": [
{
"id": 3805910,
"type": "spotify_presave",
"worth": 1,
"mandatory": false,
"config1": "https://open.spotify.com/album/49MNmJhZQewjt06rpwp6QR",
"config2": "Mezzanine",
"config3": "2025-12-31 12:00:00 AM",
"config4": "Melbourne",
"config5": "1542932145",
"config6": null,
"config7": null,
"config8": null,
"config9": null,
"config_selections": [],
"image": null,
"config_toggle": false,
"actions_required": 0
}
],
"allowed_countries": null,
"disallowed_countries": null
}
],
"pagination": {
"results": 2,
"page": 1,
"page_size": 20,
"total_pages": 1,
"total_count": 2
}
}
GET https://gleam.io/api/v2/sites/[site_id]/captures
Parameter | Format | Default | Description |
---|---|---|---|
page | integer | 1 | The page number to display |
per_page | integer | 20 | The number of Captures returned per page. Maximum of 500. |
Expand
{
"data": [
{
"key": "43dEV",
"name": "Embeddable Capture Example",
"created_at": "2018-10-18T08:10:38Z",
"reporting": {
"impressions": 123,
"conversions": 29
}
},
{
"key": "AXW4h",
"name": "Cart Abandonment Demo",
"created_at": "2018-10-17T04:09:52Z",
"reporting": {
"impressions": 312,
"conversions": 184
}
},
],
"pagination": {
"results": 2,
"page": 1,
"page_size": 20,
"total_pages": 1,
"total_count": 2
}
}
See Next Article
Import Entries From CSV Files
Business users have the ability to import actions into their campaigns from CSV files if they have collected entries offline.