Member API
Welcome to the Member API for Marigold EDP/Loyalty.
The Member API allows developers to connect to endpoints relating to data and actions inside Marigold EDP and Loyalty.
Getting Started
Before you create your own connectors or apps using the Member API, get your API client ID and client Secret with your Marigold EDP or Loyalty login You can also download this Postman collection to play around the API using Postman.
Your Marigold EDP/Loyalty server hostname, e.g. https://mycompany.marigold.com, is your base url for all API calls.
Each command that you send through the API is called an endpoint. Each API invocation can be done through HTTPS calls. We have examples of invocation using command line and the command cURL.
Contents Multi-lingual Support
Environment Variable
To enable for offers:export TRANSLATABLES=offer
To enable for offers, rewards and challenges:
export TRANSLATABLES=offer,reward,challenge
Program Settings
Contents refers to Offers, Challenges (Ratings, Multiple Choice and Text surveys, etc), Rewards, Punch cards, Badges, Wallet, etc. When published in Marigold Loyalty marketing console, these contents become available through APIs for members to access, respond, claim or redeem depending on context.
With multi-lingual support, these contents can be presented in different languages on mobile applications, web, or other platforms that consumes Marigold Loyalty APIs. Not all attributes need multi-lingual support, in marketing console this is indicated by globe icon next to the field including those within forms. The most common attributes among contents are Terms of Acceptance Text & Terms of Acceptance URL and those API exposed attributes such as heading, subheading, body, subject, details, action, etc. from the content editor.
Multi-lingual support on contents is disabled by default. This requires environment variable and program settings to enable. Environment variable controls which content will have Multi-lingual Support while the Program Setting controls the default locale and additional locales.
The variable is called TRANSLATABLES and needs to be set on that environment. Checkout examples on enabling multi-lingual support for single content or multiple contents on the right.
The program settings part controls which is the default locale and what other additional locales are supported. Additional locales should be configured to enable multi-lingual support. From this example, default locale is en-US while additional locales are it & ja. This settings can accessed via Content Locales API.
Important: Not all contents in marketing console have multi-lingual support. Please contact customer service which contents have multi-lingual support prior to requesting configuration changes.
Content Locales API
To get content locales JSON settings via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H "Bearer <access_token>"
<base_url>/api/content_locales
Example JSON response:
{
"success": true,
"data": {
"default": "en",
"locales": {
"en": "English",
"it": "Italian",
"ja": "Japanese"
}
}
}
Get <base_url>/api/content_locales
This endpoint returns the current multi-lingual settings in JSON format. locales array contains all the supported locales with the default locale as the first element. The default locale can also be accessed directly on its own attribute.
Important: Any changes made to the program settings takes effect immediately. If a locale is removed from 'Additional Locales', translations for that locale will not be returned via API and the locale tab will be hidden everywhere in Marigold Loyalty marketing console. But the translation records are still in the system.
Request Header
To pass japanese (
ja) Accept-Language header to get a published offer, invoke the followingcURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Accept-Language: ja'
-H "Bearer <access_token>"
<base_url>/api/offers/491
Example JSON response:
{
"success": true,
"data": {
"id": 491,
"internal_name": "ja_test",
"integration_id": null,
"type": "coupon",
"description": null,
"rank": null,
"campaign_id": null,
"campaign_rank": null,
"aggregated_business_value": "0.0",
"start_date": null,
"end_date": null,
"response_start_date": null,
"response_end_date": null,
"response_schedule": null,
"trigger_activity_type": null,
"heading": "テキストを表示する",
"subheading": "テキストを表示する<br>",
"body": "テキストを表示する<br>",
"subject": "テキストを表示する",
"details": "テキストを表示する<br>",
"action": "<button> テキ </button>",
"heading_color": "",
"color": "",
"bgcolor": "",
"heading_bgcolor": "",
"image1_bg": "",
"layout_id": "master",
"sections": {},
"image_url": "https://via.placeholder.com/320x240?text=Click%20to%20change%20Image",
"thumb_image_url": "https://via.placeholder.com/320x240?text=Click%20to%20change%20Image",
"original_image_url": "https://via.placeholder.com/320x240?text=Click%20to%20change%20Image",
"favorited": false,
"respondable": true,
"respondable_info": {
"value": true,
"code": "",
"message": ""
},
"extra_json": {},
"target_url": "https://growingtree.demostellar.com/is?p=JUeyJyZW5kZXJUbyI6IiNzb2NpYWxzaGFyZSIsImltZ1NlbGVjdG9yIjoiLnNob3ctaW1hZ2UgaW1nIiwicHJvZ19pZCI6MSwiY29tcF90eXBlIjoib2ZmZXIiLCJjb21wX2lkIjo0OTEsInRpdGxlIjoiSGVhZGluZyIsImRlc2NyaXB0aW9uIjoiU3ViaGVhZGluZyIsInNpdGVfbmFtZSI6Ikdyb3dpbmcgVHJlZSIsImltZyI6Imh0dHBzOi8vdmlhLnBsYWNlaG9sZGVyLmNvbS8zMjB4MjQwP3RleHQ9Q2xpY2slMjB0byUyMGNoYW5nZSUyMEltYWdlIiwiZnVsbEltZyI6Imh0dHBzOi8vdmlhLnBsYWNlaG9sZGVyLmNvbS8zMjB4MjQwP3RleHQ9Q2xpY2slMjB0byUyMGNoYW5nZSUyMEltYWdlIiwic2hvd19zdG9yeSI6dHJ1ZSwibHBfdHlwZSI6ImZhY2Vib29rIn0=",
"internal_url": "offer://491",
"tracking_code": null,
"metric_amount": "0.0",
"metric_name": "points",
"acceptance_required": false,
"acceptance_text": "用語テキストの受け入れ",
"acceptance_url": "https://www.google.com/lang/ja"
}
}
Make sure all API requests have Accept-Language HTTP header and its value should be one of the locales from Content Locales API. If this is not submitted, the system will return translations based on the default locale.
Member Registration
Sign Up
To create a user via command line, invoke the following
cURLcommand:
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-F "client_id=<client_id>"
-F "client_secret=<client_secret>"
-F "email=<email>"
-F "password=<password>"
-F "password_confirmation=<password_confirmation>"
-F "first_name=<first_name>"
-F "last_name=<last_name>"
<base_url>/api/sign_up
If successful, the response should be:
{
"success" : true
}
Every intent to call the Marigold API starts with having a user.
You can start creating a user via the POST /api/sign_up API endpoint.
HTTP Request
POST <base_url>/api/sign_up
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
Form Parameters
| Parameter | Type | Description |
|---|---|---|
| client_id | string (required) | The app's client ID, found at <base_url>/console/apps and only accessible via admin user only |
| client_secret | string (required) | The app's secret key, verifying that the client ID is in fact a match, also found at <base_url>/console/apps |
| string (required) | The user's email address | |
| password | string (required) | The user's password to be used when logging in |
| password_confirmation | string (required) | Ensure that the password supplied is correct |
| first_name | string (required) | The user's given name |
| last_name | string (required) | The user's surname |
| referral_code | string (optional) | Optional 'referral_code', if provided and valid, will link referral to member that shared the code |
Sign Up without Email
To create a user via command line, invoke the following
cURLcommand:
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-F "client_id=<client_id>"
-F "client_secret=<client_secret>"
-F "password=<password>"
-F "password_confirmation=<password_confirmation>"
-F "first_name=<first_name>"
-F "last_name=<last_name>"
<base_url>/api/sign_up
If successful, the response should be:
{
"success" : true
}
NOTE: This feature is only enabled upon request so please contact your Marigold account manager to request that the ALLOW_SIGNUP_WITHOUT_EMAIL option be enabled in your environment.
Every intent to call the Marigold API starts with having a user.
You can start creating a user via the POST /api/sign_up API endpoint.
HTTP Request
POST <base_url>/api/sign_up
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
Form Parameters
| Parameter | Type | Description |
|---|---|---|
| client_id | string (required) | The app's client ID, found at <base_url>/console/apps and only accessible via admin user only |
| client_secret | string (required) | The app's secret key, verifying that the client ID is in fact a match, also found at <base_url>/console/apps |
| password | string (required) | The user's password to be used when logging in |
| password_confirmation | string (required) | Ensure that the password supplied is correct |
| first_name | string (required) | The user's given name |
| last_name | string (required) | The user's surname |
| referral_code | string (optional) | Optional 'referral_code', if provided and valid, will link referral to member that shared the code |
| string (optional) | The user's email address | |
| mobile_phone | string (optional) | The user's mobile phone number. Login with mobile phone should be set to true if you want to use mobile phone. |
| card_id | string (optional) | The user's card ID |
| username | string (optional) | The user's username |
- Atleast one of member unique identifiers is required . The member unique identifiers are: email, mobile_phone, card_id, and username.
Resend Email Confirmation
To request email confirmation via command line, invoke the following
cURLcommand:
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-F "client_id=<client_id>"
-F "client_secret=<client_secret>"
-F "email=<email>"
<base_url>/api/confirmations
Response will always return true to avoid enumerating emails
{
"success": true,
"data": {
"message": "If your email address exists in our database, you will receive an email with instructions for how to confirm your email address in a few minutes."
}
}
HTTP Request
POST <base_url>/api/confirmations
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
Form Parameters
| Parameter | Type | Description |
|---|---|---|
| client_id | string (required) | The app's client ID, found at <base_url>/console/apps and only accessible via admin user only |
| client_secret | string (required) | The app's secret key, verifying that the client ID is in fact a match, also found at <base_url>/console/apps |
| string (required) | The user's email address |
Request Password Reset Email
To request reset password email, submit one of the following: email, card_id or email_alias. To use email_alias, make sure this env has 'CSR Use Email Alias' enabled in program settings.
To request reset password instructions email via command line, invoke the following
cURLcommand:
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-F "client_id=<client_id>"
-F "client_secret=<client_secret>"
-F "email=<email>"
<base_url>/api/passwords
To request reset password instructions card_id via command line, invoke the following
cURLcommand:
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-F "client_id=<client_id>"
-F "client_secret=<client_secret>"
-F "card_id=<card_id>"
<base_url>/api/passwords
To request reset password instructions email via command line, invoke the following
cURLcommand:
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-F "client_id=<client_id>"
-F "client_secret=<client_secret>"
-F "email_alias=<email_alias>"
<base_url>/api/passwords
Response will always return true to avoid enumerating emails
{
"success": true,
"data": {
"message": "If your email address exists in our database, you will receive a password recovery link at your email address in a few minutes."
}
}
HTTP Request
POST <base_url>/api/passwords
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
Form Parameters
| Parameter | Type | Description |
|---|---|---|
| client_id | string (required) | The app's client ID, found at <base_url>/console/apps and only accessible via admin user only |
| client_secret | string (required) | The app's secret key, verifying that the client ID is in fact a match, also found at <base_url>/console/apps |
& one of
| Parameter | Type | Description |
|---|---|---|
| string (required) | The user's email address, if not using card_id or email_alias | |
| card_id | string (required) | The user's card_id address, if not using email or email_alias |
| email_alias | string (required) | The user's email_alias address, if not using email or card_id |
Reset Password Via Secure Token
To change password using reset_password_token, invoke the following
cURLcommand:
curl -X PUT
-H 'Accept: application/vnd.stellar-v1+json'
-F "client_id=<client_id>"
-F "client_secret=<client_secret>"
-F "reset_password_token=<reset_password_token>"
-F "password=<password>"
-F "password_confirmation=<password_confirmation>"
<base_url>/api/passwords
Returns simple json if changing password is successful. Returns error on failure.
{
"success": true
}
HTTP Request
PUT <base_url>/api/passwords
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
Form Parameters
| Parameter | Type | Description |
|---|---|---|
| client_id | string (required) | The app's client ID, found at <base_url>/console/apps and only accessible via admin user only |
| client_secret | string (required) | The app's secret key, verifying that the client ID is in fact a match, also found at <base_url>/console/apps |
| reset_password_token | string (required) | URL param 'reset_password_token' sent to matching email from Request Password Reset Email |
| password | string (required) | new valid password to set |
| password_confirmation | string (required) | password_confirmation that should match password |
Custom Authentication / Login
For ENV with 'Custom Login Service to use' set in program settings, use the following endpoints to request a reset password email and change password with secure token.
Request Password Reset Email
To request reset password instructions email via command line, invoke the following
cURLcommand:
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-F "client_id=<client_id>"
-F "client_secret=<client_secret>"
-F "email=<email>"
-F "card_id=<card_id>"
-F "birthdate=<birthdate>"
<base_url>/api/passwords/reset
Response will always return true to avoid enumerating emails
{
"success": true,
"data": {
"message": "If your email address exists in our database, you will receive a password recovery link at your email address in a few minutes."
}
}
HTTP Request
POST <base_url>/api/passwords/reset
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
Form Parameters
| Parameter | Type | Description |
|---|---|---|
| client_id | string (required) | The app's client ID, found at <base_url>/console/apps and only accessible via admin user only |
| client_secret | string (required) | The app's secret key, verifying that the client ID is in fact a match, also found at <base_url>/console/apps |
| string (optional) | member's email | |
| card_id | string (optional) | member's card_id |
| birthdate | string (optional) | member's birthdate |
Reset Password Via Secure Token
To change password with reset_password_token via command line, invoke the following
cURLcommand:
curl -X PUT
-H 'Accept: application/vnd.stellar-v1+json'
-F "client_id=<client_id>"
-F "client_secret=<client_secret>"
-F "email=<email>"
-F "reset_password_token=<reset_password_token>"
-F "identify_token=<identify_token>"
-F "new_password=<new_password>"
-F "old_password=<old_password>"
<base_url>/api/passwords/reset
Response JSON on success
{
"success": true
}
HTTP Request
PUT <base_url>/api/passwords/reset
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
Form Parameters
| Parameter | Type | Description |
|---|---|---|
| client_id | string (required) | The app's client ID, found at <base_url>/console/apps and only accessible via admin user only |
| client_secret | string (required) | The app's secret key, verifying that the client ID is in fact a match, also found at <base_url>/console/apps |
| password | string (optional) | member current password |
| new_password | string (optional) | member prefered new password |
| password_confirmation | string (required) | confirm password |
| string (optional) | member's email | |
| card_id | string (optional) | member's card_id |
| old_password | string (optional) | member's old password |
| identify_token | string (optional) | member's token identity |
| reset_password_token | string (optional) | reset password token |
Authentication
After creating a user via Member Registration API endpoint, you can now proceed developing your authentication modules using the following login schemes.
Regular Sign-In
To sign-in via command line, invoke the following
cURLcommand:
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-F "grant_type=password"
-F "client_id=<client_id>"
-F "client_secret=<client_secret>"
-F "email=<email>"
-F "password=<password>"
<base_url>/oauth/token
If successful, the response should look like this:
{
"access_token": "ee83a844eeab8a1eceb862486ccafe6fb908c49316062ad6048dd4d744e5a9cd",
"token_type": "Bearer",
"refresh_token": "95bc8b81535d4569f65b4a35b0efcf7d263ca5c4b4c1d0acbc0b9454b917cf5f",
"created_at": 1540197922,
"settings": {
"send_location_anonymously": false
}
}
Regular sign-in will normally just require either user's email address, member_id or mobile_phone (requires setting update) and password. This is the usual choice, especially when you had the users signing in via web or mobile app.
HTTP Request
POST <base_url>/oauth/token
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
Form Parameters
| Parameter | Type | Description |
|---|---|---|
| grant_type | string (required) | For regular sign-in, this value should be password |
| client_id | string (required) | The app's client ID, found at <base_url>/console/appsand only accessible to admin users only |
| client_secret | string (required) | The app's secret key, verifying that the client ID is in fact a match, also found at <base_url>/console/apps |
| <identifier> | string (required) | Please see list of identifiers below |
| password | string (required) | The user's password |
Identifiers
| Name | Description |
|---|---|
| Email attribute | |
| integration_id | Integration ID attribute |
| member_id | Member ID attribute |
| card_id | Card ID attribute |
| username | The username attribute |
| mobile_phone | Mobile Phone attribute if ProgramSetting.login_with_mobile_phone is enabled |
Revoke
To revoke, invoke the following
cURLcommand:
curl -L '<base_url>/oauth/revoke' \
-H 'Accept: application/vnd.stellar-v1+json' \
-F 'token="21c55a2fbb92405e1816bda4240fdc00002471854d212f096e5ff7f79673392f"' \
-F 'client_id="160039ce1cdb915a6220d9940e8290fcf2974a6cfd13db09164519b6125b4bc9"'
If successful, the response should look like this with a 200 OK HTTP status:
{
}
Up until 24.1.0, revoke will accept the parameter token only. By 24.2.0, revoke will require client_id along with token for security purposes.
HTTP Request
POST <base_url>/oauth/revoke
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
Form Parameters
| Parameter | Type | Description |
|---|---|---|
| client_id | string (required) | The app's client ID, found at <base_url>/console/appsand only accessible to admin users only |
| token | string (required) | The access token to revoke |
Regular Sign-In with MFA
MFA gives an additional layer of security on top of the regular sign-in. When it is enabled (Member API MFA in program settings), an OTP will be sent to the member and they would need to present it to the system for validation in order to receive the access_token. The initial process is the same with the regular sign-in but server will response either with a mfa_required or mfa_channel_required message upon an authenticated regular signin request. Both responses will include a mfa_token which will be used in the succeeding requests. Depending on the response you may need to trigger the mfa challenge endpoint to send the OTP to the member. Once the OTP is received it would be provided by the member and would be included as a payload on mfa_otp grant request to get the access token.
Response definition
mfa_required - An OTP has been sent to the member and it needs to be validated with the mfa_otp grant.
mfa_channel_required - There is more than one channel available for the member thus cannot proceed to send OTP. The channel list would be included in the response for the member to choose. The selected channel will then be a payload for the mfa challenge request which would trigger sending of OTP to the member.
Example of mfa_required response:
{
"code": 4109,
"name": "mfa_required",
"message": "Multifactor authentication required",
"mfa_token": "9c7fb5ce403b42c1d874c830b843d02f",
"challenge": "otp",
"channel": "email"
"otp_expiration": "2022-12-22T02:49:00Z"
}
Example of mfa_channel_required response:
{
"code": 4110,
"name": "mfa_channel_required",
"message": "Multifactor authentication channel required",
"mfa_token": "dc3759be251b5b2b7b8a90ed81c96e7e",
"channels": [
"sms",
"email"
]
}
mfa_otp grant
mfa_otp grant request using
cURLcommand:
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-F "grant_type=mfa_otp"
-F "client_id=<client_id>"
-F "client_secret=<client_secret>"
-F "mfa_token=<mfa_token>"
-F "otp=<otp>"
<base_url>/oauth/token
If successful, the response should look like this:
{
"access_token": "ee83a844eeab8a1eceb862486ccafe6fb908c49316062ad6048dd4d744e5a9cd",
"token_type": "Bearer",
"refresh_token": "95bc8b81535d4569f65b4a35b0efcf7d263ca5c4b4c1d0acbc0b9454b917cf5f",
"created_at": 1540197922,
"settings": {
"send_location_anonymously": false
}
}
If mfa_token is invalid, the response should look like this:
{
"code": 4108,
"name": "invalid_mfa_token_error",
"message": "Invalid MFA Token"
}
If otp is invalid, the response should look like this:
{
"code": 4107,
"name": "invalid_otp",
"message": "Invalid One Time Password"
}
After sending OTP to the member either via the login endpoint (with mfa_required response) or mfa challenge endpoint, a post request for the mfa otp grant must be sent in order to verify the OTP from the member and provide the access token.
HTTP Request
POST <base_url>/oauth/token
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
Form Parameters
| Parameter | Type | Description |
|---|---|---|
| grant_type | string (required) | Grant type for auth request. Must be set to mfa_otp |
| client_id | string (required) | The app's client ID, found at <base_url>/console/appsand only accessible to admin users only |
| client_secret | string (required) | The app's secret key, verifying that the client ID is in fact a match, also found at <base_url>/console/apps |
| mfa_token | string (required) | The token received from the initial login's mfa_required or mfa_channel_required response |
| otp | string (required) | The OTP that was sent to the member |
MFA Challenge
MFA Challenge request using
cURLcommand:
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-F "channel=<channel>"
-F "mfa_token=<mfa_token>"
<base_url>/mfa/challenge
If successful, the OTP would be sent to the member and the response should look like this:
{
"success": true,
"data": {
"challenge": "otp",
"mfa_token": "d412b6d3562e3003eefddfbe17a67650",
"channel": "email",
"otp_expiration": "2023-01-12T10:40:30Z"
}
}
If mfa_token is invalid, the response should look like this:
{
"code": 4108,
"name": "invalid_mfa_token_error",
"message": "Invalid MFA Token"
}
If passed channel is not one of the valid channels for the member, the response should look like this:
{
"code": 4111,
"name": "invalid_mfa_channel",
"message": "Invalid multifactor authentication channel",
"mfa_token": "8871eb2116ebd469f5879c52214984d9",
"channel": "snailmail",
"channels": [
"email",
"sms"
]
}
This endpoint provides the ability to send or resend the OTP to the member through a specified channel. Common usage would be when a mfa_channel_required is received from the server.
HTTP Request
POST <base_url>/mfa/challenge
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
Form Parameters
| Parameter | Type | Description |
|---|---|---|
| mfa_token | string (required) | The token received from the initial login's mfa_required or mfa_channel_required response |
| channel | string (required) | The communication channel on which the OTP would be send through |
Sign-In via Social Networking Sites
To sign-in via command line, invoke the following
cURLcommand:
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-F "grant_type=assertion"
-F "client_id=<client_id>"
-F "client_secret=<client_secret>"
-F "provider=<provider>"
-F "assertion=<assertion>"
<base_url>/oauth/token
If successful, the response should look like this:
{
"access_token": "40e4726e5263ce266058c04494d4385f36530d233ef0bc363e92b2c969ff57a9",
"token_type": "bearer",
"expires_in": 7200,
"refresh_token": "5d0c438a28d62466ef70154bf15a6cc185e0e884b06d76fbf176ff86a55860c5",
"created_at": 1444027150
}
Sometimes, it's too cumbersome for users to enter their emails or passwords, that's why most apps integrate into them some form of social media authentication. Luckily, the Marigold API allows this authentication via the assertion grant type.
HTTP Request
POST <base_url>/oauth/token
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
Form Parameters
| Parameter | Type | Description |
|---|---|---|
| grant_type | string (required) | For the social login, this value should be assertion |
| client_id | string (required) | The app's client ID, found at <base_url>/console/appsand only accessible to admin users only |
| client_secret | string (required) | The app's secret key, verifying that the client ID is in fact a match, also found at <base_url>/console/apps |
| provider | string (required) | The social media type. Values can be facebook, twitter, google or instagram |
| assertion | string (required) | The access token gathered from integrating the social media's login API |
| mode | string (optional) | Accepts either sign_in or sign_up. 'sign_in' means to login an existing account. 'sign_up' means to register a new account. |
Note: Twitter token has two parts, token and secret. To make it work same as other provider, it should be joined by a colon :, i.e. token is 5193411975-2VkFr012k3roT65staVsKL9o0yTmo9JHuMl2l, then secret is 3BbnqcSzl3cEmWGWXtiwefwelfweiZIsevi9bj3YPfYFVcjYn, build the assertion value like this 5193411975-2VkFr012k3roT65staVsKL9o0yTmo9JHuMl2l:3BbnqcSzl3cEmWGWXtiwefwelfweiZIsevi9bj3YPfYFVcjYn, notice the colon in the middle.
Refresh an Access Token
To refresh an access token via command line, invoke the following
cURLcommand:
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-F "grant_type=refresh_token"
-F "client_id=<client_id>"
-F "client_secret=<client_secret>"
-F "refresh_token=<refresh_token>"
<base_url>/oauth/token
If successful, the response should look like this:
{
"access_token": "e9a6be80243f0c653904614f1f769c9fe90652223d040a3a9cc742f624624ce8",
"token_type": "Bearer",
"refresh_token": "d7b7a6bd8dfc79f183ddbac72bc1442a6a1de34413c93c68782ebce037ef4198",
"created_at": 1540198375,
"settings": {
"send_location_anonymously": false
}
}
After logging in and securing an access token from the authentication APIs, the default behavior is that the access token gathered will expire in 7200 seconds (approximately 2 hours). If the user needs to still be able to access the API endpoints after the 2-hour period, there's no need for another login. All the app needs to do is connect to the access token refresh endpoint.
HTTP Request
POST <base_url>/oauth/token
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
Form Parameters
| Parameter | Type | Description |
|---|---|---|
| grant_type | string (required) | For refreshing token, this value should be refresh_token |
| client_id | string (required) | The app's client ID, found at <base_url>/console/appsand only accessible to admin users only |
| client_secret | string (required) | The app's secret key, verifying that the client ID is in fact a match, also found at <base_url>/console/apps |
| refresh_token | string (required) | The refresh_token value gathered from earlier logins or token refreshes |
Authenticated Request
Example of passing access_token via Authorization header
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/places
Example of passing access_token via URL Parameter
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/places
Passing access_token returned from a successful Sign-in or Sign-In via Social Networking Sites to succeeding API calls can be done in two ways:
- As Authorization Bearer
- As URL parameter [DEPRECATED]
We recommend using Authorization Bearer because HTTP headers are not easily exposed within a network traffic, especially in an unsecure public WIFI. Please make sure to use either 1 or 2, never both both at the same API call.
JWT via Authorization Header
To access any member API using JWT as access_token, add HTTP Authorization Bearer header to your
cURLcommand:
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-H 'client_id: <client_id>'
-H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImxpTUZRV1Fqc1dTdGl5RkFKV1VZR1c2YkNkZVdkM1hWUFVOcXI3V1BOZGMifQ.eyJzdWIiOiJjYmVhZjE1My1kMzdlLTQ3NDYtYjQ4Yi0yYzc0MjY0OGNiMGEiLCJlbWFpbCI6ImZiQHNwcmludGluZy5pbyIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJnaWd5YV91aWQiOiI5NzQzOGUwMTQ1MjM0ZjdjYjY4MDE1MGY2YjM1MDc5ZiIsInRlbmFudElkIjozLCJmYWNlYm9va19pZCI6IjEwOTA2ODIxNjk1ODgzMCIsImZhbWlseV9uYW1lIjoiSGFuc2VyIiwiZ2l2ZW5fbmFtZSI6IlBldGVyIiwibmlja25hbWUiOiJQZXRlciBIYW5zZXIiLCJwaWN0dXJlIjoiaHR0cHM6Ly9ncmFwaC5mYWNlYm9vay5jb20vdjIuMTIvMTA5MDY4MjE2OTU4ODMwL3BpY3R1cmU_dHlwZT1sYXJnZSIsImZpcnN0VGltZVNpZ251cCI6ZmFsc2UsImF1dGhfdGltZSI6MTU3MzE0MDg1OSwibm9uY2UiOiJwbGVhc2Utc2VuZC1ub25jZSIsInNpZCI6ImQxNDJiMGNjLTBhN2QtNGFkZi1hNWVjLTFjZTg2NmY3MDJiZCIsImF1ZCI6ImN1c3RvbWVyLXByb2dyYW0iLCJleHAiOjQ3MjY3NDA4NTksImlhdCI6MTU3MzE0MDg1OSwiaXNzIjoiaHR0cHM6Ly90LWlkcC5kc2dhcHBzLmRrIn0.GFFEW7BsCQgLH9er3boVDboaLQuFFazn4HPxydZAtsqscF3bnOGPYQjnHH0Z24TU3JYmESa0nFgJszka3MaLJF1JNSPtsHVVtDjvtaZPbdKwqXO3DNzSaATRr4glBEAs4VeaO553dHJ4d3ALqrltWcCiGwHp1oaw4W0WgAoqn0xSmdawjS2HIO1bBc0rO7Ynf8IDfbc7Q8Vb9x4WEfab-sTCegK3sm8naCqIj38goUw_jXuh_Z7U9RVeax5C63vc4sx0LZqiUIJCbSMFKMevT2ChSwYaeP0SQr2FQUWmv7kqfCYIXj-Yxk4GYkaOVi3ZVahRSTvxiYU9RBh88P5Iow'
<base_url>/api/challenges/<id>/respond
Successful JSON response based on which endpoint is called, i.e. challenges/<id>/respond
{
"success": true,
"data": {
"challenge_response": {
"id": 1,
"status": "approved"
},
"challenge_respondable": true,
"secondary_prize": {
"amount": "99.0",
"metric": {
"id": 5,
"name": "point",
"label": "Point",
"description": "",
"type": "Point",
"decimal_place": 0,
"code": "Pw",
"expirable": false
}
}
}
}
JSON response when JWT expired
{
"code": 4002,
"name": "expired_token",
"message": "Access token is expired"
}
JSON response when JWT cannot be decoded
{
"code": 4001,
"name": "invalid_token",
"message": "Access token is invalid"
}
JSON response when JWT decoding succeeded but no member was loaded
{
"code": 4104,
"name": "jwt_member_missing",
"message": "JWT linked member missing"
}
Member APIs accepts signed JWT by an external server provided the public key is configured in one or more Oauth Applications with member scope in Marketing Console.
JWT is read from HTTP Authorization Bearer including the custom client_id header. See cURL example:
Configure JWT Settings in Oauth Applications page
- Go to <base_url>/console/apps, and create or select an existing Oauth Application with a member scope. Click on 'Advanced' > 'Edit' on JWT Settings section. Paste the JWT public key provided by the external server that will sign the JWT. Public key can be in a form of JWK (JSON Web Keys) or RSA key. See JWT for more info. Include client_id of selected Oauth Application in HTTP headers.
- In the JWT integration key field, enter name of JWT attribute where existing member's integration_id will be read. Confirm with external JWT signer documentation that this field contains the member integration_id.
- Select from Lookup Attribute options which member field matches integration key from step 2. Usually this is integration_id. Other options are listed below.
Lookup Attribute options
- member_id
- username
- card_id
- mobile_phone
- integration_id
- integration2_id
- integration3_id
- integration4_id
- integration5_id
- integration6_id
- integration7_id
- integration8_id
- integration9_id
- integration10_id
- integration11_id
Oauth2 + PKCE Token Exchange
This API document describes how to exchange the returned authorization code for an access token using the {{client_url}}/oauth/token API endpoint. This is the second step of the OAuth2 Authorization Code + PKCE flow
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
Form Parameters
| Parameter | Type | Description |
|---|---|---|
| grant_type | string (required) | The OAuth2 grant type, set to "authorization_code" for Authorization Code + PKCE flow. |
| client_id | string (required) | The app's client ID, found at <base_url>/console/appsand only accessible to admin users only |
| code | string (required) | The authorization code received from the previous step. |
| code_verifier | string (required) | The original code verifier that was used to create the code challenge sent in the first step. |
| redirect_uri | string (required) | The URI to which the user was redirected after authorization. It must match the redirect_uri used in the first step. |
To sign-in via command line, invoke the following
cURLcommand:
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-F "grant_type=authorization_code"
-F "client_id=<client_id>"
-F "code=<code>"
-F "code_verifier=<code_verifier>"
-F "redirect_uri=<redirect_uri>"
<base_url>/oauth/token
If successful, the response should look like this:
{
"access_token": "40e4726e5263ce266058c04494d4385f36530d233ef0bc363e92b2c969ff57a9",
"token_type": "bearer",
"expires_in": 7200,
"refresh_token": "5d0c438a28d62466ef70154bf15a6cc185e0e884b06d76fbf176ff86a55860c5",
"created_at": 1444027150
}
Oauth2 Identity Provider
Marigold as Oauth2 Identity Provider follows OAuth 2.0 Authorization Framework. Below are the steps to configure your environment to serve as Oauth2 Identity Provider.
Setup your application
Go to <base_url>/console/apps, and create your Oauth Application. In this example, 'growingtree.demostellar.com' is your base url.
Define callback URL to Oauth2 consumer. Here, it points to https://myapphost.com/users/auth/marigold/callback
Leave the rest of the fields as is.Copy client_id & client_secret from Oauth Application detail page. This will serve as your
MARIGOLD_APP_IDandMARIGOLD_APP_SECRETcredential keys to be installed in your Oauth (Consumer) Resource server. Click on 'Show secret' button to reveal the secret key.
Authorization URL
Marigold Authorization URL is at <base_url>/oauth/authorize. Check OAuth 2.0 Authorization Framework for documentation.
Authorization URL + PKCE Flow API
Example cUrl comamnd using the Marigold Authorization URL + PKCE
curl -X GET
<base_url>/oauth/authorize
Example cURL command using query parameter:
curl -X GET
<base_url>/oauth/authorize?response_type=code&code_challenge=<your_code_challenge>&code_challenge_method=S256&state=<your_state>&redirect_uri=<your_redirect_uri>&client_id=<your_client_id>&scope=member
Example Response
HTTP/1.1 302 Found
Location: https://client.example.com/callback?code=<returned_code>&state=<returned_state>
This API document describes how to implement the OAuth2 Authorization Code + PKCE flow using the <base_url>/oauth/authorize API endpoint.
he PKCE flow is required for applications like desktop and mobile apps that can’t securely store a client secret.
HTTP Request
GET <base_url>/oauth/authorize
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| response_type | string (required) | The OAuth2 response type, set to "code" for Authorization Code + PKCE flow. |
| code_challenge | string (required) | Created by performing a SHA256 hash on the code verifier and then Base64url encoding the hash e.g. code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier))) |
| code_challenge_method | string (required) | The method used to generate the code challenge, set to "S256" for the SHA-256 hashing algorithm. |
| state | string (optional) | A unique string value to maintain state between the request and callback, used to prevent CSRF attacks. |
| redirect_uri | string (required) | The URI to which the user will be redirected after authorization. It must be pre-registered and associated with the client_id. |
| client_id | string (required) | The unique identifier of the client application that is requesting authorization. |
| scope | string (required) | A space-separated list of permissions that the application is requesting. For this implementation, set to "member". |
Generating a code verifier and code challenge
The code_hallenge is created by performing a SHA256 hash on the code verifier and then Base64url encoding the hash e.g.
code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))
The main difference beween an Authorizatio nGrant Type and the PKCE Grant, is that the PKCE Grant does not have Client Secret. It instead uses a Code Verifier and Code Challenge.
As you can't currently generate these code easily in Postman at the moment, you can use the following online tool to generate them for you: Online PKCE Generator Tool
- Enter the code verifier into the first box
- A code verifier is a random string between 43 and 128 characters long that consists of the characters A-Z, a-z, 0-9, and the punctuation
-._~(hyphen, period, underscore, and tilde). - Click
Generate Code Challenge - Copy out the Code Challenge and post it into the Params tab of the Get Authorization Call
Success Response
The user will be redirected to the redirect_uri with the following parameters in the query string:
| Parameter | Type | Description |
|---|---|---|
| code | string | The authorization code generated by the authorization server, to be used to request an access token. |
| state | string | (if you provided one). The same unique string value sent in the initial request, used to prevent CSRF attacks. |
Identity URL
Example cURL command using Authorization Bearer:
curl -X GET
-H 'Authorization: Bearer <access_token>'
<base_url>/api/v1/me
Example cURL command using query parameter:
curl -X GET
<base_url>/api/v1/me?access_token=<access_token>
Example JSON response
{
"provider": "marigold",
"uid": "A-000000001",
"info": {
"name": "Maddison Hilpert",
"email": "darrion1@white.com",
"first_name": "Maddison",
"last_name": "Hilpert",
"nickname": "oauth2_user1",
"image": "",
"mobile_phone": "+13878271628",
"payments": []
},
"extra": {
"raw_info": {
"member": {
"first_name": "Maddison",
"last_name": "Hilpert",
"member_id": "G-000000001",
"member_since": "2019-11-07T06:29:12.046Z",
"referred": false,
"visitor": false,
"locale_code": "en-US"
},
"tier": {
"current_tier": {
"name": "Foo",
"label": "Foo",
"expiration_date": ""
},
"tier_in_progression": "Bar",
"primary_metric_name": "null",
"metrics": [],
"expressions_exist": false,
"tiers": []
},
"metrics": {
"points": {
"label": "Points",
"redeem_total": "0",
"balance": "0",
"life_time": "0",
"last_12mo": "0",
"ytd": "0",
"last_30d": "0",
"mtd": "0",
"today": "0"
}
},
"member_badges": [],
"permissions": "null",
"address_verification_enabled": false
}
}
}
Marigold Member's Identity URL is at <base_url>/api/v1/me.json
This endpoint is queried immediately upon successful authorization callback and stored in request.env["omniauth.auth"] hash. The raw_info node is the same as data node from Account Summary endpoint.
HTTP Request
GET <base_url>/api/v1/me.json
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
Member Profile
To get member profile via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/profile
Member profile information.
HTTP Request
GET <base_url>/api/profile
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| include_segments | boolean (optional) | Include current member eligible segments. Default is false. |
If successful, the response should look like this:
{
"success": true,
"data": {
"email": "chuck@norris.com",
"email_alias": "",
"username": "chucknorris",
"first_name": "Chuck",
"last_name": "Norris",
"mailing_street": "Amethyst",
"mailing_street2": "Road",
"mailing_city": "San Mateo",
"mailing_state": "California",
"mailing_postal_code": "55443",
"mailing_country": "US",
"birthdate": "2000-02-14",
"mobile_phone": "1373849023",
"member_since": "2014-07-13T08:34:48.000Z",
"member_id": "A-0000002",
"receive_sms_offers": false,
"receive_mobile_app_offers": false,
"receive_mail_offers": false,
"receive_e_statements": false,
"current_tier": "Cadet",
"expiration_date": "2016-12-31",
"tier_in_progression": "Private",
"referrer_id": "A-0000001",
"integration_id": "",
"integration2_id": "",
"integration3_id": "",
"integration4_id": "",
"integration5_id": "",
"integration6_id": "",
"gender": "",
"marital_status": "",
"education": "",
"income": "",
"has_children": "",
"employment": "",
"employee": false,
"ethnicity": "",
"housing": "",
"test_member": false,
"visitor": "",
"card_id": "",
"receive_newsfeed_like_notification": true,
"receive_newsfeed_comment_notification": true,
"company": "",
"receive_personalized_offers": true,
"receive_statements": "Monthly",
"place_integration_id": "",
"region_integration_id": "",
"migrated": "",
"locale_code": "en-CA",
"avatar_url": "",
"place_label": ""
}
}
Account Summary
To get member account summary via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
-F "include_dependent_metrics=<include_dependent_metrics>"
<base_url>/api/summary
If successful and include_dependent_metrics parameter is not set or set to false, the response should look like this:
{
"success": true,
"data": {
"member": {
"first_name": "Cory",
"last_name": "Altenwerth",
"member_id": "A-0000002",
"member_since": "2015-06-22T00:00:00.000Z",
"referred": false,
"visitor": false,
"locale_code": "en-US",
"confirmed_at": "null",
"email_confirmation_required": true
},
"tier": {
"current_tier": {
"name": "cadet",
"label": "Cadet",
"expiration_date": "2016-12-31"
},
"tier_in_progression": "Cadet",
"primary_metric_name": "point",
"metrics": [
"point"
],
"expressions_exist": false,
"tiers": [
{
"name": "cadet",
"label": "Cadet",
"description": "",
"metric_thresholds": {
"point": 0
}
},
{
"name": "private",
"label": "Private",
"description": "",
"metric_thresholds": {
"point": 2500
}
}
]
},
"metrics": {
"point": {
"label": "Point",
"balance": "10393",
"life_time": "10428",
"last_12mo": "10428",
"ytd": "10428",
"last_30d": "10428",
"mtd": "10428",
"today": "0",
"redeem_total": "35"
},
"spend": {
"label": "Spend",
"balance": "0.0",
"life_time": "0.0",
"last_12mo": "0.0",
"ytd": "0.0",
"last_30d": "0.0",
"mtd": "0.0",
"today": "0.0",
"redeem_total": "0.0"
}
},
"metric_expiration": {
"Last Activity Title": {
"point":{
"next_expiration_date":"2024-02-07T00:00:00.000Z",
"expiring_metric_value":800,
"days_to_expiration": 320
},
"spend":{
"next_expiration_date":"2024-02-07T00:00:00.000Z",
"expiring_metric_value":800,
"days_to_expiration": 320
}
}
},
"member_badges": [
],
"permissions": "null",
"address_verification_enabled": false
}
}
If include_dependent_metrics is set to true, response would look like this:
{
"success": true,
"data": {
"member": {
"first_name": "Chuck",
"last_name": "Norris",
"member_id": "A-0000002",
"member_since": "2015-06-22T00:00:00.000Z"
},
"tier": {
"current_tier": {
"name": "cadet",
"label": "Cadet",
"expiration_date": "2016-12-31"
},
"tier_in_progression": "Cadet",
"primary_metric_name": "point",
"metrics": [
"point"
],
"expressions_exist": false,
"tiers": [
{
"name": "cadet",
"label": "Cadet",
"description": "",
"metric_thresholds": {
"point": 0
}
},
{
"name": "private",
"label": "Private",
"description": "",
"metric_thresholds": {
"point": 2500
}
}
]
},
"metrics": {
"point": {
"label": "Point",
"balance": "10393",
"life_time": "10428",
"last_12mo": "10428",
"ytd": "10428",
"last_30d": "10428",
"mtd": "10428",
"today": "0",
"redeem_total": "35"
},
"spend": {
"label": "Spend",
"balance": "0.0",
"life_time": "0.0",
"last_12mo": "0.0",
"ytd": "0.0",
"last_30d": "0.0",
"mtd": "0.0",
"today": "0.0",
"redeem_total": "0.0"
}
},
"aggregate_metrics": {
"created_at": "2017-09-18T04:54:26.471Z",
"slMetrics": {
"Balance": {},
"Redeem": {},
"Earn": {},
"PrevBalance": {},
"Expired": {}
}
},
"child_summary": [
{
"member": {
"first_name": "FirstName7",
"last_name": "LastName7",
"member_since": "2017-09-12T00:00:00.000Z",
"visitor": false,
"member_id": "MICHAELSIMACLOCAL-000000357"
},
"tier_result": {
"created_at": "2017-09-18T04:54:26.406Z",
"tier": "base",
"expiration_date": "2017-12-31T00:00:00.000Z",
"tier_in_progression": "base"
},
"sl_metrics_aggregate_result": {
"created_at": "2017-09-18T04:54:26.406Z",
"slMetrics": {
"Balance": {
"spend": {
"label": "spend",
"balance": "0.0",
"life_time": "0.0",
"last_12mo": "0.0",
"ytd": "0.0",
"last_30d": "0.0",
"mtd": "0.0",
"today": "0.0"
},
"star": {
"label": "star",
"balance": "0",
"life_time": "0",
"last_12mo": "0",
"ytd": "0",
"last_30d": "0",
"mtd": "0",
"today": "0"
},
"points": {
"label": "points",
"balance": "0",
"life_time": "0",
"last_12mo": "0",
"ytd": "0",
"last_30d": "0",
"mtd": "0",
"today": "0"
}
},
"Redeem": {
"spend": {
"label": "spend",
"balance": "0.0",
"life_time": "0.0",
"last_12mo": "0.0",
"ytd": "0.0",
"last_30d": "0.0",
"mtd": "0.0",
"today": "0.0"
},
"star": {
"label": "star",
"balance": "0",
"life_time": "0",
"last_12mo": "0",
"ytd": "0",
"last_30d": "0",
"mtd": "0",
"today": "0"
},
"points": {
"label": "points",
"balance": "0",
"life_time": "0",
"last_12mo": "0",
"ytd": "0",
"last_30d": "0",
"mtd": "0",
"today": "0"
}
},
"Earn": {
"spend": {
"label": "spend",
"balance": "0.0",
"life_time": "0.0",
"last_12mo": "0.0",
"ytd": "0.0",
"last_30d": "0.0",
"mtd": "0.0",
"today": "0.0"
},
"star": {
"label": "star",
"balance": "0",
"life_time": "0",
"last_12mo": "0",
"ytd": "0",
"last_30d": "0",
"mtd": "0",
"today": "0"
},
"points": {
"label": "points",
"balance": "0",
"life_time": "0",
"last_12mo": "0",
"ytd": "0",
"last_30d": "0",
"mtd": "0",
"today": "0"
}
},
"PrevBalance": {
"spend": {
"label": "spend",
"balance": "0.0",
"life_time": "0.0",
"last_12mo": "0.0",
"ytd": "0.0",
"last_30d": "0.0",
"mtd": "0.0",
"today": "0.0"
},
"star": {
"label": "star",
"balance": "0",
"life_time": "0",
"last_12mo": "0",
"ytd": "0",
"last_30d": "0",
"mtd": "0",
"today": "0"
},
"points": {
"label": "points",
"balance": "0",
"life_time": "0",
"last_12mo": "0",
"ytd": "0",
"last_30d": "0",
"mtd": "0",
"today": "0"
}
},
"Expired": {
"spend": {
"label": "spend",
"balance": "0.0",
"life_time": "0.0",
"last_12mo": "0.0",
"ytd": "0.0",
"last_30d": "0.0",
"mtd": "0.0",
"today": "0.0"
},
"star": {
"label": "star",
"balance": "0",
"life_time": "0",
"last_12mo": "0",
"ytd": "0",
"last_30d": "0",
"mtd": "0",
"today": "0"
},
"points": {
"label": "points",
"balance": "0",
"life_time": "0",
"last_12mo": "0",
"ytd": "0",
"last_30d": "0",
"mtd": "0",
"today": "0"
}
}
}
}
}
]
}
}
Member account summary information.
HTTP Request
GET <base_url>/api/summary
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| include_dependent_metrics | boolean (optional) | This would determine if child member info will be included |
Account Pipeline Summary
To get member account summary via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/cw/summary
If successful, the response should look like this:
{
"success": true,
"data": {
"member": {
"first_name": "Chuck",
"last_name": "Norris",
"member_id": "A-0000002",
"card_id": "null",
"mobile": 6501987654,
"member_since": "2015-06-22T00:00:00.000Z"
},
"progress": {
"tours_completed": 0,
"tours_completed_credit": 1,
"wbt_credits": 88,
"wbt_next_threshold": 100,
"wbt_next_reward": "$15 OC Cash Reward",
"points": 20,
"points_next_threshold": 75,
"points_next_reward": "$5 OC Cash"
},
"rewards": [
{
"name": "Free Appetizer",
"description": "Welcome reward - free appetizer upto $12",
"start_date": "2017-04-01T00:00:00.000Z",
"end_date": "2017-04-01T00:00:00.000Z",
"category": "food",
"balance": "null",
"image_url": "https://s3.../contents/images/000/005/399/standard/__35.JPG?1449109087",
"thumb_image_url": "https://s3.../contents/images/000/005/399/thumb/__35.JPG?1449109087"
},
{
"name": "$5 OC Cash",
"description": "$5 OC Cash \"reward\" that has to be used in one go (balance does not carry forward)",
"start_date": "2017-04-01T00:00:00.000Z",
"end_date": "2017-04-01T00:00:00.000Z",
"category": "oc_cash",
"balance": "null",
"image_url": "https://s3.../contents/images/000/005/399/standard/__35.JPG?1449109087",
"thumb_image_url": "https://s3.../contents/images/000/005/399/thumb/__35.JPG?1449109087"
},
{
"name": "$15 OC Cash Reward",
"description": "some description",
"start_date": "2017-04-01T00:00:00.000Z",
"end_date": "2017-04-01T00:00:00.000Z",
"category": "oc_cash_reward_1",
"balance": 10.75,
"image_url": "https://s3.../contents/images/000/005/399/standard/__35.JPG?1449109087",
"thumb_image_url": "https://s3.../contents/images/000/005/399/thumb/__35.JPG?1449109087"
},
{
"name": "$25 OC Cash Reward",
"description": "some description",
"start_date": "2017-04-01T00:00:00.000Z",
"end_date": "2017-04-01T00:00:00.000Z",
"category": "oc_cash_reward_2",
"balance": 25,
"image_url": "https://s3.../contents/images/000/005/399/standard/__35.JPG?1449109087",
"thumb_image_url": "https://s3.../contents/images/000/005/399/thumb/__35.JPG?1449109087"
}
],
"punchcards": [
{
"name": "Tour 1 to 10 - Recognition",
"description": "some description",
"start_date": "null",
"end_date": "null",
"category": "wbt_recognition",
"required_punches": 110,
"num_punches": 3,
"punches": [
"9901",
"9902",
"9903"
],
"image_url": "https://s3.../contents/images/000/005/399/standard/__35.JPG?1449109087",
"thumb_image_url": "https://s3.../contents/images/000/005/399/thumb/__35.JPG?1449109087"
},
{
"name": "Tour 2 Plus Credit",
"description": "some description",
"start_date": "null",
"end_date": "null",
"category": "wbt_credit",
"required_punches": 110,
"num_punches": 3,
"punches": "null",
"image_url": "https://s3.../contents/images/000/005/399/standard/__35.JPG?1449109087",
"thumb_image_url": "https://s3.../contents/images/000/005/399/thumb/__35.JPG?1449109087"
},
{
"name": "Summer Mini Tour",
"description": "some description",
"start_date": "2017-05-01T00:00:00.000Z",
"end_date": "2017-05-31T00:00:00.000Z",
"category": "minitours",
"required_punches": 10,
"num_punches": 2,
"punches": [
"9902",
"9903"
],
"image_url": "https://s3.../contents/images/000/005/399/standard/__35.JPG?1449109087",
"thumb_image_url": "https://s3.../contents/images/000/005/399/thumb/__35.JPG?1449109087"
}
]
}
}
Member pipeline account summary information.
HTTP Request
GET <base_url>/api/cw/summary
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
Profile Metadata
To get profile metadata via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/profile/describe
Member profile metadata information.
HTTP Request
GET <base_url>/api/profile/describe
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
If successful, the response should look like this:
{
"success": true,
"data": [
{
"name": "email",
"label": "Email",
"description": "",
"type": "Email",
"default": "",
"read_only": true,
"required": false,
"categories": [],
"is_static": false,
"condition": ""
},
{
"name": "username",
"label": "Username",
"description": "",
"type": "String",
"default": "",
"read_only": true,
"required": false,
"categories": [],
"is_static": false,
"condition": ""
},
{
"name": "first_name",
"label": "First Name",
"description": "",
"type": "String",
"default": "",
"read_only": false,
"required": false,
"categories": [],
"is_static": false,
"condition": ""
},
{
"name": "last_name",
"label": "Last Name",
"description": "",
"type": "String",
"default": "",
"read_only": false,
"required": false,
"categories": [],
"is_static": false,
"condition": ""
},
{
"name": "mobile_phone",
"label": "Mobile Phone",
"description": "null",
"type": "Phone",
"default": "",
"read_only": false,
"required": false,
"categories": [],
"is_static": false,
"condition": "",
"phone_country_codes": {
"US": {
"prefix": "1",
"label": "(+1) United States"
},
"PH": {
"prefix": "63",
"label": "(+63) Philippines"
}
}
},
{
"name": "gender",
"label": "Gender",
"description": "",
"type": "String",
"default": "",
"read_only": false,
"domain": {
"list": [
{
"m": "Male"
},
{
"f": "Female"
},
{
"d": "Decline"
}
]
}
},
{
"name": "mailing_country",
"label": "Mailing Country",
"description": "",
"type": "String",
"default": "",
"read_only": false,
"domain": {
"list": [
{
"AD": "Andorra"
},
{
"ZW": "Zimbabwe"
}
]
}
}
]
}
Update Profile
To update a string profile attribute
first_namevia command line, invoke the followingcURLcommand:
curl -X PUT
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
-F "first_name=<first_name>"
<base_url>/api/profile
To update a boolean profile attribute
receive_e_statementsvia command line, invoke the followingcURLcommand:
curl -X PUT
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
-F "receive_e_statements=<receive_e_statements>"
<base_url>/api/profile
If successful, the response should be:
{
"success": true,
"data": {
"member_attributes": [
{
"sl_attribute": "first_name",
"sl_attribute_value": "Elvis",
"sl_prev_value": "Chuck"
},
{
"sl_attribute": "last_name",
"sl_attribute_value": "Potter",
"sl_prev_value": "Norris"
}
]
}
}
Allows the user to update profile.
HTTP Request
PUT <base_url>/api/profile
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
Form Parameters
| Parameter | Type | Description |
|---|---|---|
| first_name | string (optional but not blank) | Member's first name |
| last_name | string (optional but not blank) | Member's last name |
| mailing_street | string (optional but not blank) | Member's street address |
| mailing_city | string (optional but not blank) | Member's city address |
| mailing_state | string (optional but not blank) | Member's state address |
| mailing_postal_code | string (optional but not blank) | Member's postal code address |
| mailing_country | string (optional but not blank) | Member's mailing country |
| birthdate | date (optional but not blank) | Member's date of birth in the format '2006-02-14' |
| mobile_phone | string (optional but not blank) | Member's mobile phone |
| receive_email_offers | boolean (optional) | Set member's receive email offers preference |
| receive_sms_offers | boolean (optional) | Set member's receive email sms preference |
| receive_mobile_app_offers | boolean (optional) | Set member's receive mobile app offers preference |
| receive_mail_offers | boolean (optional) | Set member's receive mail offers preference |
| receive_e_statements | boolean (optional) | Set member's receive E-statements preference |
Delete Profile (Account)
current_password:
To delete member profile using current_password and valid access_token, invoke the followingcURLcommand:
curl -X DELETE
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
-F "current_password=<current_password>"
<base_url>/api/profile
Failed responses:
{
"code": 4045,
"name": "invalid_record",
"message": "Current password can't be blank"
}
{
"code": 4045,
"name": "invalid_record",
"message": "Current password is invalid"
}
otp_code:
To request a new OTP code sent to member's email on record, invoke the followingcURLcommand:
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/profile/otp
To delete member profile using OTP code received via email and valid access_token, invoke the following
cURLcommand:
curl -X DELETE
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
-F "code=<code>"
<base_url>/api/profile
Failed responses:
{
"code": 4045,
"name": "invalid_record",
"message": "Code can't be blank"
}
{
"code": 4045,
"name": "invalid_record",
"message": "Code is invalid"
}
access_token:
To delete member profile with just a valid access_token, invoke the followingcURLcommand:
curl -X DELETE
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/profile
If successful, the response should be:
{
"success": true
}
Allow member to delete his profile or account and any related child objects, like content responses, activities, etc.
The default behavior requires member's current password. It can be changed to require an OTP code (one-time-password) or just a valid member's access token. The most secure option is to use OTP code sent to member's email on record that expires after 5 minutes (default). This expiration can be changed via Direct MFA Code Validity in Minutes in marketing console Program Settings page.
Using otp_code requires email service and an extra environment variable to be set -- MFA_SECRET_ENCRYPTION_KEY, this can be any random string or generated by some randomizer tool.
To request a new OTP code, call POST <base_url>/api/profile/otp with a valid access_token.
Contact support to change GDPR_DELETION_REQUIREMENT environment variable. Below are the options:
| Value | Form Parameter Name | Description |
|---|---|---|
| current_password | current_password | Requires member's current password to delete the account. This is the default setting. |
| otp_code | code | Requires OTP code sent to member's email and valid access token to delete the account. Make sure to also request MFA_SECRET_ENCRYPTION_KEY environment variable to be set. |
| access_token | n/a |
Allows deletion with just the valid access token. |
| disable | n/a |
Disable account deletion completely, returns Endpoint not found error. |
HTTP Request
DELETE <base_url>/api/profile
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
Form Parameters
| Parameter | Type | Description |
|---|---|---|
| current_password | string (required if setting is current_password) |
Member's current password |
| code | string (required if setting is otp_code) |
OTP code sent to member's email |
Upload Avatar
Allows the user to upload an avatar of type image/jpeg or image/png. Uploading a new avatar overwrites the existing one.
To upload/update a user avatar via command line, invoke the following
cURLcommand:
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
-F "avatar=<avatar_path/avatar.jpg>"
<base_url>/api/profile/avatar
If successful, the response should look like this:
{
"success": true,
"data": {
"avatar_url": "/standard/12007318_10153070054750079_1060767658_n.jpg?1444033847",
"thumb_avatar_url": "/thumb/12007318_10153070054750079_1060767658_n.jpg?1444033847"
}
}
HTTP Request
POST <base_url>/api/profile/avatar
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
Form Parameters
| Parameter | Type | Description |
|---|---|---|
| avatar | file (required) | Raw image data from file |
Remove Avatar
To remove a user avatar via command line, invoke the following
cURLcommand:
curl -X DELETE
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/profile/avatar
If successful, the response should be:
{
"success":true
}
Allows the user to remove or clear existing avatar.
HTTP Request
DELETE <base_url>/api/profile/avatar
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
Change Password
Allows the user to change an existing password.
To change user password via command line, invoke the following
cURLcommand:
curl -X PUT
-H 'Accept: application/vnd.stellar-v1+json'
-F "current_password=<current_password>"
-F "password=<password>$"
-F "password_confirmation=<password_confirmation>$"
<base_url>/api/profile/change_password
If successful, the response should be:
{
"success": true
}
If not, the response should look like this:
{
"code": 4400,
"name": "invalid_record",
"message": "Current password is invalid."
}
HTTP Request
PUT <base_url>/api/profile/change_password
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
Form Parameters
| Parameter | Type | Description |
|---|---|---|
| current_password | string (required or optional) | The user's current password. Optional if member record's encrypted_password password is blank |
| password | string (required) | The user's new password |
| password_confirmation | string (required) | Confirmation of the user's new password |
Change Password with MFA
MFA provides another layer of security for the change password. When enabled (Member API MFA in program settings), an OTP will be sent to the member and it has to be included as a payload in the original change password request. The initial process is the same with the regular change password but server will respond with either with a mfa_required or mfa_channel_required message upon submission (with correct and valid data). Once the member receives the otp and enters it to the system, the original change password request must be posted again to the server but this time with the otp payload.
Response definition
mfa_required - An OTP has been sent to the member and it needs to be validated. The change password request must be posted again but with the otp parameter
mfa_channel_required - There is more than one channel available for the member thus cannot proceed to send OTP. The channel list would be included in the response for the member to choose. The selected channel will then be a payload for the mfa challenge request which would trigger sending of OTP to the member.
Example of mfa_required response:
{
"code": 4109,
"name": "mfa_required",
"message": "Multifactor authentication required",
"mfa_token": "9c7fb5ce403b42c1d874c830b843d02f",
"challenge": "otp",
"channel": "email"
"otp_expiration": "2022-12-22T02:49:00Z"
}
Example of mfa_channel_required response:
{
"code": 4110,
"name": "mfa_channel_required",
"message": "Multifactor authentication channel required",
"mfa_token": "dc3759be251b5b2b7b8a90ed81c96e7e",
"channels": [
"sms",
"email"
]
}
Change Password (otp)
Once the OTP is received by the member, the initial request must be posted back to the server with the otp parameter.
Change Password (otp) with
cURLcommand:
curl -X PUT
-H 'Accept: application/vnd.stellar-v1+json'
-F "current_password=<current_password>"
-F "password=<password>"
-F "password_confirmation=<password_confirmation>"
-F "otp=<otp>"
<base_url>/api/profile/change_password
If successful, the response should be:
{
"success": true
}
If current password provided is invalid, the response should look like this:
{
"code": 4400,
"name": "invalid_record",
"message": "Current password is invalid."
}
If otp provided is invalid, the response should look like this:
{
"code": 4107,
"name": "invalid_otp",
"message": "Invalid One Time Password"
}
HTTP Request
PUT <base_url>/api/profile/change_password
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Form Parameters
| Parameter | Type | Description |
|---|---|---|
| current_password | string (required or optional) | The user's current password. Optional if member record's encrypted_password password is blank |
| password | string (required) | The user's new password |
| password_confirmation | string (required) | Confirmation of the user's new password |
| otp | string (required) | The otp that was sent to the user |
MFA Challenge
MFA Challenge request using
cURLcommand:
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-F "channel=<channel>"
-F "mfa_token=<mfa_token>"
<base_url>/mfa/challenge
If successful, the OTP would be sent to the member and the response should look like this:
{
"success": true,
"data": {
"challenge": "otp",
"mfa_token": "d412b6d3562e3003eefddfbe17a67650",
"channel": "email",
"otp_expiration": "2023-01-12T10:40:30Z"
}
}
If mfa_token is invalid, the response should look like this:
{
"code": 4108,
"name": "invalid_mfa_token_error",
"message": "Invalid MFA Token"
}
If passed channel is not one of the valid channels for the member, the response should look like this:
{
"code": 4111,
"name": "invalid_mfa_channel",
"message": "Invalid multifactor authentication channel",
"mfa_token": "8871eb2116ebd469f5879c52214984d9",
"channel": "snailmail",
"channels": [
"email",
"sms"
]
}
This endpoint provides the ability to send or resend the OTP to the member. Common usage would be when a mfa_channel_required is received from the server.
HTTP Request
POST <base_url>/mfa/challenge
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
Form Parameters
| Parameter | Type | Description |
|---|---|---|
| mfa_token | string (required) | The token received from the initial login's mfa_required or mfa_channel_required response |
| channel | string (required) | The communication channel on which the OTP would be send through |
Last Active At
To update user attribute
last_active_atvia command line, invoke the followingcURLcommand:
curl -X PUT
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/profile/active
If successful, the response should be:
{
"success": true
}
Updates the datetime value the user was last active.
HTTP Request
PUT <base_url>/api/profile/active
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
Friends
To get the user's list of friends via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/friends
If successful, the response should look like this:
{
"success": true,
"data": [
{
"id": 2,
"member_id": "A-0000002",
"first_name": "Chuck",
"last_name": "Norris",
"display_name": "Chuck Norris",
"avatar_url": ""
},
{
"id": 1,
"member_id": "A-0000001",
"first_name": "Bruce",
"last_name": "Nolan",
"display_name": "Bruce Nolan",
"avatar_url": ""
}
]
}
Allows the user to retrieve his/her list of friends.
HTTP Request
GET <base_url>/api/friends
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| leaderboard | string (optional) | leaderboard name from the list of Leaderboards |
| paged | boolean (optional) | Return total_pages and total_entries result using paged param; Default is false |
Referral Codes
To get the user's list of referral codes via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/referral_codes
If successful, the response should look like this:
{
"success": true,
"data": [
{
"code": "UK3D-HBT2"
}
]
}
Allows the user to generate and retrieve his/her referral codes.
HTTP Request
GET <base_url>/api/referral_codes
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
Referrals
To get the user's list of successful referrals via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/referrals
If successful, the response should look like this:
{
"success":true,
"data":{
"total_pages":1,
"total_entries":1,
"referrals":[
{
"name":"Carson Feest",
"email":"shemar_ratke2@raynor.name",
"member_id":"M-000000006",
"referral_code":"5119862237273",
"referred_date": "2024-06-11T03:20:15.000Z"
}
]
}
}
Returns list of current user's successful referrals and the the referral code used.
HTTP Request
GET <base_url>/api/referrals
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| page | numeric (optional) | Offset page parameter |
| per_page | numeric (optional) | Number of items per page |
Submit a Referrer
To submit a referrer via command line, invoke the following
cURLcommand:
curl -X PUT
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
-F "referral_code=<referral_code>"
<base_url>/api/profile/referral_code
If successful, the response should look like this:
{
"success": true
}
Allows the user to submit his/her referrer's referral code.
HTTP Request
PUT <base_url>/api/profile/referral_code
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
Form Parameters
| Parameter | Type | Description |
|---|---|---|
| referral_code | string (required) | The referrer's referral code |
Connected Identities
To get the current member's connected identities, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/profile/identities
If successful, the response should look like this:
{
"success": true,
"data": [
{
"uid": "117587795263690",
"provider": "facebook",
"display_name": "Mark Sadansen (fakxyyv_sadansen_1444609795@tfbnw.net)"
}
]
}
List all connected identities.
HTTP Request
GET <base_url>/api/profile/identities
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
Connect an Identity
To connect a social account Facebook or Google identity to Marigold Loyalty, invoke the following
cURLcommand:
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
-F "token=<provider_token>"
<base_url>/api/profile/connect/<provider>
If successful, the response should look like this:
{
"success": true
}
Connect Facebook or Google identity.
HTTP Request
POST <base_url>/api/profile/connect/<provider>
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| token | string (required) | token string issued by provider |
Route Parameter
| Parameter | Type | Description |
|---|---|---|
| provider | string (required) | provider is either facebook, google, twitter, instagram, strava, garmin or apple |
Disconnect an Identity
To disconnect an identity from Marigold Loyalty via command line, invoke the following
cURLcommand:
curl -X DELETE
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
-F "uid=<uid>"
<base_url>/api/identities/<provider>
If successful, the response should look like this:
{
"success": true
}
Disconnect an identity from Marigold Loyalty.
HTTP Request
DELETE <base_url>/api/profile/identities/<provider>
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| uid | string (required) | uid is the unique identifier from list of connected identities |
Route Parameter
| Parameter | Type | Description |
|---|---|---|
| provider | string (required) | provider is either facebook, google, twitter, instagram, strava, garmin or apple |
Member Preferences
Each program member is able to choose which parameters can be considered whenever an offer is sent his way. Say a member only prefers glutten-free snacks, or dairy-free vegan ice cream, or offers pertaining to the brand Dreyer's, members can do so by setting their preferences.
To get all listed member preferences via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/preferences
If successful, the response should look like this:
{
"success": true,
"data": [
{
"name": "brands",
"label": "Preferred Brands",
"description": "Member's preferred brands",
"domain": {
"list": [
"General Mills",
"Kellogs"
],
"user": [],
"selected": []
},
"is_unbounded": true,
"is_multi_select": true,
"ui_hint": "List"
},
{
"name": "location",
"label": "Location",
"description": "Member's preferred location",
"domain": {
"list": [
"San Mateo",
"Oakland"
],
"user": [],
"selected": []
},
"is_unbounded": false,
"is_multi_select": false,
"ui_hint": "Checkbox"
}
]
}
Lists all possible preference types that a member could modify to further tweak the kinds of offers or content that can be retrieved.
HTTP Request
GET <base_url>/api/preferences
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
Response JSON Explained
The response JSON object have the usual success flag (true or false), and the data attribute pointing to an array of JSON objects. Each of the listed JSON objects are representation of each Member Preference types. Picking one of them will have the following structure:
- name
[the name, or unique descriptor] - label
[readable label or title of the current preference type] - description
[full description of the current preference type]] - domain
the possible values that the user intends to associate for this preference type- list
[an array of strings allowed to be values for this preference type] - user
[member-supplied additions to the values for this preference type] - selected
[all of the domain- or member-supplied values that the member has preferred]
- list
- is_unbounded
[boolean describing whether this preference type can have domains that are member-supplied] - is_multi_select
[boolean that allows members to select multiple items from the domain. False if only one can be chosen] - ui_hint
[suggested type of user interface to render the list]
UI Hints
For the ui_hint attribute, the values you can receive are:
List- Render the domain as a dropdown list
Checkbox- Render the domain as a checkbox- or radio button-oriented list, depending on the multi-selection
Preferences Metadata
To get member preferences metadata via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/preferences/describe
List of member preferences information.
HTTP Request
GET <base_url>/api/preferences/describe
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
If successful, the response should look like this:
{
"success": true,
"data": [
{
"name": "brands",
"label": "Brands",
"description": "Brands",
"domain": {
"list":[
"nike",
"addidas",
"world balance",
"puma",
"levis"
]
},
"is_unbounded": false,
"is_multi_select": false,
"ui_hint": "List"
},
{
"name": "genre",
"label": "Genre",
"description": "",
"domain": {
"list":[
"chacha",
"jazz",
"punk"
]
},
"is_unbounded": false,
"is_multi_select": false,
"ui_hint": "Checkbox"
}
]
}
Preference by Name
To get a specific member preference by name via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/preferences/<name>
If successful, the response should look like this:
{
"success": true,
"data": {
"name": "brands",
"label": "Preferred Brands",
"description": "Member's preferred brands",
"domain": {
"list": [
"General Mills",
"Kellogs"
],
"user": [],
"selected": []
},
"is_unbounded": true,
"is_multi_select": true,
"ui_hint": "List"
}
}
Allows the user to get a specific preference by name, retrieved from Member Preferences. It should be noted that the parameter here is the name.
HTTP Request
GET <base_url>/api/preferences/<name>
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| name | string (required) | specific preference name |
Add/Remove a Domain
To add a domain under a member preference via command line, noted by its name, invoke the following
cURLcommand:
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
-F "domain=Samsung"
<base_url>/api/preferences/<name>/domain
On the other hand, to remove a domain via command line, invoke the following
cURLcommand:
curl -X DELETE
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
-F "domain=Samsung"
<base_url>/api/preferences/<name>/domain
If successful, the response should be:
{
"success": true
}
And when you try to get the preference type after adding a domain, the response should look like this:
{
"success": true,
"data": {
"name": "brands",
"label": "Preferred Brands",
"description": "Member's preferred brands",
"domain": {
"list": [
"General Mills",
"Kellogs",
"Nike"
],
"user": [
"Nike"
],
"selected": []
},
"is_unbounded": true,
"is_multi_select": true,
"ui_hint": "List"
}
}
Allows the user to add/remove a member-supplied domain value. This, of course, will only work if your adding a domain to a preference that is unbounded or the domain being removed exists. Otherwise an error will be thrown.
HTTP Request
POST <base_url>/api/preferences/<name>/domain
DELETE <base_url>/api/preferences/<name>/domain
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| name | string (required) | specific preference name |
Form Parameters
| Parameter | Type | Description |
|---|---|---|
| domain | string (required) | The domain value to be added/removed |
Update Selected Domains
To update selected domain values for a member preference via command line, noted by its name, invoke the following
cURLcommand:
curl -X PUT
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
-F "domain=Nike"
<base_url>/api/preferences/<name>
If successful, the response should be:
{
"success": true
}
And when you try to get the preference type after selecting a domain, the response should look like this:
{
"success": true,
"data": {
"name": "brands",
"label": "Preferred Brands",
"description": "Member's preferred brands",
"domain": {
"list": [
"General Mills",
"Kellogs",
"Nike"
],
"user": [
"Nike"
],
"selected": [
"Nike"
]
},
"is_unbounded": true,
"is_multi_select": true,
"ui_hint": "List"
}
}
Allows the user to update the selected domain values for a specific member preference. This, of course, will only work if the domain values being selected exists. Otherwise an error will be thrown.
HTTP Request
PUT <base_url>/api/preferences/<name>
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| name | string (required) | specific preference name |
Form Parameters
| Parameter | Type | Description |
|---|---|---|
| domain | string (required) | A comma-and-space-separated listing of all selected domains |
Account Metrics
To get member metrics via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/metrics
If successful, the response should look like this:
{
"success": true,
"data": {
"created_at": "2015-06-30T04:28:37.549Z",
"metrics": {
"point": {
"label": "Point",
"balance": "10393",
"life_time": "10428",
"last_12mo": "10428",
"ytd": "10428",
"last_30d": "10428",
"mtd": "10428",
"today": "0"
},
"spend": {
"label": "Spend",
"balance": "0.0",
"life_time": "0.0",
"last_12mo": "0.0",
"ytd": "0.0",
"last_30d": "0.0",
"mtd": "0.0",
"today": "0.0"
}
}
}
}
Member metrics information.
HTTP Request
GET <base_url>/api/metrics
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
Metric History
To test member metric history by type via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Authorization: Bearer <access_token>'
-F "metric_name=point"
<base_url>/api/metric_history
If successful, the response should look like this:
{
"success": true,
"data": {
"point": {
"earn": "30",
"balance": "10",
"redeem": "40",
"expired": "20"
}
}
}
Return JSON if invalid or non-existing metric_name is passed
{
"code": 4044,
"name": "not_available",
"message": "Metric 'smile' does not exist"
}
Allows the user to get metric history by metric_name.
HTTP Request
GET <base_url>/api/metrics_history
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Access | string (required) | application/vnd.stellar-v1+json |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| metric_name | string (required) | metric_name to retrieve |
Activities
To get member activities via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/activities
If successful, the response should look like this:
{
"success": true,
"data": {
"total_pages": 1,
"total_entries": 3,
"period_type": "Day",
"period_start": "",
"period_end": "",
"activities": [
{
"sl_type": "sl_member_preference",
"sl_items": [
{
"sl_preference": "brands",
"sl_value": "Brand X",
"sl_prev_value": "Brand Y"
}
],
"sl_integration_id": "1-Person",
"sl_ext_id": "1-1444033722-Person",
"sl_environment_id": "1",
"sl_id": "3",
"sl_member_id": "A-0000001",
"sl_activity_ts": "2015-10-05T08:28:42.303Z",
"sl_metrics": {},
"sl_type_label": "Member Preference Activity"
},
{
"sl_type": "sl_challenge",
"sl_action": "respond",
"sl_status": "submitted",
"sl_prev_status": "",
"sl_value": 0,
"sl_metric": "Point",
"challenge_id": 1,
"challenge_name": "update_preference_challenge",
"sl_integration_id": "1-ChallengeResponse",
"sl_ext_id": "1-1444033706-ChallengeResponse",
"sl_environment_id": "1",
"sl_id": "2",
"sl_member_id": "A-0000001",
"_sl_version": "2.0",
"sl_activity_ts": "2015-10-05T08:28:26.459Z",
"sl_metrics": {},
"sl_type_label": "Challenge Response Activity",
"challenge_label": "Update Preference Challenge"
},
{
"sl_type": "sl_sign_up",
"sl_environment_id": "1",
"sl_id": "1",
"sl_member_id": "A-0000001",
"_sl_version": "2.0",
"sl_activity_ts": "2015-06-25T04:14:08.934Z",
"sl_metrics": {},
"sl_type_label": "Sign-up"
}
]
}
}
Member activities information.
HTTP Request
Get <base_url>/api/activities
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| period_type | string (optional) | Day or Month, default Day |
| period_start | string (optional) | i.e. 2014-01-01 if period_type is Day, 2014-01 if period type is Month |
| period_end | string (optional) | i.e. 2014-01-01 if period_type is Day, 2014-10 if period type is Month |
| with_metric_change | boolean (optional) | Values can be true or false |
| page | numeric (optional) | Offset page parameter |
| per_page | numeric (optional) | Number of items per page |
Normalized Activities
To get member normalized activities via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/activities2
If successful, the response should look like this:
{
"success": true,
"data": {
"total_pages": 1,
"total_entries": 2,
"period_start": "",
"period_end": "",
"activities": [
{
"activity_ts": "2015-12-01T09:36:04.805Z",
"type_name": "sl_member_attribute",
"type_label": "Update Member Attribute",
"metric_name": "point",
"metric_label": "Point",
"metric_amount": "0",
"label": "",
"detail": ""
},
{
"activity_ts": "2015-12-01T03:14:16.670Z",
"type_name": "sl_challenge",
"type_label": "Challenge Response",
"metric_name": "point",
"metric_label": "Point",
"metric_amount": "100",
"label": "Photo Challenge",
"detail": ""
}
]
}
}
Member normalized activities information.
HTTP Request
Get <base_url>/api/activities2
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| activity_types | string (optional) | Comma-separated activity type names to filter by type/s |
| period | string (optional) | Default is 'last3m', see table 'Options for Period' below for other options |
| period_start | string (optional) | Specify start date, i.e. 2014-01-01 |
| period_end | string (optional) | Specify end date, i.e. 2014-01-01 |
| with_details | boolean (optional) | Values can be true or false |
| with_line_item | boolean (optional) | Values can be true or false |
| earned_metrics | string or array (optional) | List of metric names either CSV string or array |
| with_metric_change | boolean (optional) | Values can be true or false |
| page | numeric (optional) | Offset page parameter |
| per_page | numeric (optional) | Number of items per page |
Options for period
| Value | Description |
|---|---|
| alltime | Activities all time |
| ytd | Year to date |
| prev<n>ytd | Year to date of previous n years e.g. prev1ytd. If today is 05/05/2017, then it would be 01/01/2016-05/05/2016. Used for period-to-period comparison. |
| mtd | Month to date |
| prev<n>mtd | Same period as mtd but of previous n months e.g. prev1mtd. If today is 05/05/2017, then it would be 04/01/2017-04/05/2017. Used for period-to-period comparison. |
| wtd | Week to date, starts on a Monday |
| prev<n>wtd | Same period as wtd but of previous n weeks e.g. prev1wtd. If today is 05/05/2017 (Friday), then it would be 04/24/2017-04/28/2017 (Monday to Friday). Used for period-to-period comparison. |
| qtd | Quarter to date |
| prev<n>qtd | Same period as qtd but of previous n quarters e.g. prev1qtd. If today is 05/05/2017, then it would be 01/01/2017-02/05/2017 since previous quarter is from January to March. Used for period-to-period comparison. |
| last<n>d | Last n days; e.g. last5d |
| last<n>w | Last n weeks; e.g. last3w |
| last<n>m | Last n months; e.g. last2m |
| prev<n>d | Previous n days; e.g. prev5d. The 5 days before the last 5 days. Used for period-to-period comparison. |
| prev<n>w | Previous n weeks; e.g. prev5w. The 5 weeks before the last 5 weeks. Used for period-to-period comparison. |
| prev<n>m | Previous n months; e.g. prev5m. The 5 months before the last 5 minths. Used for period-to-period comparison. |
Activities by Type
To get member activities by type via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Authorization: Bearer <access_token>'
<base_url>/api/activities_metrics
If successful, the response should look like this:
{
"success": true,
"data": {
"created_at": "2015-06-30T04:50:21.779Z",
"activity_types": {
"sl_challenge": {
"label": "Challenge Response Activity",
"balance": "104",
"life_time": "104",
"last_12mo": "104",
"ytd": "104",
"last_30d": "104",
"mtd": "104",
"today": "0"
},
"sl_sign_up": {
"label": "Sign-up",
"balance": "0",
"life_time": "0",
"last_12mo": "0",
"ytd": "0",
"last_30d": "0",
"mtd": "0",
"today": "0"
}
}
}
}
Allows the user to get activities by type.
HTTP Request
GET <base_url>/api/activities_metrics
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Access | string (required) | application/vnd.stellar-v1+json |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
Activities History by Type
To test member activities history by type via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Authorization: Bearer <access_token>'
-F "period_type=Month"
<base_url>/api/activities_metrics_history
If successful, the response should look like this:
{
"success": true,
"data": {
"created_at": "2015-06-30T04:52:57.177Z",
"period_type": "Month",
"period_start": "2015-01",
"period_end": "2015-6",
"activity_types": {
"sl_challenge": {
"label": "Challenge Response Activity",
"values": [
"",
"",
"",
"",
"",
"104"
]
},
"sl_sign_up": {
"label": "Sign-up",
"values": [
"",
"",
"",
"",
"",
"0"
]
}
}
}
}
Allows the user to get activities history by type.
HTTP Request
GET <base_url>/api/activities_metrics_history
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Access | string (required) | application/vnd.stellar-v1+json |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| period_type | string (optional) | Day or Month, default Day |
| period_start | string (optional) | i.e. 2014-01-01 if period_type is Day, 2014-01 if period type is Month |
| period_end | string (optional) | i.e. 2014-01-01 if period_type is Day, 2014-10 if period type is Month |
Household
Create new member as a household member
To add an existing member via command line, invoke the following
cURLcommand:
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
-F "first_name=<first name>"
-F "last_name=<last name>"
-F "birthdate=<birthday>"
-F "integration_id=<integration_id>"
-F "email=<email>"
-F "password=<password>"
<base_url>/api/household/create_child
If successful, the response should look like this:
{
"success": true
}
HTTP Request
POST <base_url>/api/household/create_child
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
Form Parameters
| Parameter | Type | Description |
|---|---|---|
| first_name | string (optional) | User's first name |
| last_name | string (optional) | User's last name |
| birthdate | date (optional) | User's birthdate |
| integration_id | string (optional) | User's integration_id |
| string (optional) | User's email | |
| password | string (optional) | User's password |
Add existing member to household member
To add an existing member via command line, invoke the following
cURLcommand:
curl -X PUT
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
-F "child_member_id=<member_id of the user>"
<base_url>/api/household/add_child
If successful, the response should look like this:
{
"success": true
}
If a user already belongs to a household, the response should look like this:
{
"code": 4400,
"name": "invalid_record",
"message": "User already belongs to a household"
}
If member_id of the child does not exists, the response should look like this:
{
"code": 4044,
"name": "not_available",
"message": "Resource not available"
}
HTTP Request
PUT <base_url>/api/household/add_child
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
Form Parameters
| Parameter | Type | Description |
|---|---|---|
| child_member_id | string (required) | member_id of the user you want to add as child |
Remove a member from the household
To remove a member from household via command line, invoke the following
cURLcommand:
curl -X PUT
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
-F "child_member_id=<member_id of the child>"
<base_url>/api/household/remove_child
If successful, the response should look like this:
{
"success": true
}
If a user does not belong to the user's household, the response should look like this:
{
"code": 4400,
"name": "invalid_record",
"message": "Invalid secondary member"
}
If member_id of the child does not exists, the response should look like this:
{
"code": 4044,
"name": "not_available",
"message": "Resource not available"
}
HTTP Request
PUT <base_url>/api/household/remove_child
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
Form Parameters
| Parameter | Type | Description |
|---|---|---|
| child_member_id | string (required) | member_id of the user you want to remove from household |
Orders
To get orders via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/orders
If successful, the response should look like this:
{
"success": true,
"data": {
"total_pages": 1,
"total_entries": 1,
"orders": [
{
"id": 1,
"transaction_type": "sale",
"ordered_at": "2019-05-20T18:58:19.000Z",
"preferred_receive_at": "null",
"source_name": "pos",
"order_status": "completed",
"integration_id": "124-7859202-20190522",
"place_integration_id": "124",
"terminal_name": "WEB",
"transaction_id": "7859202",
"business_date": "2019-05-22",
"metric_name": "point",
"metric_amount": "295.0",
"currency": "USD",
"eligible_subtotal": "0.00",
"subtotal": "294.75",
"overall_discount": "0.00",
"tip_amount": "0.00",
"service_charge": "0.00",
"tax": "0.00",
"total_amount": "294.75",
"created_at": "2019-07-18T04:29:17.000Z",
"updated_at": "2019-07-18T04:29:17.000Z",
"overall_item_count": 6,
"item_count": 2,
"items": [
{
"id": 1,
"kind": "item",
"subkind": "null",
"sku": "null-40",
"upc": "null",
"category": [],
"name": "The Works™",
"description": "The Works™-14\" Large-FAMOUS THIN",
"line_number": "2",
"linked_line_number": "0",
"depth": 0,
"discountable": false,
"base_price": "54.30",
"weight": "0.0",
"quantity": "3.0",
"net_price": "162.90",
"discount": "0.00",
"amount": "162.90",
"created_at": "null",
"updated_at": "null"
},
{
"id": 2,
"kind": "item",
"subkind": "null",
"sku": "null-40",
"upc": "null",
"category": [],
"name": "Pepperoni",
"description": "Pepperoni-14\" Large-FAMOUS THIN",
"line_number": "1",
"linked_line_number": "0",
"depth": 0,
"discountable": false,
"base_price": "43.95",
"weight": "0.0",
"quantity": "3.0",
"net_price": "131.85",
"discount": "0.00",
"amount": "131.85",
"created_at": "null",
"updated_at": "null"
}
]
}
]
}
}
Lists all orders available to the user.
HTTP Request
GET <base_url>/api/orders
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| access_token | string (required) | access_token from successful login |
| excluded_transaction_types | Array (optional) | List of transaction types to exclude. (sale, refund or void) |
| page | numeric (optional) | Offset page parameter |
| per_page | numeric (optional) | Number of items per page |
| sort_by | string (optional) | Sort options. Values can be id or ordered_at. default: ordered_at |
| sort_dir | string (optional) | Sort direction. Values can be desc or asc. default: desc |
Order by ID
To get a specific order by ID via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/orders/<id>
If successful, the response should look like this:
{
"success": true,
"data": {
"id": 1,
"transaction_type": "sale",
"ordered_at": "2019-05-20T18:58:19.000Z",
"preferred_receive_at": "null",
"source_name": "pos",
"order_status": "completed",
"integration_id": "124-7859202-20190522",
"place_integration_id": "124",
"place": {
"id": "null",
"label": "null",
"name": "null"
},
"terminal_name": "WEB",
"transaction_id": "7859202",
"business_date": "2019-05-22",
"last_4_cc_digits": "4444",
"metric_name": "point",
"metric_amount": "295.0",
"currency": "USD",
"eligible_subtotal": "0.00",
"subtotal": "294.75",
"overall_discount": "0.00",
"tip_amount": "0.00",
"service_charge": "0.00",
"tax": "0.00",
"total_amount": "294.75",
"created_at": "2019-07-18T04:29:17.000Z",
"updated_at": "2019-07-18T04:29:17.000Z",
"overall_item_count": 6,
"item_count": 2,
"items": [
{
"id": 1,
"kind": "item",
"subkind": "null",
"sku": "null-40",
"upc": "null",
"category": [],
"name": "The Works™",
"description": "The Works™-14\" Large-FAMOUS THIN",
"line_number": "2",
"linked_line_number": "0",
"depth": 0,
"discountable": false,
"base_price": "54.30",
"weight": "0.0",
"quantity": "3.0",
"net_price": "162.90",
"discount": "0.00",
"amount": "162.90",
"created_at": "null",
"updated_at": "null"
},
{
"id": 2,
"kind": "item",
"subkind": "null",
"sku": "null-40",
"upc": "null",
"category": [],
"name": "Pepperoni",
"description": "Pepperoni-14\" Large-FAMOUS THIN",
"line_number": "1",
"linked_line_number": "0",
"depth": 0,
"discountable": false,
"base_price": "43.95",
"weight": "0.0",
"quantity": "3.0",
"net_price": "131.85",
"discount": "0.00",
"amount": "131.85",
"created_at": "null",
"updated_at": "null"
}
]
}
}
Allows the user to get a specific order.
HTTP Request
GET <base_url>/api/orders/<id>
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| id | integer (required) | id of a specific order |
Create Order
To create an order via command line, invoke the following
cURLcommand:
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
-d '{
"business_date": "1988-01-17",
"place_integration_id": 123,
"subtotal": 23.00,
"total_amount": 27.60,
"transaction_id": 1,
"transaction_ts": "1988-01-17T00:00:00.000Z",
"transaction_type": "sale",
"currency": "USD",
"employee_full_name": "John Doe",
"employee_identifier": "1223334444",
"item_count": 2,
"order_status": "completed",
"overall_discount": 0.0,
"overall_item_count": 5,
"ext_integration_id": "231-2112-432",
"preferred_receive_at": "2020-01-17T00:00:00.000Z",
"service_charge": 2.3,
"source": "pos",
"tax": 2.3,
"terminal_name": "A-1",
"tip_amount": 0.0,
"order_items": [
{
"amount": 18.00,
"base_price": 5.00,
"net_price": 20.00,
"quantity": 4,
"sku": "4444221333",
"categories": ["food"],
"depth": 0,
"decription": "Cheese Pizza",
"discount": 2.00,
"ext_integration_id": "4444221333",
"type": "item",
"line_number": "1",
"linked_line_number": "",
"name": "cheese_pizza_1",
"upc": "4444221333",
"weight": 0.0
},
{
"amount": 5.00,
"base_price": 5.00,
"net_price": 5.0,
"quantity": 1,
"sku": "889444444",
"categories": ["food"],
"depth": 0,
"decription": "Hawaiian Pizza",
"discount": 0.0,
"ext_integration_id": "889444444",
"type": "item",
"line_number": "2",
"linked_line_number": "",
"name": "hawaiian_pizza_1",
"upc": "889444444",
"weight": 0.0
}
]
}'
<base_url>/api/orders
If successful, the response should look like this:
{
"success": true,
"data": {
"claim_stub": null,
"claimed_at": null,
"metric_amount": "0.0",
"metric_name": "points"
}
}
Create a member order.
HTTP Request
POST <base_url>/api/orders
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
Raw JSON
| Parameter | Type | Description | Values / Sample |
|---|---|---|---|
| business_date | string (required) | Order Business Date | 1988-01-17 |
| place_integration_id | string (required) | Store Identifier | |
| subtotal | bigdecimal (required) | Order Subtotal Amount | |
| total_amount | bigdecimal (required) | Order Total amount | |
| transaction_id | string (required) | Transaction Id | |
| transaction_ts | string (required) | Transaction Timestamp | 1988-01-07T23:45:06.000Z |
| transaction_type | string (required) | Transaction Type | sale, refund or void |
| currency | string (optional) | Order Currency | USD |
| employee_full_name | string (optional) | Employee Fullname | |
| employee_identifier | string (optional) | Employee Id | |
| item_count | integer (optional) | Number of Unique Items | |
| order_status | string (optional) | Order Status | pending or completed |
| overall_discount | bigdecimal (optional) | Order Discount | |
| overall_item_count | integer (optional) | Overall Item Count | |
| ext_integration_id | string (optional) | Order External Id | |
| preferred_receive_at | string (optional) | Preferred Receive At Timestamp | 1988-01-07T23:45:06.000Z |
| service_charge | bigdecimal (optional) | Order Service Charge | |
| source | string (optional) | Order Source | pos, online, mobile, etc. |
| tax | bigdecimal (optional) | Order Tax | |
| terminal_name | string (optional) | Terminal Name | |
| tip_amount | bigdecimal (optional) | Order Tip Amount | |
| order_items | array[order items] (optional) | Order Items |
Order Items
| Parameter | Type | Description | Values / Sample |
|---|---|---|---|
| amount | bigdecimal (required) | Item Amount | |
| base_price | bigdecimal (required) | Item Base Price | |
| net_price | bigdecimal (required) | Item Net Price | |
| quantity | integer (required) | Item Quantity | |
| sku | string (required) | Item SKU | |
| categories | array[string] (optional) | Item Categories | |
| depth | integer (optional) | Item Depth/Level | 0 - primary/parent, 1 - secondary/child |
| description | string (optional) | Item Description | |
| discount | bigdecimal (optional) | Item Discount | |
| ext_integration_id | string (optional) | Item External Id | |
| type | string (optional) | Item Type | item or coupon |
| line_number | integer (optional) | Item Line Number | |
| linked_line_number | integer (optional) | Item Linked Line Number | |
| name | string (optional) | Item Name | |
| upc | string (optional) | Item UPC | |
| weight | decimal (optional) | Item Weight |
Retro Claim
To retro claim an order via command line, invoke the following
cURLcommand:
curl -X POST \
'<base_url>/api/orders/claim' \
-H 'Accept: application/vnd.stellar-v1+json' \
-H 'Authorization: Bearer <access_token>' \
-F 'transaction_id=<transaction_id>' \
-F 'business_date=<business_date>' \
-F 'place_id=<place_id>'
If successful, the response should look like this:
{
"success": true,
"data": {
"claim_stub": "1af9b765-0e15-43da-9619-7635581149f1",
"claimed_at": "2020-01-26T2:08:24.000Z",
"metric_amount": "81",
"metric_name": "points"
}
}
If unsuccessful, the response will be something like:
{
"code": 4044,
"name": "not_available",
"message": "Resource not available"
}
Retro claim a member order.
HTTP Request
POST <base_url>/api/orders/claim
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
Form Parameters
| Parameter | Type | Description |
|---|---|---|
| flow | string (optional) | Specifies the flow. Can be either receipt or credit_card. If left blank the default value is receipt |
| transaction_id | string (optional) | Transaction id |
| business_date | string (required) | Order Business Date (YYYY-MM-DD) |
| place_id | string (required) | Store Identifier |
| last_4_cc_digits | string (optional) | Last 4 digits of Credit Card |
| charged_amount | string (optional) | |
| register_name | string (optional) | |
| subtotal | string (optional) | |
| total_amount | string (optional) |
Error Codes
| Code | Description |
|---|---|
| 4044 | Resource not available |
| 4446 | Resource already claimed |
| 4049 | Retro claim age limit error |
| 4800 | Invalid parameter format |
| 4060 | Missing required parameter |
Receipts
To get awards member's receipts command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/receipts
If successful, the response should look like this:
{
"success": true,
"data": {
"total_pages": 1,
"total_entries": 2,
"receipts": [
{
"id": 23,
"created_at": "2015-12-29T01:55:28.000Z",
"updated_at": "2015-12-29T01:55:28.000Z",
"created_by": "admin",
"last_updated_by": "admin",
"receipt_url": "http://s3.amazonaws.com/path/to/receipt/file",
"or_number": "C01-1234567-4443312",
"or_date": "null",
"vendor": "amazon",
"status": "manual",
"outcome": "none",
"amount_paid": "null",
"metric_amount": "5.0",
"activity_submitted": false,
"metric_name": "point",
"uploaded_via": "web",
"processing_type": "manual",
"comment": "This is a comment added by the marketer"
},
{
"id": 24,
"created_at": "2015-12-29T02:59:59.000Z",
"updated_at": "2016-01-04T02:33:08.000Z",
"created_by": "admin",
"last_updated_by": "admin",
"receipt_url": "http://s3.amazonaws.com/path/to/receipt/file",
"or_number": "D01-4491239-4556757",
"or_date": "2015-12-23T00:00:00.000Z",
"vendor": "amazon",
"status": "manual",
"outcome": "failed_receipt_too_old",
"amount_paid": "12.94",
"metric_amount": "0.0",
"activity_submitted": false,
"metric_name": "point",
"uploaded_via": "web",
"processing_type": "manual",
"comment": "null"
}
]
}
}
Lists all submitted receipts by the member
HTTP Request
GET <base_url>/api/receipts
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| page | numeric (optional) | Offset page parameter |
| per_page | numeric (optional) | Number of items per page |
Receipt by ID
To get a specific receipt via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/receipts/<id>
If successful, the response should look like this:
{
"success": true,
"data": {
"id": 100,
"created_at": "2016-01-11T07:40:20.000Z",
"updated_at": "2016-01-11T07:40:20.000Z",
"created_by": "System",
"last_updated_by": "System",
"receipt_url": "http://s3.amazonaws.com/path/to/receipt/file",
"or_number": "ABC-123-45677",
"or_date": "null",
"vendor": "amazon",
"status": "manual",
"outcome": "failed_duplicate",
"amount_paid": "null",
"metric_amount": "0.0",
"activity_submitted": false,
"metric_name": "point",
"uploaded_via": "web",
"processing_type": "auto",
"comment": "null"
}
}
Allows the member to get a specific receipt.
HTTP Request
GET <base_url>/api/receipts/<id>
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| id | integer (required) | id of a specific receipt |
Submit a Receipt
To receipt via command line, invoke the following
cURLcommand:
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
-F "receipt=<path_to_receipt/receipt_file>"
<base_url>/api/receipts
If successful, the response should look like this:
{
"success": true
}
Allows the member to submit a receipt. The receipt parameter could be an image, HTML, .txt or .json file
HTTP Request
POST <base_url>/api/receipts
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| receipt | file (required) | image, HTML, .txt or .json file |
News Feed
Lists all news feeds visible to the user.
To get all news feeds via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/news_feeds
If successful, the response should look like this:
{
"success": true,
"data": {
"total_pages": 1,
"total_entries": 1,
"news_feeds": [
{
"id": 26,
"name": "members",
"tag": "null",
"description": "Magnam natus assumenda quod sit aut. members",
"image_url": "/system/news_feeds/images/000/000/026/standard/images.jpeg?1447300177",
"show_to_public": true,
"allowed_to_post": "some_members",
"allowed_to_post_members": [
"2"
],
"post_visibility": "post_immediately",
"allowed_to_comment": "some_members",
"allowed_to_comment_members": [
"11"
],
"comment_visibility": "post_immediately"
}
]
}
}
HTTP Request
GET <base_url>/api/news_feeds
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| page | numeric (optional) | Offset page parameter |
| per_page | numeric (optional) | Number of items per page |
Posts
We have two versions of the News Feed post structure. The following (V1) is the current structure as of this writing (November 13, 2015):
To get all news feed V1 posts via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/news_feed
If successful, the response should look like this:
{
"success": true,
"data": {
"total_pages": 1,
"total_entries": 3,
"pinned": {
"id": 1,
"created_at": "2015-06-30T07:59:51.000Z",
"subject": {
"body": "Today is Pasig Day!",
"attachment_urls": [],
"attachment_thumbs": []
},
"owner_name": "admin",
"owner_avatar": "",
"owner": {
"owner_name": "admin",
"owner_avatar": "",
"owner_id": "null",
},
"like_count": 0,
"comment_count": 0,
"is_owner": false,
"liked": false,
"is_pinned": true,
"flagged": "unflagged",
"attachment_urls": [],
"attachment_thumbs": [],
"target_url": "https://client-webapp.com/is?p=someencodedstring",
"internal_url": "challenge://256"
},
"feed": [
{
"id": 2,
"created_at": "2015-07-01T06:21:59.000Z",
"subject": {
"body": "Gentle Reminder",
"attachment_urls": [
"http://s3.amazonaws.com/path/to/image"
],
"attachment_thumbs": [
"http://s3.amazonaws.com/path/to/image/thumbnail"
]
},
"owner_name": "Chuck Norris",
"owner_avatar": "http://s3.amazonaws.com/path/to/owner/avatar",
"owner": {
"owner_name": "Chuck Norris",
"owner_avatar": "http://s3.amazonaws.com/path/to/owner/avatar",
"owner_id": "L-000123",
},
"like_count": 0,
"comment_count": 0,
"is_owner": true,
"liked": false,
"is_pinned": false,
"flagged": "unflagged",
"attachment_urls": [
"http://s3.amazonaws.com/path/to/image"
],
"attachment_thumbs": [
"http://s3.amazonaws.com/path/to/image/thumbnail"
],
"target_url": "https://client-webapp.com/is?p=someencodedstring",
"internal_url": "challenge://256"
},
{
"id": 2,
"created_at": "2015-07-01T06:20:53.000Z",
"subject": {
"id": 121,
"response": "Cake",
"attachment_url": "http://s3.amazonaws.com/path/to/video/or/image",
"status": "approved",
"comments": [],
"created_at": "2015-11-11T23:53:52.000Z",
"updated_at": "2015-11-11T23:53:52.000Z",
"attachment_urls": [ "http://s3.amazonaws.com/path/to/video/or/image"
],
"attachment_thumbs": [
"http://s3.amazonaws.com/path/to/video/or/image/thumbnail"
]
},
"owner_name": "Shrek",
"owner_avatar": "http://s3.amazonaws.com/path/to/owner/avatar",
"owner": {
"owner_name": "Shrek",
"owner_avatar": "http://s3.amazonaws.com/path/to/owner/avatar",
"owner_id": "L-000144",
},
"like_count": 0,
"comment_count": 0,
"is_owner": true,
"liked": false,
"is_pinned": false,
"flagged": "unflagged",
"attachment_urls": [
"http://s3.amazonaws.com/path/to/video/or/image"
],
"attachment_thumbs": [
"http://s3.amazonaws.com/path/to/video/or/image/thumbnail"
],
"target_url": "https://client-webapp.com/is?p=someencodedstring",
"internal_url": "challenge://256"
}
]
}
}
NOTE TO DEVELOPERS: There are currently two types of News Feed Posts: - The regular ones that include the text body and attachments (if any) are those created via the Marketing Console, via the Create Post API, and the Social Media Posts imported from the Marketing Console. The submitted text body is saved and served as it was submitted. - The other one are 'activities', usually auto-generated by member responses. At the moment, we only generate posts when members respond to challenges (if enabled by the marketer). The persisted text body is a generated string from the details of the member response. The generated string follows this format: <member display name>. <activity type>. <challenge's metric_amount>. <challenge's metric_name>. <challenge's sl_label, which is actually the content heading or label>
e.g. "Matthew Shardlake. Challenge Response. 520. point. Megamillions Survey."
To get all news feed posts V2 via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/news_feed2
If successful, the response should look like this:
{
"success": true,
"data": {
"total_pages": 1,
"total_entries": 3,
"feed": [
{
"id": 266,
"created_at": "2015-11-11T23:53:54.000Z",
"owner_name": "Miyagi Ryota ",
"owner_avatar": "",
"owner": {
"owner_name": "Miyagi Ryota ",
"owner_avatar": "",
"owner_id": "L-000154",
},
"like_count": 0,
"comment_count": 2,
"is_pinned": false,
"is_owner": true,
"liked": false,
"flagged": "unflagged",
"body": "Miyagi Ryota . sl_challenge. 55.0. point. Photo",
"attachment_urls": [
"http://s3.amazonaws.com/path/to/video/or/image"
],
"attachment_thumbs": [
"http://s3.amazonaws.com/path/to/video/or/image/thumbnail"
],
"target_url": "https://client-webapp.com/is?p=someencodedstring",
"internal_url": "challenge://256"
},
{
"id": 265,
"created_at": "2015-11-11T23:52:51.000Z",
"owner_name": "admin",
"owner_avatar": "",
"owner": {
"owner_name": "admin",
"owner_avatar": "",
"owner_id": "null",
},
"like_count": 0,
"comment_count": 0,
"is_pinned": false,
"is_owner": false,
"liked": false,
"flagged": "unflagged",
"body": "Imagine there's no heaven",
"attachment_urls": [
"http://s3.amazonaws.com/path/to/video/or/image1",
"http://s3.amazonaws.com/path/to/video/or/image2"
],
"attachment_thumbs": [
"http://s3.amazonaws.com/path/to/video/or/image/thumbnail1"
"http://s3.amazonaws.com/path/to/video/or/image/thumbnail2"
]
},
{
"id": 262,
"created_at": "2015-11-02T03:03:21.000Z",
"owner_name": "admin",
"owner_avatar": "",
"owner": {
"owner_name": "admin",
"owner_avatar": "",
"owner_id": "null",
},
"like_count": 0,
"comment_count": 0,
"is_pinned": false,
"is_owner": false,
"liked": false,
"flagged": "unflagged",
"body": "It's easy if you try",
"attachment_urls": [],
"attachment_thumbs": [],
"target_url": "https://client-webapp.com/is?p=someencodedstring",
"internal_url": "challenge://256"
}
]
}
}
HTTP Request
Lists all news feed posts visible to the user.
V1: GET <base_url>/api/news_feed
V2: GET <base_url>/api/news_feed2
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| page | numeric (optional) | Offset page parameter |
| per_page | numeric (optional) | Number of items per page |
| feed_name | string (optional) | News feed's internal name. Displays posts from a specific News Feed. Default is main_newsfeed, or the first available news feed |
Post by ID
Like the list of News Feed Posts API, we have two versions of Post JSON structure. The following (V1) is the current structure as of this writing (November 13, 2015):
To get news feed post V1 by ID via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/news_feed/<id>
If successful, the response should look like this:
{
"success": true,
"data": {
"id": 1,
"created_at": "2015-06-30T07:59:51.000Z",
"subject": {
"body": "Today is Pasig Day!",
"attachment_urls": [],
"attachment_thumbs": []
},
"owner_name": "admin",
"owner_avatar": "",
"owner": {
"owner_name": "admin",
"owner_avatar": "",
"owner_id": "null",
},
"like_count": 0,
"comment_count": 0,
"is_owner": false,
"liked": false,
"is_pinned": true,
"flagged": "unflagged",
"likers": [],
"attachment_urls": [],
"attachment_thumbs": [],
"target_url": "https://client-webapp.com/is?p=someencodedstring",
"internal_url": "challenge://256"
}
}
To get news feed post V2 by ID via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/news_feed2/<id>
If successful, the response should look like this:
{
"success": true,
"data": {
"id": 266,
"created_at": "2015-11-11T23:53:54.000Z",
"owner_name": "Miyagi Ryota ",
"owner_avatar": "",
"owner": {
"owner_name": "Miyagi Ryota ",
"owner_avatar": "",
"owner_id": "L-000154",
},
"like_count": 0,
"comment_count": 2,
"is_pinned": false,
"is_owner": true,
"liked": false,
"flagged": "unflagged",
"body": "Miyagi Ryota . sl_challenge. 55.0. point. Photo",
"attachment_urls": [
"http://s3.amazonaws.com/path/to/video/or/image"
],
"attachment_thumbs": [
"http://s3.amazonaws.com/path/to/video/or/image/thumbnail"
],
"target_url": "https://client-webapp.com/is?p=someencodedstring",
"internal_url": "challenge://256"
}
}
Allows the user to get a specific news feed post by ID.
HTTP Request
V1: GET <base_url>/api/news_feed/<id>
V2: GET <base_url>/api/news_feed2/<id>
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| id | integer (required) | id of a specific news feed post |
Add a Post
To add a news feed post via command line, invoke the following
cURLcommand:
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
-F "body=<string to be added to the post>"
-F "attachments[]=@filename"
-F "attachments[]=@filename" ...
<base_url>/api/news_feed
If successful, the response should look like this:
{
"success": true,
"data": {
"wall_post": {
"id": 1,
"created_at": "2018-10-23T02:01:06.626Z",
"updated_at": "2018-10-23T02:01:06.626Z",
"trackable_id": "null",
"recipient_id": "null",
"trackable_type": "null",
"owner_type": "Member",
"recipient_type": "null",
"properties": {},
"key": "wall_post.created",
"visible": true,
"pinned_at": "null",
"post_date": "2018-10-23T02:01:06.627Z",
"news_feed_id": 1,
"owner_id": 5,
"body": "Today is Pasig Day!",
"source_uid": "null",
"targetable_id": "null",
"targetable_type": "null",
"target_url": "null",
"publish_start_at": "2018-10-23T02:01:06.620Z",
"publish_end_at": "null",
"publish_timezone": "null"
},
"attachments": [],
"attachment_thumbs": []
}
}
Allows the user to add a news feed post.
HTTP Request
POST <base_url>/api/news_feed
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
| Content-Type | string (optional, required when with attachments) | multipart/form-data |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
Form Parameters
| Parameter | Type | Description |
|---|---|---|
| body | string (required) | The message body string to be posted as a new feed post |
| attachments[] | collection of files (optional) | A set of images and / or videos that will be attached to the post |
| feed_name | string (optional) | News feed's internal name. Add the post to a specific News Feed. Default is main_newsfeed, or the first available news feed |
Update a Post
To update a news feed post via command line, invoke the following
cURLcommand:
curl -X PUT
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
-F "body=<string to be updated to the post>"
<base_url>/api/news_feed/<id>
If successful, the response should look like this:
{
"success": true
}
Allows the user to update his own news feed post. User cannot update other user's news feed post.
HTTP Request
PUT <base_url>/api/news_feed/<id>
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| id | integer (required) | id of a specific news feed post |
Form Parameters
| Parameter | Type | Description |
|---|---|---|
| body | string (required) | The message body string to change new feed post |
Remove a Post
To remove a news feed post via command line, invoke the following
cURLcommand:
curl -X DELETE
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/news_feed/<id>
If successful, the response should look like this:
{
"success": true,
"data": {
"id": 2,
"created_at": "2016-07-01T06:20:53.000Z",
"updated_at": "2016-10-23T02:08:29.000Z",
"trackable_id": "null",
"owner_id": 5,
"recipient_id": "null",
"trackable_type": "null",
"owner_type": "Member",
"recipient_type": "null",
"properties": {},
"key": "wall_post.created",
"visible": true,
"pinned_at": "null",
"post_date": "2016-10-23T02:08:29.000Z",
"news_feed_id": 1,
"body": "Good Morning!",
"source_uid": "null",
"targetable_id": "null",
"targetable_type": "null",
"target_url": "null",
"publish_start_at": "2018-10-23T02:12:25.000Z",
"publish_end_at": "null",
"publish_timezone": "null"
}
}
Allows the user to remove a news feed post.
HTTP Request
DELETE <base_url>/api/news_feed/<id>
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| id | integer (required) | id of a specific news feed post |
Like/Unlike a Post
To like a post via command line, invoke the following
cURLcommand:
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/news_feed/<id>/like
On the other hand, to unlike a post via command line, invoke the following
cURLcommand:
curl -X DELETE
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/news_feed/<id>/like
If successful, the response for both endpoints should be:
{
"success": true
}
Allows the user to like/unlike a news feed post.
HTTP Request
POST <base_url>/api/news_feed/<id>/like
DELETE <base_url>/api/news_feed/<id>/like
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| id | integer (required) | id of a specific news feed post |
Post Comments
To get news feed post comments via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/news_feed/<id>/comments
If successful, the response should look like this:
{
"success": true,
"data": {
"total_pages": 1,
"total_entries": 2,
"comments": [
{
"id": 8,
"created_at": "2015-07-02T01:48:03.000Z",
"updated_at": "2015-07-02T01:48:03.000Z",
"message": "Same to you @Chuck!",
"visible": true,
"commenter_name": "admin",
"commenter_avatar": "/system/admins/public_avatars/000/000/001/thumb/10250078_1055269054488998_7926837404024526425_n.jpg?1435740703",
"commenter": {
"commenter_name": "admin",
"commenter_avatar": "/system/admins/public_avatars/000/000/001/thumb/10250078_1055269054488998_7926837404024526425_n.jpg?1435740703",
"commenter_id": "null"
},
"likes": 0,
"liked": false,
"is_commenter": false,
"flagged": "unflagged"
},
{
"id": 7,
"created_at": "2015-07-02T01:38:48.000Z",
"updated_at": "2015-07-02T01:38:48.000Z",
"message": "Happy Pasig Day to all! :)",
"visible": true,
"commenter_name": "Chuck Norris",
"commenter_avatar": "/system/users/avatars/000/000/006/thumb/998080_10200333525036287_937268422_n.jpg?1435741024",
"commenter": {
"commenter_name": "Chuck Norris",
"commenter_avatar": "/system/users/avatars/000/000/006/thumb/998080_10200333525036287_937268422_n.jpg?1435741024",
"commenter_id": "L-000123"
},
"likes": 0,
"liked": false,
"is_commenter": true,
"flagged": "unflagged"
}
]
}
}
Lists all the comments on a news feed post.
HTTP Request
GET <base_url>/api/news_feed/<id>/comments
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| id | integer (required) | id of a specific news feed post |
Comment by ID
To get a specific news feed post comment by ID via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/news_feed/<id>/comments/<comment_id>
If successful, the response should look like this:
{
"success": true,
"data": {
"comment": {
"id": 8,
"created_at": "2015-07-02T01:48:03.000Z",
"updated_at": "2015-07-02T01:48:03.000Z",
"message": "Same to you @Chuck!",
"visible": true,
"commenter_name": "admin",
"commenter_avatar": "/system/admins/public_avatars/000/000/001/thumb/10250078_1055269054488998_7926837404024526425_n.jpg?1435740703",
"commenter": {
"commenter_name": "admin",
"commenter_avatar": "/system/admins/public_avatars/000/000/001/thumb/10250078_1055269054488998_7926837404024526425_n.jpg?1435740703",
"commenter_id": "null"
},
"likes": 0,
"liked": false,
"is_commenter": false,
"flagged": "unflagged"
}
}
}
Allows the user to get a specific comment on a news feed post.
HTTP Request
GET <base_url>/api/news_feed/<id>/comments/<comment_id>
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| id | integer (required) | id of a specific news feed post |
| comment_id | integer (required) | id of a specific news feed post comment |
Add a Comment
To add a comment via command line, invoke the following
cURLcommand:
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
-F "message=<comment message>"
<base_url>/api/news_feed/<id>/comments
If successful, the response should be:
{
"success": true
}
Allows the user to add a comment.
HTTP Request
POST <base_url>/api/news_feed/<id>/comments
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
Form Parameters
| Parameter | Type | Description |
|---|---|---|
| message | string (required) | The comment message string |
Update Comment
To update a comment via command line, invoke the following
cURLcommand:
curl -X PUT
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
-F "message=<comment message>"
<base_url>/api/news_feed/<id>/comments/<comment_id>
If successful, the response should look like this:
{
"success": true
}
Allows the user to update his own comment. User cannot update other user's comment
HTTP Request
PUT <base_url>/api/news_feed/<id>/comments/<comment_id>
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| id | integer (required) | id of a specific news feed post |
| comment_id | integer (required) | id of a specific news feed post comment |
Form Parameters
| Parameter | Type | Description |
|---|---|---|
| access_token | string (required) | access_token from successful login |
| message | string (required) | The new or updated comment message string |
Remove a Comment
To remove a comment via command line, invoke the following
cURLcommand:
curl -X DELETE
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/news_feed/<id>/comments/<comment_id>
If successful, the response should look like this:
{
"success": true,
"data": {
"id": 9,
"created_at": "2015-07-02T02:03:13.000Z",
"updated_at": "2015-07-02T02:03:13.000Z",
"message": "Hi!",
"visible": true,
"commenter_name": "Chuck Norris",
"commenter_avatar": "/system/users/avatars/000/000/006/thumb/998080_10200333525036287_937268422_n.jpg?1435741024",
"likes": 0
}
}
Allows the user to remove a comment.
HTTP Request
DELETE <base_url>/api/news_feed/<id>/comments/<comment_id>
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| id | integer (required) | id of a specific news feed post |
| comment_id | integer (required) | id of a specific news feed post comment |
Like/Unlike a Comment
To like a comment via command line, invoke the following
cURLcommand:
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/news_feed/<id>/comments/<comment_id>/like
On the other hand, to unlike a comment via command line, invoke the following
cURLcommand:
curl -X DELETE
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/news_feed/<id>/comments/<comment_id>/like
If successful, the response for both endpoints should be:
{
"success": true
}
Allows the user to like/unlike a comment.
HTTP Request
POST <base_url>/api/news_feed/<id>/comments/<comment_id>/like
DELETE <base_url>/api/news_feed/<id>/comments/<comment_id>/like
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| id | integer (required) | id of a specific news feed post |
| comment_id | integer (required) | id of a specific news feed post comment |
Flags
To get available news feed flags via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/news_feed/flags
If successful, the response should look like this:
{
"success": true,
"data": [
{
"key": "flagged_nudity",
"label": "Nudity"
},
{
"key": "flagged_spam",
"label": "Spam"
},
{
"key": "flagged_violent",
"label": "Violent"
}
]
}
Lists all available flags to be assigned or set later on a news feed post/comment.
HTTP Request
GET <base_url>/api/news_feed/flags
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
Flag/Unflag a Post
To flag a post via command line, invoke the following
cURLcommand:
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
-F "flag=<flag type>"
<base_url>/api/news_feed/<id>/flag
On the other hand, to unflag a post via command line, invoke the following
cURLcommand:
curl -X DELETE
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/news_feed/<id>/flag
If successful, the response for both endpoints should be:
{
"success": true
}
Allows the user to flag/unflag a post.
HTTP Request
POST <base_url>/api/news_feed/<id>/flag
DELETE <base_url>/api/news_feed/<id>/flag
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| id | integer (required) | id of a specific news feed post |
Form Parameters
| Parameter | Type | Description |
|---|---|---|
| flag | string (required for POST method) |
The flag key from the list of Flags |
Flag/Unflag a Comment
To flag a comment via command line, invoke the following
cURLcommand:
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
-F "flag=<flag type>"
<base_url>/api/news_feed/<id>/comments/<comment_id>/flag
On the other hand, to unflag a comment via command line, invoke the following
cURLcommand:
curl -X DELETE
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/news_feed/<id>/comments/<comment_id>/flag
If successful, the response for both endpoints should be:
{
"success": true
}
Allows the user to flag/unflag a comment.
HTTP Request
POST <base_url>/api/news_feed/<id>/comments/<comment_id>/flag
DELETE <base_url>/api/news_feed/<id>/comments/<comment_id>/flag
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| id | integer (required) | id of a specific news feed post |
| comment_id | integer (required) | id of a specific news feed post comment |
Form Parameters
| Parameter | Type | Description |
|---|---|---|
| flag | string (required for POST method) |
The flag key from the list of Flags |
Notifications
To get member notifications via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/notifications
If successful, the response should look like this:
{
"success": true,
"data": {
"total_pages": 1,
"total_entries": 2,
"notifications": [
{
"id": 2,
"title": "Challenge #6",
"text": "Hi, here's a new challenge you may want to try.",
"description": "",
"sent_date": "2015-07-03T09:10:57.000Z",
"attachment": {
"type": "Challenge",
"id": 39,
"image_url": "https://s3.amazonaws.com/stellar-qa-net9b1qlg8vk1v55llub/contents/images/000/000/928/standard/hiro_baymax_in_big_hero_6-3840x2160.jpg?1435730399",
"thumb_image_url": "https://s3.amazonaws.com/stellar-qa-net9b1qlg8vk1v55llub/contents/images/000/000/928/thumb/hiro_baymax_in_big_hero_6-3840x2160.jpg?1435730399"
}
},
{
"id": 1,
"title": "Rewards for today!",
"text": "Hi, checkout our available rewards for today.",
"description": "",
"sent_date": "2015-07-03T09:08:33.000Z",
"attachment": {
"type": "Reward",
"id": 3,
"image_url": "https://s3.amazonaws.com/stellar-qa-net9b1qlg8vk1v55llub/contents/images/000/000/928/standard/hiro_baymax_in_big_hero_6-3840x2160.jpg?1435730399",
"thumb_image_url": "https://s3.amazonaws.com/stellar-qa-net9b1qlg8vk1v55llub/contents/images/000/000/928/thumb/hiro_baymax_in_big_hero_6-3840x2160.jpg?1435730399"
}
}
]
}
}
Lists all member notifications.
HTTP Request
GET <base_url>/api/notifications
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| layout | string (optional) | The content layout name. Default is the access token's application name. Example: ios, android |
| scope_client_application | boolean (optional) | Filter push notifications based on OAuth Application's Client Application of current access_token. Default value is true. |
| page | numeric (optional) | Offset page parameter |
| per_page | numeric (optional) | Number of items per page |
| dismissed | boolean (optional) | Filter notifications based on if it's dismissed. |
| read | boolean (optional) | Filter notifications based on if it's read. |
Register a Device
To register a device via command line, invoke the following
cURLcommand:
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
-F "device_id=<device id>"
-F "token=<device token>"
<base_url>/api/devices
If successful, the response should look like this:
{
"success": true,
"data": {
"device_id": "76DA658F-5D0C-42D6-96F5-27CDD8B32475",
"token": "7941844762fac8998f02574ae8e7f4eac3b9d6d9fd433611187db7997f74c255",
"enabled": true,
"platform": "ios"
}
}
This allows the user to register a device in order to receive Push Notifications.
This could be called during every user login to ensure that the device will be registered to the user logging in.
HTTP Request
POST <base_url>/api/devices
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
Form Parameters
| Parameter | Type | Description |
|---|---|---|
| device_id | string (required) | The unique device id |
| token | string (required) | The device specific token |
Dismiss a Notification
To dismiss a message via command line, invoke the following
cURLcommand:
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/notifications/<id>/dismiss
If successful, the response should be:
{
"success": true
}
Allows the user to dismiss a notification.
HTTP Request
POST <base_url>/api/notifications/<id>/dismiss
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| id | integer (required) | id of a specific notification |
Track a Notification
To track a message via command line, invoke the following
cURLcommand:
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
-F "action=<action>"
<base_url>/api/notifications/<id>/track
If successful, the response should be:
{
"success": true
}
Allows the user to track a notification.
HTTP Request
POST <base_url>/api/notifications/<id>/track
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| id | integer (required) | id of a specific notification |
| action | string (required) | action can be either of the following: deliveredopened |
Mark a Notification as Read
To mark a message as read via command line, invoke the following
cURLcommand:
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/notifications/<id>/read
If successful, the response should be:
{
"success": true
}
Allows the user to mark a notification as read.
HTTP Request
POST <base_url>/api/notifications/<id>/read
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| id | integer (required) | id of a specific notification |
Mark a Notification as Unread
To mark a message as unread via command line, invoke the following
cURLcommand:
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/notifications/<id>/unread
If successful, the response should be:
{
"success": true
}
Allows the user to mark a notification as unread.
HTTP Request
POST <base_url>/api/notifications/<id>/unread
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| id | integer (required) | id of a specific notification |
Mark All Notifications as Read
To mark all messages as read via command line, invoke the following
cURLcommand:
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/notifications/read
If successful, the response should be:
{
"success": true
}
Allows the user to mark all notifications as read.
HTTP Request
POST <base_url>/api/notifications/read
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
Message Responses
To see all message responses via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/messages
If successful, the response should be:
{
"success": true,
"data": {
"total_pages": 1,
"total_entries": 3,
"responses": [
{
"id": 1,
"activity": "sent",
"created_at": "2018-11-08T06:13:53.000Z",
"updated_at": "2018-11-08T10:11:29.000Z",
"message": {
"id": 4,
"type": "Message::PushNotification",
"internal_name": "new_challenge",
"title": "New Challenge",
"description": "",
"attachment": {
"image_url": "",
"thumb_image_url": ""
}
},
"message_action": {
"id": 1,
"member_id": 6,
"message_id": 4,
"delivered_at": "2018-11-08T10:11:07.000Z",
"opened_at": "null",
"clicked_at": "null",
"created_at": "2018-11-08T18:11:07.000Z",
"updated_at": "2018-11-08T18:11:07.000Z",
"sent_at": "null",
"bounced_at": "null",
"flagged_at": "null",
"dropped_at": "null",
"responded_at": "null",
"batch_id": "11082018-10:11:1541671867",
"failed_at": "null"
}
},
{
"id": 2,
"activity": "sent",
"created_at": "2018-11-08T06:13:57.000Z",
"updated_at": "2018-11-08T10:11:34.000Z",
"message": {
"id": 5,
"type": "Message::Email",
"internal_name": "new_offer",
"title": "New Offer",
"description": "",
"attachment": {
"image_url": "",
"thumb_image_url": ""
}
},
"message_action": {
"id": 1,
"member_id": 6,
"message_id": 5,
"delivered_at": "2018-11-08T10:11:13.000Z",
"opened_at": "null",
"clicked_at": "null",
"created_at": "2018-11-08T18:11:13.000Z",
"updated_at": "2018-11-08T18:11:13.000Z",
"sent_at": "null",
"bounced_at": "null",
"flagged_at": "null",
"dropped_at": "null",
"responded_at": "null",
"batch_id": "11082018-10:11:1541700673",
"failed_at": "null"
}
},
{
"id": 3,
"activity": "sent",
"created_at": "2018-11-08T06:14:05.000Z",
"updated_at": "2018-11-08T10:15:47.000Z",
"message": {
"id": 6,
"type": "Message::Sms",
"internal_name": "new_challenge",
"title": "New Challenge",
"description": "",
"attachment": {
"image_url": "",
"thumb_image_url": ""
}
},
"message_action": {
"id": 1,
"member_id": 6,
"message_id": 6,
"delivered_at": "2018-11-08T10:11:17.000Z",
"opened_at": "null",
"clicked_at": "null",
"created_at": "2018-11-08T18:11:17.000Z",
"updated_at": "2018-11-08T18:11:17.000Z",
"sent_at": "null",
"bounced_at": "null",
"flagged_at": "null",
"dropped_at": "null",
"responded_at": "null",
"batch_id": "11082018-10:11:1541700677",
"failed_at": "null"
}
}
]
}
}
Lists all messages sent
HTTP Request
GET <base_url>/api/messages
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| page_type | integer (optional) | |
| per_page | integer (optional) | number of items per page |
Message Response by ID
To see all message responses via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/messages/<id>
If successful, the response should be:
{
"success": true,
"data": {
"id": 1,
"activity": "sent",
"created_at": "2018-11-08T06:13:53.000Z",
"updated_at": "2018-11-08T10:11:29.000Z",
"message": {
"id": 4,
"type": "Message::PushNotification",
"internal_name": "new_challenge",
"title": "New Challenge",
"description": "",
"attachment": {
"image_url": "",
"thumb_image_url": ""
}
},
"message_action": {
"id": 1,
"member_id": 6,
"message_id": 4,
"delivered_at": "2018-11-08T10:11:07.000Z",
"opened_at": "null",
"clicked_at": "null",
"created_at": "2018-11-08T18:11:07.000Z",
"updated_at": "2018-11-08T18:11:07.000Z",
"sent_at": "null",
"bounced_at": "null",
"flagged_at": "null",
"dropped_at": "null",
"responded_at": "null",
"batch_id": "11082018-10:11:1541671867",
"failed_at": "null"
}
}
}
Allows the user to get a specific message sent.
HTTP Request
GET <base_url>/api/messages/<id>
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| page_type | integer (optional) | |
| per_page | integer (optional) | number of items per page |
Offers
To get offers via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/offers
If successful, the response should look like this:
{
"success": true,
"data": {
"total_pages": 1,
"total_entries": 3,
"offers": [
{
"id": 24,
"internal_name": "display",
"type": "certificate",
"description": "null",
"rank": "null",
"campaign_id": 1,
"campaign_rank": 1,
"aggregated_business_value": "0.0",
"start_date": "null",
"end_date": "null",
"response_start_date": "null",
"response_end_date": "null",
"response_schedule": "null",
"trigger_activity_type": "null",
"heading": "<h2>display</h2>",
"subheading": "mobile details subheading ",
"body": "mobile details body ",
"subject": "",
"details": "",
"action": "",
"heading_color": "",
"color": "",
"bgcolor": "",
"heading_bgcolor": "",
"image1_bg": "",
"layout_id": "master",
"image_url": "https://s3.amazonaws.com/stellar-qa-net9b1qlg8vk1v55llub/contents/images/000/000/648/standard/IMG_20150624_151219869.jpg?1435197227",
"thumb_image_url": "https://s3.amazonaws.com/stellar-qa-net9b1qlg8vk1v55llub/contents/images/000/000/648/thumb/IMG_20150624_151219869.jpg?1435197227",
"favorited": false,
"respondable_info": {
"value": true,
"code": "",
"meesage": ""
},
"target_url": "",
"internal_url": "",
"tracking_code": "null",
"metric_amount": "5.0",
"metric_name": "points",
"acceptance_required": false,
"acceptance_text": "",
"acceptance_url": "null"
},
{
"id": 23,
"type": "url",
"description": "null",
"rank": "null",
"campaign_id": 1,
"campaign_rank": 3,
"aggregated_business_value": "0.0",
"url": "http://katkat.com",
"start_date": "",
"end_date": "",
"response_start_date": "null",
"response_end_date": "null",
"response_schedule": "null",
"trigger_activity_type": "null",
"heading": "<span style=\"background-color: #31a354; color: #c7e9c0;\">display offers</span>",
"subheading": "<span style=\"background-color: #756bb1;\">Master Subheading </span>",
"body": "<span style=\"font-size: 20px; background-color: rgb(49, 130, 189); color: #fd8d3c;\">Master Body</span>",
"details": "",
"action": "",
"heading_color": "",
"color": "",
"bgcolor": "",
"heading_bgcolor": "",
"image1_bg": "",
"layout_id": "master",
"image_url": "https://s3.amazonaws.com/stellar-qa-net9b1qlg8vk1v55llub/contents/images/000/000/604/standard/2mb.jpg?1435114101",
"thumb_image_url": "https://s3.amazonaws.com/stellar-qa-net9b1qlg8vk1v55llub/contents/images/000/000/604/thumb/2mb.jpg?1435114101",
"favorited": false,
"respondable_info": {
"value": true,
"code": "",
"meesage": ""
},
"target_url": "",
"internal_url": "",
"tracking_code": "null",
"metric_amount": "5.0",
"metric_name": "points",
"acceptance_required": false,
"acceptance_text": "",
"acceptance_url": "null"
},
{
"id": 22,
"internal_name": "testing",
"type": "null",
"description": "null",
"rank": "null",
"campaign_id": 3,
"campaign_rank": 1,
"aggregated_business_value": "0.0",
"start_date": "null",
"end_date": "null",
"response_start_date": "null",
"response_end_date": "null",
"response_schedule": "null",
"trigger_activity_type": "null",
"heading": "<h2>display offers21</h2>",
"subheading": "mobile details subheading ",
"body": "mobile details body ",
"subject": "",
"details": "",
"action": "",
"heading_color": "",
"color": "",
"bgcolor": "",
"heading_bgcolor": "",
"image1_bg": "",
"layout_id": "master",
"image_url": "https://s3.amazonaws.com/stellar-qa-net9b1qlg8vk1v55llub/contents/images/000/000/648/standard/IMG_20150624_151219869.jpg?1435197227",
"thumb_image_url": "https://s3.amazonaws.com/stellar-qa-net9b1qlg8vk1v55llub/contents/images/000/000/648/thumb/IMG_20150624_151219869.jpg?1435197227",
"favorited": false,
"respondable": true,
"respondable_info": {
"value": true,
"code": "",
"message": ""
},
"internal_url": "",
"tracking_code": "null",
"metric_amount": "5.0",
"metric_name": "points",
"acceptance_required": false,
"acceptance_text": "",
"acceptance_url": "null"
}
]
}
}
Lists all offers available to the user.
HTTP Request
GET <base_url>/api/offers
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Accept-Language | string (Multi-lingual Support) | en-US |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| access_token | string (required) | access_token from successful login |
| set | string (optional) | Internal name of a known Offer Set |
| placement | string (optional) | Internal name of a known Placement |
| campaign | string (optional) | Internal name of a known Campaign |
| start_index | Integer (optional) | Start index of the available Offers subset. Used in conjunction with set. |
| end_index | Integer (optional) | End index of the available Offers subset. Used in conjunction with set. |
| category | string (optional) | key from the list of Offer Categories |
| layout | string (optional) | The content layout name. Default is the access token's application name. Example: ios, android |
| Filter Param | ||
| offer_type | string (optional) | Return only matching offer_types based on offer_type parameter. Can be any of 'barcode', 'certificate', 'coupon', 'url' or 'stellar'. |
| respondable | boolean (optional) | If set to true, only offers that can be responded to will be shown. (Default: false) |
| show_clipped | boolean (optional) | If set to true, will show clipped and unclipped offers, false will show unclipped offers only (Default: false) |
| show_target | boolean (optional) | If set to true, targetable attribute that holds a target offer object will be shown. (Default: false) |
| displayable_processing_statuses | string (optional) | Comma-separated string of processing status to be included in the response |
| category | string (optional) | Comma-separated string of category internal names of Offers to include in the response |
| Extra Detail Param | These parameters add extra details and has performance overhead. Please use sparingly. | |
| include_clipped | boolean (optional) | If set to true, is_clipped attribute will be shown. (Default: false) |
| include_responses | boolean (optional) | If set to true, responses(Array) attribute that holds responses details will be shown. (Default: false) |
| result_with_categories | boolean (optional) | Values can be true or false. This parameter will return the category keys of the offer in an array. |
| html | boolean (optional) | If set to true, html attribute that holds html layout will be shown. (Default: false) |
| Sorting Param | ||
| sort_by | string (optional) | Sort options. Values can be updated_at or publish_date or name or points. default: updated_at |
| sort_dir | string (optional) | Sort direction. Values can be desc or asc. default: desc. NOTE: default is desc if sort_by is date otherwise asc |
| page | numeric (optional) | Offset page parameter |
| per_page | numeric (optional) | Number of items per page |
NOTE: default is desc if sort_by is date otherwise asc
Offer by ID
To get a specific offer by ID via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/offers/<id>
If successful, the response should look like this:
{
"success": true,
"data": {
"id": 24,
"type": "barcode",
"description": "null",
"barcode": "1212",
"barcode_std": "Code39",
"target_url": "",
"internal_url": "",
"start_date": "",
"end_date": "",
"heading": "<h2>display offers2</h2>",
"subheading": "mobile details subheading ",
"body": "mobile details body ",
"details": "",
"image_url": "https://s3.amazonaws.com/stellar-qa-net9b1qlg8vk1v55llub/contents/images/000/000/648/standard/IMG_20150624_151219869.jpg?1435197227",
"thumb_image_url": "https://s3.amazonaws.com/stellar-qa-net9b1qlg8vk1v55llub/contents/images/000/000/648/thumb/IMG_20150624_151219869.jpg?1435197227",
"favorited": false
}
}
Allows the user to get a specific offer.
HTTP Request
GET <base_url>/api/offers/<id>
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Accept-Language | string (Multi-lingual Support) | en-US |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| access_token | string (required) | access_token from successful login |
| id | integer (required) | id of a specific offer |
| layout | string (optional) | The content layout name. Default is the access token's application name. Example: ios, android |
| html | boolean (optional) | Values can be true or false. |
| result_with_categories | boolean (optional) | Values can be true or false |
This parameter will return the category keys of the offer in an array.
NOTE: This parameter performs extra database queries. Please use sparingly.
html | boolean (optional) | Values can be true or false.
Offer by Code
To get a specific offer by code via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/offers/
If successful, the response should look like this:
{
"success": true,
"data": {
"id": 40,
"internal_name": "with_certificates",
"type": "certificate",
"description": "null",
"rank": "null",
"campaign_id": "null",
"campaign_rank": "null",
"aggregated_business_value": "0.0",
"start_date": "null",
"end_date": "null",
"response_start_date": "null",
"response_end_date": "null",
"response_schedule": "null",
"trigger_activity_type": "null",
"heading": "with certificates",
"subheading": "null",
"body": "null",
"image_url": "",
"thumb_image_url": "",
"original_image_url": "",
"subject": "null",
"details": "null",
"html": "null",
"action": "null",
"heading_color": "null",
"color": "null",
"bgcolor": "null",
"heading_bgcolor": "null",
"image1_bg": "null",
"layout_id": "null",
"favorited": false,
"respondable": true,
"respondable_info": {
"value": true,
"code": "",
"message": ""
},
"target_url": "https://client-webapp.com/is?p=someencodedstring",
"internal_url": "offer://40",
"tracking_code": "null",
"metric_amount": "0.0",
"metric_name": "points",
"acceptance_required": false,
"acceptance_text": "",
"acceptance_url": "null"
}
}
Lists all offers based on code
HTTP Request
GET <base_url>/api/offers
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Accept-Language | string (Multi-lingual Support) | en-US |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| access_token | string (required) | access_token from successful login |
| code | string (required) | offer code to be searched |
Saved Offers
To get saved offers via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/offers/favorites
If successful, the response should look like this:
{
"success": true,
"data": {
"total_pages": 1,
"total_entries": 1,
"offers": [
{
"id": 24,
"url": "",
"barcode": "1212",
"barcode_std": "Code39",
"target_url": "",
"internal_url": "",
"start_date": "",
"end_date": "",
"heading": "<h2>display offers2</h2>",
"subheading": "mobile details subheading ",
"body": "mobile details body ",
"details": "",
"image_url": "https://s3.amazonaws.com/stellar-qa-net9b1qlg8vk1v55llub/contents/images/000/000/648/standard/IMG_20150624_151219869.jpg?1435197227",
"thumb_image_url": "https://s3.amazonaws.com/stellar-qa-net9b1qlg8vk1v55llub/contents/images/000/000/648/thumb/IMG_20150624_151219869.jpg?1435197227",
"favorited": true
}
]
}
}
Lists all saved offers.
HTTP Request
GET <base_url>/api/offers/favorites
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Accept-Language | string (Multi-lingual Support) | en-US |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| layout | string (optional) | The content layout name. Default is the access token's application name. Example: ios, android |
| html | boolean (optional) | Values can be true or false. |
| page | numeric (optional) | Offset page parameter |
| per_page | numeric (optional) | Number of items per page |
Save/Unsave an Offer
To save an offer via command line, invoke the following
cURLcommand:
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/offers/<id>/favorite
On the other hand, to unsave an offer via command line, invoke the following
cURLcommand:
curl -X DELETE
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/offers/<id>/favorite
If successful, the response for both endpoints should be:
{
"success": true
}
Allows the user to add/remove an offer to the list of favorites.
HTTP Request
POST <base_url>/api/offers/<id>/favorite
DELETE <base_url>/api/offers/<id>/favorite
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Accept-Language | string (Multi-lingual Support) | en-US |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| id | integer (required) | id of a specific offer |
Dismissed Offers
To get dismissed offers via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/offers/dismissed
If successful, the response should look like this:
{
"success": true,
"data": {
"total_pages": 1,
"total_entries": 1,
"offers": [
{
"id": 24,
"url": "",
"barcode": "1212",
"barcode_std": "Code39",
"target_url": "",
"internal_url": "",
"start_date": "",
"end_date": "",
"heading": "<h2>display offers2</h2>",
"subheading": "mobile details subheading ",
"body": "mobile details body ",
"details": "",
"image_url": "https://s3.amazonaws.com/stellar-qa-net9b1qlg8vk1v55llub/contents/images/000/000/648/standard/IMG_20150624_151219869.jpg?1435197227",
"thumb_image_url": "https://s3.amazonaws.com/stellar-qa-net9b1qlg8vk1v55llub/contents/images/000/000/648/thumb/IMG_20150624_151219869.jpg?1435197227",
"favorited": true
}
]
}
}
Lists all dismissed offers.
HTTP Request
GET <base_url>/api/offers/dismissed
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Accept-Language | string (Multi-lingual Support) | en-US |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
Dismiss/Undismiss an Offer
To dismiss an offer via command line, invoke the following
cURLcommand:
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/offers/<id>/dismiss
On the other hand, to undismiss an offer via command line, invoke the following
cURLcommand:
curl -X DELETE
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/offers/<id>/dismiss
If successful, the response for both endpoints should be:
{
"success": true
}
Allows the user to dismiss/undismiss an offer.
HTTP Request
POST <base_url>/api/offers/<id>/dismiss
DELETE <base_url>/api/offers/<id>/dismiss
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Accept-Language | string (Multi-lingual Support) | en-US |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| id | integer (required) | id of a specific offer |
Respond to Offer
There are two ways to respond to offer.
- Responding to offer
idspecified in the request path with valid access_token. - Responding with a
codeparameter that matches either barcode or certificate code from a collection of offers configured in program setting.
Responding to offer id
To respond to an offer with valid access_token via command line, invoke the following
cURLcommand:
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/offers/<id>/respond
If successful, the response should be:
{
"success": true
}
HTTP Request
POST <base_url>/api/offers/<id>/respond
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Accept-Language | string (Multi-lingual Support) | en-US |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| id | integer (required) | id of a specific offer |
Form Parameters
| Parameter | Type | Description |
|---|---|---|
| start_date | date (optional) | Effectivity start_date of the certificate |
| end_date | date (optional) | Effectivity end_date of the certificate |
Responding with a code parameter
To respond with code parameter using access_token via command line, invoke the following
cURLcommand:
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
-F "code=<code>"
<base_url>/api/offers/responses
If successful, the response should be:
{
"success": true
}
To respond with code parameter using email via command line, invoke the following
cURLcommand:
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
-F "email=<email>"
-F "code=<code>"
-F "client_id=<client_id>"
-F "client_secret=<client_secret>"
<base_url>/api/offers/responses
If successful, the response should be:
{
"success": true
}
If email does not match any member, the response should be:
{
"code": 4044,
"name": "not_available",
"message": "Member does not exist"
}
Below are other errors related to code validity, effectivity and limit expected whichever approach is used:
{
"code": 4403,
"name": "not_allowed",
"message": "You have reached the maximum limit of responses per user."
}
{
"code": 5066,
"name": "registration_code_used",
"message": "Registration code is already used."
}
{
"code": 5067,
"name": "registration_code_already_expired",
"message": "Registration code already expired."
}
{
"code": 4942,
"name": "invalid",
"message": "Item is no longer available."
}
If responding outside effectivity period.
{
"code": 4403,
"name": "not_allowed",
"message": "Response period is not satisfied."
}
This endpoint works with valid access_token or existing member's email with client_id & client_secret. This requires offer IDs configured in 'signup_certificate_objects' from program setting (<base_url>/console/program_settings)
HTTP Request
POST <base_url>/api/offers/responses
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Accept-Language | string (Multi-lingual Support) | en-US |
Query Parameters with access_token
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| code | string (required) | access_token from successful login |
Query Parameters without access_token
| Parameter | Type | Description |
|---|---|---|
| code | string (required) | Either offer certificate code or a barcode of an offer |
| string (required) | Email of existing member record | |
| client_id | string (required) | client_id with member scope |
| client_secret | string (required) | client_secret with member scope |
Clip/Unclip an Offer
To clip an offer via command line, invoke the following
cURLcommand:
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/offers/<offer_id>/clip
On the other hand, to unclip an offer via command line, invoke the following
cURLcommand:
curl -X DELETE
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/offers/<offer_id>/clip
If successful, the response for both endpoints should be:
{
"success": true
}
Allows the user to clip/unclip an offer.
HTTP Request
POST <base_url>/api/offers/<offer_id>/clip
DELETE <base_url>/api/offers/<offer_id>/clip
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Accept-Language | string (Multi-lingual Support) | en-US |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| access_token | string (required) | access_token from successful login |
| offer_id | integer (required) | id of Offer |
Offer Responses
To get offer responses via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/offers/responses
If successful, the response should look like this:
{
"success": true,
"data": {
"total_pages": 1,
"total_entries": 2,
"responses": [
{
"id": 42,
"respondable": true
},
{
"id": 41,
"respondable": false,
"secondary_prize": {
"reward": {
"id": 12,
"type": "metric",
"sku": "null",
"draw_date": "null",
"points": "10",
"metric": "points",
"metric_display_name": "Points",
"start_date": "null",
"end_date": "null",
"heading": "Metric Reward",
"subheading": "",
"body": "",
"details": "",
"image_url": "https://s3.amazonaws.com/qyxdn1uk2xgzssjk6wya/contents/357/static_files/7.jpg",
"thumb_image_url": "https://s3.amazonaws.com/qyxdn1uk2xgzssjk6wya/contents/357/static_files/7.jpg",
"original_image_url": "https://s3.amazonaws.com/qyxdn1uk2xgzssjk6wya/contents/357/static_files/7.jpg",
"subject": "",
"action": "",
"heading_color": "",
"color": "null",
"bgcolor": "null",
"heading_bgcolor": "",
"image1_bg": "null",
"layout_id": "master",
"awarded": true,
"favorited": false,
"redeemable": true,
"respondable": true,
"metric_amount": "10",
"metric_name": "points",
"target_url": "null",
"internal_url": "null",
"address_required": false
}
},
"certificate": {
"code": "RRVK-T1VR-J4JD",
"start_date": "null",
"end_date": "null"
}
}
]
}
}
Lists all current user offer responses.
HTTP Request
GET <base_url>/api/offers/responses
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Accept-Language | string (Multi-lingual Support) | en-US |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| access_token | string (required) | access_token from successful login |
| Filter Param | ||
| category | string (optional) | Comma-separated string of category internal names of Offers to include in the response |
| usable | boolean (optional) | Removes unusable responses if true. Defaults tofalse`, i.e. do not filter |
| processing_status | string (optional) | Filter results depending on the requested processing_status. Values can be one of ["pending", "clipped", "processing", "shipping", "completed", "cancelled", "errored", "expired"] |
| placement | string (optional) | Return only responses from requested Placement. Value is the internal name of the Placement. |
| filter_inactive_parents | boolean (optional) | Removes responses that belong to inactive offers if true. Defaults to true |
| Extra Detail Param | These parameters add extra details and has performance overhead. Please use sparingly. | |
| include_clipped | boolean (optional) | If set to true, is_clipped attribute will be shown. (Default: false) |
| result_with_categories | boolean (optional) | Values can be true or false. This parameter will return the category keys of the offer in an array. |
| html | boolean (optional) | If set to true, html attribute that holds html layout will be shown. (Default: false) |
| Sorting Param | ||
| sort_by | string (optional) | Sort options. Values can be updated_at or publish_date or name or points or usage_start or usage_end. default: updated_at |
| sort_dir | string (optional) | Sort direction. Values can be desc or asc. default: desc. NOTE: default is desc if sort_by is date otherwise asc |
| page | numeric (optional) | Offset page parameter |
| per_page | numeric (optional) | Number of items per page |
Offer Response By ID
To get specific offer response via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/offers/responses/<offer_response_id>
If successful, the response should look like this:
{
"success": true,
"data": {
"id": 41,
"respondable": false,
"secondary_prize": {
"reward": {
"id": 12,
"type": "metric",
"sku": "null",
"draw_date": "null",
"points": "10",
"metric": "points",
"metric_display_name": "Points",
"start_date": "null",
"end_date": "null",
"heading": "Metric Reward",
"subheading": "",
"body": "",
"details": "",
"image_url": "https://s3.amazonaws.com/stellar-growingtree-qyxdn1uk2xgzssjk6wya/contents/357/static_files/7.jpg?1477185866",
"thumb_image_url": "https://s3.amazonaws.com/stellar-growingtree-qyxdn1uk2xgzssjk6wya/contents/357/static_files/7.jpg?1477185866",
"original_image_url": "https://s3.amazonaws.com/stellar-growingtree-qyxdn1uk2xgzssjk6wya/contents/357/static_files/7.jpg?1477185866",
"subject": "",
"action": "",
"heading_color": "",
"color": "null",
"bgcolor": "null",
"heading_bgcolor": "",
"image1_bg": "null",
"layout_id": "master",
"awarded": true,
"favorited": false,
"redeemable": true,
"respondable": true,
"metric_amount": "10",
"metric_name": "points",
"target_url": "null",
"internal_url": "null",
"address_required": false
}
},
"certificate": {
"code": "RRVK-T1VR-J4JD",
"start_date": "null",
"end_date": "null"
}
}
}
Get specific offer response.
HTTP Request
GET <base_url>/api/offers/responses/<offer_response_id>
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Accept-Language | string (Multi-lingual Support) | en-US |
Update Offer Response By ID
To update specific offer response via command line, invoke the following
cURLcommand:
curl -X PUT
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/offers/responses/<offer_response_id>
If successful, the response should look like this:
{
"success": true,
"data": {
"id": 157,
"respondable": null,
"processing_status": "completed",
"usage_start_date": null,
"usage_end_date": null,
"usage_schedule": null,
"created_at": "2023-12-14T05:33:34.000Z",
"updated_at": "2023-12-14T05:35:00.468Z",
"order_transaction_id": null,
"offer": {
"id": 10,
"label": "Test Offer",
"internal_name": "test_offer",
"integration_id": null,
"type": "coupon",
"description": "Test Offer",
"rank": null,
"campaign_id": 2,
"campaign_rank": 2,
"business_value": "0.0",
"aggregated_business_value": "0.0",
"start_date": null,
"end_date": null,
"response_start_date": null,
"response_end_date": null,
"response_schedule": null,
"preferred_effectivity_period_tz": false,
"preferred_response_period_tz": false,
"preferred_usage_period_tz": false,
"trigger_activity_type": null,
"heading": "Test Offer",
"subheading": "Subheading",
"body": "Body",
"subject": "",
"details": "Details",
"action": "\n <button> CTA </button>\n ",
"heading_color": "",
"color": "",
"bgcolor": "",
"heading_bgcolor": "",
"image1_bg": "",
"layout_id": "master",
"sections": {},
"image_url": "https://via.placeholder.com/320x240?text=Click%20to%20change%20Image",
"thumb_image_url": "https://via.placeholder.com/320x240?text=Click%20to%20change%20Image",
"original_image_url": "https://via.placeholder.com/320x240?text=Click%20to%20change%20Image",
"favorited": false,
"respondable": true,
"respondable_info": {
"value": true,
"code": "",
"message": ""
},
"extra_json": {},
"target_url": "http://localhost:8080/is?p=JUeyJyZW5kZXJUbyI6IiNzb2NpYWxzaGFyZSIsImltZ1NlbGVjdG9yIjoiLnNob3ctaW1hZ2UgaW1nIiwicHJvZ19pZCI6MSwiY29tcF90eXBlIjoib2ZmZXIiLCJjb21wX2lkIjoxMCwidGl0bGUiOiJCYW5uZXJfU2F2ZSBiaWcgYXQgdGhlIENhc3RsZSEgIiwiZGVzY3JpcHRpb24iOiJTdWJoZWFkaW5nIiwic2l0ZV9uYW1lIjoibG9jYWwiLCJpbWciOiJodHRwczovL3ZpYS5wbGFjZWhvbGRlci5jb20vMzIweDI0MD90ZXh0PUNsaWNrJTIwdG8lMjBjaGFuZ2UlMjBJbWFnZSIsImZ1bGxJbWciOiJodHRwczovL3ZpYS5wbGFjZWhvbGRlci5jb20vMzIweDI0MD90ZXh0PUNsaWNrJTIwdG8lMjBjaGFuZ2UlMjBJbWFnZSIsInNob3dfc3RvcnkiOnRydWUsImxwX3R5cGUiOiJmYWNlYm9vayJ9",
"internal_url": "offer://10",
"tracking_code": null,
"metric_amount": "0.0",
"metric_name": "point",
"acceptance_required": false,
"acceptance_text": "",
"acceptance_url": null
},
"coupon": {
"code": null,
"barcode": null,
"barcode_std": "item_discount"
}
}
}
Update specific offer response.
HTTP Request
PUT <base_url>/api/offers/responses/<offer_response_id>
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Accept-Language | string (Multi-lingual Support) | en-US |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| access_token | string (required) | access_token from successful login |
| offer_response_id | integer (required) | id of offer response |
| processing_status | string (required) | processing_status of offer response that will be updated. |
Clip/Unclip an Offer Response
To clip an offer response via command line, invoke the following
cURLcommand:
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/offers/responses/<offer_response_id>/clip
On the other hand, to unclip an offer response via command line, invoke any of the following
cURLcommands:
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/offers/responses/<offer_response_id>/unclip
curl -X DELETE
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/offers/responses/<offer_response_id>/clip
If successful, the response for the endpoints should be:
{
"success": true
}
Allows the user to clip/unclip an offer response.
HTTP Request
POST <base_url>/api/offers/responses/<offer_response_id>/clip
POST <base_url>/api/offers/responses/<offer_response_id>/unclip
DELETE <base_url>/api/offers/responses/<offer_response_id>/clip
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Accept-Language | string (Multi-lingual Support) | en-US |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| access_token | string (required) | access_token from successful login |
| offer_response_id | integer (required) | id of offer response |
Offer Categories
To get offer categories via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/offers/categories
If successful, the response should look like this:
{
"success": true,
"data": {
"categories": [
{
"key": "latest_offers",
"label": "Latest Offers"
}
]
}
}
Lists all available offer categories.
HTTP Request
GET <base_url>/api/offers/categories
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Accept-Language | string (Multi-lingual Support) | en-US |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
Allocated Offers
To get offers via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/allocated_offers
If successful, the response should look like this:
{
"success": true,
"data": {
"total_pages": 1,
"total_entries": 3,
"offers": [
{
"id": 24,
"internal_name": "display",
"type": "certificate",
"description": "null",
"rank": "null",
"campaign_id": 1,
"campaign_rank": 1,
"aggregated_business_value": "0.0",
"start_date": "null",
"end_date": "null",
"response_start_date": "null",
"response_end_date": "null",
"response_schedule": "null",
"trigger_activity_type": "null",
"heading": "<h2>display</h2>",
"subheading": "mobile details subheading ",
"body": "mobile details body ",
"subject": "",
"details": "",
"action": "",
"heading_color": "",
"color": "",
"bgcolor": "",
"heading_bgcolor": "",
"image1_bg": "",
"layout_id": "master",
"image_url": "https://s3.amazonaws.com/stellar-qa-net9b1qlg8vk1v55llub/contents/images/000/000/648/standard/IMG_20150624_151219869.jpg?1435197227",
"thumb_image_url": "https://s3.amazonaws.com/stellar-qa-net9b1qlg8vk1v55llub/contents/images/000/000/648/thumb/IMG_20150624_151219869.jpg?1435197227",
"favorited": false,
"respondable_info": {
"value": true,
"code": "",
"meesage": ""
},
"target_url": "",
"internal_url": "",
"tracking_code": "null",
"metric_amount": "5.0",
"metric_name": "points",
"acceptance_required": false,
"acceptance_text": "",
"acceptance_url": "null"
},
{
"id": 23,
"type": "url",
"description": "null",
"rank": "null",
"campaign_id": 1,
"campaign_rank": 3,
"aggregated_business_value": "0.0",
"url": "http://katkat.com",
"start_date": "",
"end_date": "",
"response_start_date": "null",
"response_end_date": "null",
"response_schedule": "null",
"trigger_activity_type": "null",
"heading": "<span style=\"background-color: #31a354; color: #c7e9c0;\">display offers</span>",
"subheading": "<span style=\"background-color: #756bb1;\">Master Subheading </span>",
"body": "<span style=\"font-size: 20px; background-color: rgb(49, 130, 189); color: #fd8d3c;\">Master Body</span>",
"details": "",
"action": "",
"heading_color": "",
"color": "",
"bgcolor": "",
"heading_bgcolor": "",
"image1_bg": "",
"layout_id": "master",
"image_url": "https://s3.amazonaws.com/stellar-qa-net9b1qlg8vk1v55llub/contents/images/000/000/604/standard/2mb.jpg?1435114101",
"thumb_image_url": "https://s3.amazonaws.com/stellar-qa-net9b1qlg8vk1v55llub/contents/images/000/000/604/thumb/2mb.jpg?1435114101",
"favorited": false,
"respondable_info": {
"value": true,
"code": "",
"meesage": ""
},
"target_url": "",
"internal_url": "",
"tracking_code": "null",
"metric_amount": "5.0",
"metric_name": "points",
"acceptance_required": false,
"acceptance_text": "",
"acceptance_url": "null"
},
{
"id": 22,
"internal_name": "testing",
"type": "null",
"description": "null",
"rank": "null",
"campaign_id": 3,
"campaign_rank": 1,
"aggregated_business_value": "0.0",
"start_date": "null",
"end_date": "null",
"response_start_date": "null",
"response_end_date": "null",
"response_schedule": "null",
"trigger_activity_type": "null",
"heading": "<h2>display offers21</h2>",
"subheading": "mobile details subheading ",
"body": "mobile details body ",
"subject": "",
"details": "",
"action": "",
"heading_color": "",
"color": "",
"bgcolor": "",
"heading_bgcolor": "",
"image1_bg": "",
"layout_id": "master",
"image_url": "https://s3.amazonaws.com/stellar-qa-net9b1qlg8vk1v55llub/contents/images/000/000/648/standard/IMG_20150624_151219869.jpg?1435197227",
"thumb_image_url": "https://s3.amazonaws.com/stellar-qa-net9b1qlg8vk1v55llub/contents/images/000/000/648/thumb/IMG_20150624_151219869.jpg?1435197227",
"favorited": false,
"respondable": true,
"respondable_info": {
"value": true,
"code": "",
"message": ""
},
"internal_url": "",
"tracking_code": "null",
"metric_amount": "5.0",
"metric_name": "points",
"acceptance_required": false,
"acceptance_text": "",
"acceptance_url": "null"
}
]
}
}
Lists allocated offers available to the user. Allocated Offers are offers from a Campaign that were computed and selected by the Machine Learning Engine based on a predefined model.
Allocated Offers Setup
- Create a Campaign and add/include Offers in the "Offers" tab
- Set up the Audience of the Campaign.
- Set the Campaign's target to a predefined ML Model in the "Targeting" tab
Create and deploy a Member Attribute with an internal name that conforms to this format:
ml_<campaign internal name>_ml_<ml model internal name>. This is where the allocated offers of a member will be stored.Note: Keep the Member Attribute's internal name short, i.e. less than 100 characters. You may override the generated value in the Edit Member Attribute form.
Publish the Campaign
Activate the Campaign as the source of Allocated Offers by providing its internal name in the Active ML Campaign Program Setting.
Specify the number of Allocated Offers that will be listed in Allocated Offers Count Program Setting.
Stretch Offers
Stretch Offers is just a list of offers that will be attached to the list of Allocated Offers.
There are no exact rules or steps to setting this up, since customers and promotions have different requirements.
As long as the Offers are organized in a Campaign, and the Campaign is attached to a Placement, these offers
will be listed in the API response when the proper stretch_placement is provided in the API parameters.
HTTP Request
GET <base_url>/api/allocated_offers
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| access_token | string (required) | access_token from successful login |
| category | string (optional) | key from the list of Offer Categories |
| layout | string (optional) | The content layout name. Default is the access token's application name. Example: ios, android |
| Filter Param | ||
| offer_type | string (optional) | Return only matching offer_types based on offer_type parameter. Can be any of 'barcode', 'certificate', 'coupon', 'url' or 'stellar'. |
| respondable | boolean (optional) | If set to true, only offers that can be responded to will be shown. (Default: false) |
| show_clipped | boolean (optional) | If set to true, will show clipped and unclipped offers, false will show unclipped offers only (Default: false) |
| show_target | boolean (optional) | If set to true, targetable attribute that holds a target offer object will be shown. (Default: false) |
| displayable_processing_statuses | string (optional) | Comma-separated string of processing status to be included in the response |
| category | string (optional) | Comma-separated string of category internal names of Offers to include in the response |
| Extra Detail Param | These parameters add extra details and has performance overhead. Please use sparingly. | |
| stretch_placement | string (optional) | The internal name of the placement containing "stretch" offers. These offerse will be attached to the Allocated Offers list |
| stretch_placement_count | integer (optional) | How many stretch offers to fetch. If not provided, all available stretch offers will be listed. |
| include_clipped | boolean (optional) | If set to true, is_clipped attribute will be shown. (Default: false) |
| include_responses | boolean (optional) | If set to true, responses(Array) attribute that holds responses details will be shown. (Default: false) |
| result_with_categories | boolean (optional) | Values can be true or false. This parameter will return the category keys of the offer in an array. |
| html | boolean (optional) | If set to true, html attribute that holds html layout will be shown. (Default: false) |
Challenges
To get challenges via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/challenges
NOTE TO DEVELOPERS:
metric is for backwards compatibility ONLY. Please use metric_name.
award_amount is for backwards compatibility ONLY. Please use metric_amount.
If successful, the response should look like this:
{
"success": true,
"data": {
"total_pages": 1,
"total_entries": 2,
"challenges": [
{
"id": 2,
"response_type": "survey",
"metric": "point",
"metric_name": "point",
"metric_display_name": "Points",
"metric_amount": "100",
"award_amount": "100",
"start_period": "null",
"end_period": "null",
"heading": "What is the value of Pi?",
"subheading": "",
"body": "",
"details": "",
"image_url": "",
"thumb_image_url": "",
"response_setting": {
"question_type": "numeric",
"question": "What is the value of Pi?",
"survey_options": [],
"image_url": "null",
"maximum_number_of_characters": 0
},
"respondable": true,
"favorited": false,
"target_url": "null",
"internal_url": "null"
},
{
"id": 1,
"response_type": "photo",
"metric": "point",
"metric_name": "point",
"metric_display_name": "Points",
"metric_amount": "100",
"award_amount": "100",
"start_period": "null",
"end_period": "null",
"heading": "Weekend Warriors!",
"subheading": "",
"body": "This is the weekend warrior body<br>Another sweet line of text and<br>more than that...",
"details": "- have to be over 21",
"image_url": "",
"thumb_image_url": "",
"response_setting": {
"resolution": "original"
},
"respondable": true,
"favorited": false,
"target_url": "null",
"internal_url": "null"
}
]
}
}
Lists all challenges available to the user.
Filter challenges of a specific type by passing type param. Retrieve only the list of respondable challenges by setting respondable param to true.
HTTP Request
GET <base_url>/api/challenges
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
| Accept-Language | string (Multi-lingual Support) | en-US |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| type | string (optional) | Values can be Facebook, Photo, Survey or Video |
| respondable | boolean (optional) | Values can be true or false. |
| result_with_categories | boolean (optional) | Values can be true or falseThis parameter will return the category keys of the challenge in an array. NOTE: This parameter performs extra database queries. Please use sparingly. |
| category | string (optional) | key from the list of Challenge Categories |
| layout | string (optional) | The content layout name. Default is the access token's application name. Example: ios, android |
| html | boolean (optional) | Values can be true or false. |
| page | numeric (optional) | Offset page parameter |
| per_page | numeric (optional) | Number of items per page |
| sort_by | string (optional) | Sort options. Values can be updated_at or publish_date or name or points default: updated_at |
| sort_dir | string (optional) | Sort direction. Values can be desc or asc default: desc NOTE: default is desc if sort_by is date otherwise asc |
| show_as_alert | boolean (optional) | Values can be true or false. |
| show_in_list | boolean (optional) | Values can be true or false. |
| New Attribute | Old Attribute | Description |
|---|---|---|
| metric_name | metric | `metric` is for backwards compatibility ONLY. Please use `metric_name`. |
| metric_amount | award_amount | `award_amount` is for backwards compatibility ONLY. Please use `metric_amount`. |
Challenge by ID
To get a specific challenge by ID via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/challenges/<id>
If successful, the response should look like this:
{
"success": true,
"data": {
"id": 2,
"response_type": "survey",
"metric": "point",
"metric_name": "point",
"metric_display_name": "Points",
"metric_amount": "100",
"award_amount": "100",
"start_period": "null",
"end_period": "null",
"heading": "What is the value of Pi?",
"subheading": "",
"body": "",
"details": "",
"image_url": "",
"thumb_image_url": "",
"response_setting": {
"question_type": "numeric",
"question": "What is the value of Pi?",
"survey_options": [],
"image_url": "null",
"maximum_number_of_characters": 0
},
"respondable": true,
"favorited": true,
"target_url": "null",
"internal_url": "null"
}
}
Allows the user to get a specific challenge.
NOTE TO DEVELOPERS:
metric is for backwards compatibility ONLY. Please use metric_name.
award_amount is for backwards compatibility ONLY. Please use metric_amount.
HTTP Request
GET <base_url>/api/challenges/<id>
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
| Accept-Language | string (Multi-lingual Support) | en-US |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| id | integer (required) | id of a specific challenge |
| layout | string (optional) | The content layout name. Default is the access token's application name. Example: ios, android |
| html | boolean (optional) | Values can be true or false. |
| result_with_categories | boolean (optional) | Values can be true or falseThis parameter will return the category keys of the challenge in an array. NOTE: This parameter performs extra database queries. Please use sparingly. |
| show_poll_result | boolean (optional) | Values can be true or false. Default is false.Applicable to MultiQuestion survey type only. This parameter will return the current poll results for multiple choice surveys. NOTE: This parameter performs extra database queries. Please use sparingly. |
| New Attribute | Old Attribute | Description |
|---|---|---|
| metric_name | metric | `metric` is for backwards compatibility ONLY. Please use `metric_name`. |
| metric_amount | award_amount | `award_amount` is for backwards compatibility ONLY. Please use `metric_amount`. |
Response Setting
Different challenges have different response setting when GET challege by ID is used. Listed below are the challenge types with special parameters to be passed for them to work.
Sample response_setting for check-in challenge
{
"response_setting": {
"nearest": {
"id": 24,
"name": "flair_towers",
"label": "Flair Towers",
"place_id": "ChIJcxrwytC1lzMR-9FTsD75Xn0",
"address": "Flair Towers-DMCI Projects Online, Mandaluyong, NCR, Philippines",
"country_code": "ph",
"zip_code": "",
"phone": "",
"latitude": "14.574058",
"longitude": "121.05354399999999",
"operating_hours": "",
"radius": 100,
"radius_unit": "m",
"distance": "503.8776"
}
}
}
Check-In Challenge
In Check-In challenge type, special headers must be passed for the nearest location to be resolved and returned.
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
| Sl-User-Location | json (required) | { "lat": "14.575022", "lon": "121.0489723" } |
| Accept-Language | string (Multi-lingual Support) | en-US |
Multi-Question Survey Challenge
To show poll results for a multi-question survey:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
-F "show_poll_request=true"
<base_url>/api/challenges/<id>
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| show_poll_result | boolean (optional) | Values can be true or false. Default is false.Applicable to MultiQuestion survey type only. This parameter will return the current poll results for multiple choice surveys. NOTE: This parameter performs extra database queries. Please use sparingly. |
Simplified (other attributes not shown) response for multi-question survey that shows poll results:
{
"success": true,
"data": {
"id": 1,
"response_type": "multi_question",
"response_setting": {
"definitions": [
{
"id": 20,
"type": "multiple_choice_question",
"question": "Best X-Men?",
"options": [
{
"id": 21,
"label": "Cyclops",
"image_url": "",
"thumb_image_url": "",
"original_image_url": ""
},
{
"id": 22,
"label": "Wolverine",
"image_url": "",
"thumb_image_url": "",
"original_image_url": ""
},
{
"id": 23,
"label": "Rogue",
"image_url": "",
"thumb_image_url": "",
"original_image_url": ""
},
{
"id": 24,
"label": "Storm",
"image_url": "",
"thumb_image_url": "",
"original_image_url": ""
},
{
"id": 25,
"label": "Jean Grey",
"image_url": "",
"thumb_image_url": "",
"original_image_url": ""
}
]
}
]
},
"poll_result": [
{
"id": 20,
"question": "Best X-Men?",
"question_id": "77f844fec2ad119fac1848585a4a8a",
"results": [
{
"id": 21,
"label": "Cyclops",
"total": 0,
"percentage": "0.00"
},
{
"id": 22,
"label": "Wolverine",
"total": 0,
"percentage": "0.00"
},
{
"id": 23,
"label": "Rogue",
"total": 0,
"percentage": "0.00"
},
{
"id": 24,
"label": "Storm",
"total": 1,
"percentage": "33.33"
},
{
"id": 25,
"label": "Jean Grey",
"total": 2,
"percentage": "66.67"
}
]
}
]
}
}
Saved Challenges
To get saved challenges via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/challenges/favorites
If successful, the response should look like this:
{
"success": true,
"data": {
"total_pages": 1,
"total_entries": 1,
"challenges": [
{
"id": 2,
"response_type": "survey",
"metric": "point",
"metric_name": "point",
"metric_display_name": "Points",
"metric_amount": "100",
"award_amount": "100",
"start_period": "null",
"end_period": "null",
"heading": "What is the value of Pi?",
"subheading": "",
"body": "",
"details": "",
"image_url": "",
"thumb_image_url": "",
"response_setting": {
"question_type": "numeric",
"question": "What is the value of Pi?",
"survey_options": [],
"image_url": "null",
"maximum_number_of_characters": 0
},
"respondable": true,
"favorited": true,
"target_url": "null",
"internal_url": "null"
}
]
}
}
Lists all saved challenges.
HTTP Request
GET <base_url>/api/challenges/favorites
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
| Accept-Language | string (Multi-lingual Support) | en-US |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| layout | string (optional) | The content layout name. Default is the access token's application name. Example: ios, android |
| html | boolean (optional) | Values can be true or false. |
| page | numeric (optional) | Offset page parameter |
| per_page | numeric (optional) | Number of items per page |
Save/Unsave a Challenge
To add a challenge to user favorites via command line, invoke the following
cURLcommand:
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/challenges/<id>/favorite
On the other hand, to remove a challenge from user favorites via command line, invoke the following
cURLcommand:
curl -X DELETE
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/challenges/<id>/favorite
If successful, the response for both endpoints should be:
{
"success": true
}
Allows the user to add/remove a challenge to the list of favorites.
HTTP Request
POST <base_url>/api/challenges/<id>/favorite
DELETE <base_url>/api/challenges/<id>/favorite
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
| Accept-Language | string (Multi-lingual Support) | en-US |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| id | integer (required) | id of a specific challenge |
Dismissed Challenges
To get dismissed challenges via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/challenges/dismissed
If successful, the response should look like this:
{
"success": true,
"data": {
"total_pages": 1,
"total_entries": 1,
"challenges": [
{
"id": 2,
"response_type": "survey",
"metric": "point",
"metric_name": "point",
"metric_display_name": "Points",
"metric_amount": "100",
"award_amount": "100",
"start_period": "null",
"end_period": "null",
"heading": "What is the value of Pi?",
"subheading": "",
"body": "",
"details": "",
"image_url": "",
"thumb_image_url": "",
"response_setting": {
"question_type": "numeric",
"question": "What is the value of Pi?",
"survey_options": [],
"image_url": "null",
"maximum_number_of_characters": 0
},
"respondable": true,
"favorited": true,
"target_url": "null",
"internal_url": "null"
}
]
}
}
Lists all dismissed challenges.
HTTP Request
GET <base_url>/api/challenges/dismissed
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
| Accept-Language | string (Multi-lingual Support) | en-US |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
Dismiss/Undismiss a Challenge
To dismiss a challenge via command line, invoke the following
cURLcommand:
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/challenges/<id>/dismiss
On the other hand, to undismiss a challenge via command line, invoke the following
cURLcommand:
curl -X DELETE
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/challenges/<id>/dismiss
If successful, the response for both endpoints should be:
{
"success": true
}
Allows the user to dismiss/undismiss a challenge.
HTTP Request
POST <base_url>/api/challenges/<id>/dismiss
DELETE <base_url>/api/challenges/<id>/dismiss
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
| Accept-Language | string (Multi-lingual Support) | en-US |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| id | integer (required) | id of a specific challenge |
Respond
To respond challenge via command line with items array using query params, invoke the following
cURLcommand:
curl -X POST \
'<base_url>/api/challenges/<id>/respond?answer[text]=dddd&answer[items][][id]=388,387&answer[items][][value]=2,5'
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
-H 'Content-Type: application/x-www-form-urlencoded'
If a Challenge has a Secondary Prize (metric, award, or contest) the response will contain this information:
Secondary Award / Contest Prizes
Data for both Award and Contest prizes will go under the reward attribute, distinguished only by their type.
json
{
"success":true,
"data":{
"challenge_response":{
"id":1,
"status":"approved"
},
"challenge_respondable":true,
"secondary_prize":{
"reward":{
"id":11,
"type":"certificate",
"sku":"null",
"draw_date":"null",
"points":"10000",
"metric_amount":"10000",
"metric":"point",
"metric_name":"point",
"metric_display_name":"Points",
"start_date":"null",
"end_date":"null",
"heading":"CERT",
"subheading":"",
"body":"",
"details":"",
"image_url":"",
"thumb_image_url":"",
"original_image_url":"",
"layout_id":"master",
"awarded":false,
"favorited":false,
"redeemable":true,
"respondable":true,
"target_url":"null",
"internal_url":"null",
"address_required":false
}
}
}
}
Secondary Metric Prize
Example JSON
{
"success": true,
"data": {
"challenge_response": {
"id": 1,
"status": "approved"
},
"challenge_respondable": true,
"secondary_prize": {
"amount": "99.0",
"metric": {
"id": 5,
"name": "point",
"label": "Point",
"description": "",
"type": "Point",
"decimal_place": 0,
"code": "Pw",
"expirable": false
}
}
}
}
Data for Metric prize will go under the metric attribute, but unlike Award and Contest, it will have an accompanying attribute amount containing the metric amount value.
If the Challenge does NOT have a Secondary Prize defined, the secondary_prize attribute will not be present.
Respond (Text-Only)
To respond to a Survey-Text-type challenge via command line, invoke the following
cURLcommand:
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
-F "answer[text]=<string text response>"
<base_url>/api/challenges/<id>/respond
If successful, the response should look like this:
{
"success": true,
"data": {
"challenge_response": {
"id": 1,
"status": "approved"
},
"challenge_respondable": true,
"secondary_prize": {}
}
}
Allows the user to respond to a text-only challenge.
HTTP Request
POST <base_url>/api/challenges/<id>/respond
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
| Accept-Language | string (Multi-lingual Support) | en-US |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| id | integer (required) | id of a specific challenge |
Form Parameters
| Parameter | Type | Description |
|---|---|---|
| answer[text] | string (required) | Text response to the challenge |
| answer[comment] | string (optional) | Comment (available for Rating Survey Type only) |
Respond (List of Strings)
To respond to a Survey-Multiple Choice-type challenge via command line, invoke the following
cURLcommand:
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
-F "answer[text][]=<array list of strings>"
<base_url>/api/challenges/<id>/respond
If successful, the response should look like this:
{
"success": true,
"data": {
"challenge_response": {
"id": 1,
"status": "approved"
},
"challenge_respondable": true,
"secondary_prize": {}
}
}
Allows the user to respond to a list of strings challenge.
HTTP Request
POST <base_url>/api/challenges/<id>/respond
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
| Accept-Language | string (Multi-lingual Support) | en-US |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| id | integer (required) | id of a specific challenge |
Form Parameters
| Parameter | Type | Description |
|---|---|---|
| answer[text][] | array (required) | List of strings |
Respond (Text and Image)
To respond to a Photo-type or Facebook-type challenge via command line, invoke the following
cURLcommand:
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/challenges/<id>/respond
If successful, the response should look like this:
{
"success": true,
"data": {
"challenge_response": {
"id": 1,
"status": "approved"
},
"challenge_respondable": true,
"secondary_prize": {}
}
}
Allows the user to respond to a Photo-type or Facebook-type challenge.
HTTP Request
POST <base_url>/api/challenges/<id>/respond
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
| Accept-Language | string (Multi-lingual Support) | en-US |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| id | integer (required) | id of a specific challenge |
Form Parameters
| Parameter | Type | Description |
|---|---|---|
| answer[text] | string (required) | Caption of the photo |
| answer[attachment] | string (required) | Photo response to the challenge |
Respond (Text and Video)
To respond to a Video-type challenge via command line, invoke the following
cURLcommand:
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/challenges/<id>/respond
If successful, the response should look like this:
{
"success": true,
"data": {
"challenge_response": {
"id": 1,
"status": "approved"
},
"challenge_respondable": true,
"secondary_prize": {}
}
}
Allows the user to respond to a Video-type challenge.
HTTP Request
POST <base_url>/api/challenges/<id>/respond
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
| Accept-Language | string (Multi-lingual Support) | en-US |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| id | integer (required) | id of a specific challenge |
Form Parameters
| Parameter | Type | Description |
|---|---|---|
| answer[text] | string (required) | Caption of the photo |
| answer[attachment] | string (required) | Video response to the challenge |
Respond (Update Profile)
To respond by updating profile via command line, invoke the following
cURLcommand:
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/challenges/<id>/respond
If successful, the response should look like this:
{
"success": true,
"data": {
"challenge_response": {
"id": 1,
"status": "approved"
},
"challenge_respondable": true,
"secondary_prize": {}
}
}
Allows the user to respond to a challenge by updating profile.
HTTP Request
POST <base_url>/api/challenges/<id>/respond
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
| Accept-Language | string (Multi-lingual Support) | en-US |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| id | integer (required) | id of a specific challenge |
Form Parameters
| Parameter | Type | Description |
|---|---|---|
answer[preference][<member_preference_attribute>] |
string | Value of member preference attribute to update |
answer[profile][<member_profile_attribute>] |
string | Value of member profile attribute to update |
Member Profile - allows multiple attributes to be updated
answer[profile][first_name] = 'Will'
answer[profile][last_name] = 'Byers'
Member Preference - now supports multiple preferences to update
# single value preference
answer[preference][brands] = 'Nike'
# multi-value preference
answer[preference][things][] = 'Thing1'
answer[preference][things][] = 'Thing2'
# for preference with custom domain, just pass it like any ordinary value:
# i.e. options include: cat, fish
answer[preference][pets][] = 'bear'
answer[preference][pets][] = 'fish'
# If multiple preferences are to be updated, you can mix up by passing:
answer[preference][brands] = 'Nike'
answer[preference][things][] = 'Thing1'
answer[preference][things][] = 'Thing2'
Respond (Photo Caption / Meme)
To respond to a Photo-Caption-type Challenge via command line, invoke the following
cURLcommand:
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/challenges/<id>/respond
If successful, the response should look like this:
{
"success": true,
"data": {
"challenge_response": {
"id": 1,
"status": "approved"
},
"challenge_respondable": true,
"secondary_prize": {}
}
}
Allows the user to respond by sending a meme/photo caption.
HTTP Request
POST <base_url>/api/challenges/<id>/respond
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
| Accept-Language | string (Multi-lingual Support) | en-US |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| id | integer (required) | id of a specific challenge |
Form Parameters
| Parameter | Type | Description |
|---|---|---|
| answer[attachment] | string (required) | Photo response to the challenge |
| answer[text] | string (optional) | Text response to the challenge |
Respond (View Content)
To respond (by viewing) to a content Challenge via command line, invoke the following
cURLcommand:
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/challenges/<id>/respond
If successful, the response should look like this:
{
"success": true,
"data": {
"challenge_response": {
"id": 1,
"status": "approved"
},
"challenge_respondable": true,
"secondary_prize": {. . .}
}
}
Allows the user to respond by viewing a content-- a URL, YouTube link or Photo.
HTTP Request
POST <base_url>/api/challenges/<id>/respond
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
| Accept-Language | string (Multi-lingual Support) | en-US |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| id | integer (required) | id of a specific challenge |
Form Parameters
| Parameter | Type | Description |
|---|---|---|
| answer[attachment] | string (optional) | Photo response to the challenge |
| answer[text] | string (optional) | Text response to the challenge |
Respond (Join Group)
To respond by joining group via command line, invoke the following
cURLcommand:
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/challenges/<id>/respond
If successful, the response should look like this:
{
"success": true,
"data": {
"challenge_response": {
"id": 1,
"status": "approved"
},
"challenge_respondable": true,
"secondary_prize": {}
}
}
Allows the user to respond to a challenge by joining group.
HTTP Request
POST <base_url>/api/challenges/<id>/respond
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
| Accept-Language | string (Multi-lingual Support) | en-US |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| id | integer (required) | id of a specific challenge |
Form Parameters
| Parameter | Type | Description |
|---|---|---|
| answer[text] | string (optional) | Text response to the challenge |
| answer[group_id][] | array (required) | Array of group IDs (May contain 1 or more IDs) |
Respond (Check-In)
To respond by checking-in to a location via command line, invoke the following
cURLcommand:
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/challenges/<id>/respond
If successful, the response should look like this:
{
"success": true,
"data": {
"challenge_response": {
"id": 1,
"status": "approved"
},
"challenge_respondable": true,
"secondary_prize": {}
}
}
Allows the user to respond to a challenge by checking-in to a location
HTTP Request
POST <base_url>/api/challenges/<id>/respond
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
| Accept-Language | string (Multi-lingual Support) | en-US |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| id | integer (required) | id of a specific challenge |
Form Parameters
| Parameter | Type | Description |
|---|---|---|
| answer[text] | string (optional) | Text response to the challenge |
| answer[location_id] | integer (required) | ID of location to check into |
Respond (Multi-Question)
To respond to multi_question a location via command line with JSON body, invoke the following
cURLcommand:
curl -X POST \
'<base_url>/api/challenges/<id>/respond?show_poll_result=true' \
-H 'accept: application/vnd.stellar-v1+json' \
-H 'authorization: Bearer <access_token>' \
-H 'content-type: application/json' \
-d '{
"answer": {
"text": "Whatever. If surveys allow commenting.",
"items": [
{
"id": 20,
"value": 22
}
]
}
}'
To respond to multi_question a location via command line with form parameters, invoke the following
cURLcommand:
curl -X POST \
'<base_url>/api/challenges/<id>/respond?show_poll_result=true' \
-H 'accept: application/vnd.stellar-v1+json' \
-H 'authorization: Bearer <access_token>' \
-H 'content-type: application/json' \
-F 'answer[text]=Whatever. If surveys allow commenting.' \
-F 'answer[items][][id]=20' \
-F 'answer[items][][value]=22'
If successful, the response should look like this:
{
"success": true,
"data": {
"challenge_response": {
"id": 201,
"status": "approved",
"approval_status": "approved"
},
"challenge_respondable": true,
"respondable_info": {
"value": true,
"code": "null",
"message": "null"
},
"response_message": "null",
"poll_result": [
{
"id": 20,
"question": "Best X-Men?",
"question_id": "77f844fec2ad119fac1848585a4a8a",
"results": [
{
"id": 21,
"label": "Cyclops",
"total": 0,
"percentage": "0.00"
},
{
"id": 22,
"label": "Wolverine",
"total": 1,
"percentage": "25.00"
},
{
"id": 23,
"label": "Rogue",
"total": 0,
"percentage": "0.00"
},
{
"id": 24,
"label": "Storm",
"total": 1,
"percentage": "25.00"
},
{
"id": 25,
"label": "Jean Grey",
"total": 2,
"percentage": "50.00"
}
]
}
]
}
}
HTTP Request
POST <base_url>/api/challenges/<id>/respond
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
| Accept-Language | string (Multi-lingual Support) | en-US |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| id | integer (required) | id of a specific challenge |
| show_poll_result | boolean (optional) | Default is false. |
See the sample cURL request on the right side.
Respond (Custom)
To respond to a content Challenge via command line, invoke the following
cURLcommand:
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/challenges/<id>/respond
If successful, the response should look like this:
{
"success": true,
"data": {
"challenge_response": {
"id": 1,
"status": "approved"
},
"challenge_respondable": true,
"secondary_prize": {}
}
}
Definition Example
{
"action": {
"url": "https://meetmarigold.com",
"target": "comments"
},
"response": {
"isbn": {
"unique": true,
"type": "string",
"length": 3
},
"comments": {
"type": "string"
}
}
}
Allows the user to respond by submitting a JSON string.
HTTP Request
POST <base_url>/api/challenges/<id>/respond
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
| Accept-Language | string (Multi-lingual Support) | en-US |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| id | integer (required) | id of a specific challenge |
Form Parameters
| Parameter | Type | Description |
|---|---|---|
| answer[text] | string (optional) | JSON response to the challenge |
Approval Rules for Response
Supported Validation Rules in our JSON definition (as of this writing):
| Attribute | Type |
|---|---|
| unique | boolean |
| type | string |
| length | integer |
Supported types are: integer, string, array, boolean
JSON schema checking is mandatory. Invalid JSON schema or structure will return an error.
If no rules are needed, one can just define {} (an empty hash).
The most important thing in the JSON definition is to hook the "approval rules" to the "response" attribute. All other attributes not hooked to this will not be considered. See definition example on the right.
A valid response for the definition above is something like this.
{ "isbn": "123", "comments": "Hello from the other side." }
If no rules are needed but, you want to make sure the attributes are present, you can define something like:
{ "response": "isbn": {}, "lelz": {} }
Re-enter a Response
To re-enter a response to a challenge via command line, invoke the following
cURLcommand:
curl -X PUT
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/challenges/<id>/responses/<response_id>
If successful, the response should look like this:
{
"success": true,
"data": {
"challenge_response": true,
"challenge_respondable": true
}
}
Allows the user to re-enter a response to a challenge he/she previously responded to.
Note that this is only allowed if the initial response was returned/unapproved.
HTTP Request
PUT <base_url>/api/challenges/<id>/responses/<response_id>
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
| Accept-Language | string (Multi-lingual Support) | en-US |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| id | integer (required) | id of a specific challenge |
| response_id | integer (required) | id of a response to be updated |
Form Parameters
| Parameter | Type | Description |
|---|
*** Use the same parameters same as sending a response for a specific challenge type ***
Challenge Responses
To get challenge responses via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/challenges/reponses
If successful, the response should look like this:
{
"success": true,
"data": {
"total_pages": 1,
"total_entries": 1,
"responses": [
{
"id": 1,
"response": "Go Warriors!",
"attachment_url": "https://s3.amazonaws.com/stellar/standard/minion_bananas-2560x1440.jpg?1435114668",
"status": "approved",
"comments": [],
"created_at": "2015-12-01T08:41:33.000Z",
"updated_at": "2015-12-01T08:41:33.000Z",
"challenge": {
"id": 5,
"response_type": "photo",
"metric": "point",
"metric_name": "point",
"metric_display_name": "Points",
"metric_amount": "100",
"award_amount": "100",
"start_period": "null",
"end_period": "null",
"heading": "Weekend Warriors!",
"subheading": "",
"body": "This is the weekend warrior body<br>Another sweet line of text and<br>more than that...",
"details": "- have to be over 21",
"image_url": "",
"thumb_image_url": "",
"response_setting": {
"resolution": "original"
},
"respondable": true,
"favorited": false,
"target_url": "null",
"internal_url": "null"
}
}
]
}
}
Lists all challenge responses made by the user.
Filter challenge responses of a specific type by passing type param.
HTTP Request
GET <base_url>/api/challenges/responses
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
| Accept-Language | string (Multi-lingual Support) | en-US |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| type | string (optional) | Values can be Facebook, Photo, Survey or Video |
| layout | string (optional) | The content layout name. Default is the access token's application name. Example: ios, android |
| page | numeric (optional) | Offset page parameter |
| per_page | numeric (optional) | Number of items per page |
Challenge Response by ID
To get a specific challenge response by ID via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/challenges/responses/<id>
If successful, the response should look like this:
{
"success": true,
"data": {
"id": 8,
"response": "4",
"attachment_url": "https://s3.amazonaws.com/stellar/standard/minion_bananas-2560x1440.jpg?1435114668",
"status": "approved",
"comments": [],
"created_at": "2015-12-01T08:41:33.000Z",
"updated_at": "2015-12-01T08:41:33.000Z",
"challenge": {
"id": 5,
"response_type": "photo",
"metric": "point",
"metric_name": "point",
"metric_display_name": "Points",
"metric_amount": "100",
"award_amount": "100",
"start_period": "null",
"end_period": "null",
"heading": "Weekend Warriors!",
"subheading": "",
"body": "This is the weekend warrior body<br>Another sweet line of text and<br>more than that...",
"details": "- have to be over 21",
"image_url": "",
"thumb_image_url": "",
"response_setting": {
"resolution": "original"
},
"respondable": true,
"favorited": false,
"target_url": "null",
"internal_url": "null"
}
}
}
Allows the user to get a specific challenge response made by the user.
HTTP Request
GET <base_url>/api/challenges/responses/<id>
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
| Accept-Language | string (Multi-lingual Support) | en-US |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| id | integer (required) | id of a specific challenge response |
| layout | string (optional) | The content layout name. Default is the access token's application name. Example: ios, android |
Challenge Categories
To get challenge categories via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/challenges/categories
If successful, the response should look like this:
{
"success": true,
"data": {
"categories": [
{
"key": "latest_challenges",
"label": "Latest Challenges"
}
]
}
}
Lists all available challenge categories.
HTTP Request
GET <base_url>/api/challenges/categories
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
| Accept-Language | string (Multi-lingual Support) | en-US |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
Rewards
To get rewards via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/rewards
NOTE TO DELEVELOPERS:
metric is for backwards compatibility ONLY. Please use metric_name.
points is for backwards compatibility ONLY. Please use metric_amount.
redeemable is for backwards compatibility ONLY. Please use respondable.If successful, the response should look like this:
{
"success": true,
"data": {
"total_pages": 1,
"total_entries": 2,
"rewards": [
{
"id": 2,
"type": "product",
"sku": "null",
"draw_date": "null",
"points": "100",
"metric_amount": "100",
"metric": "point",
"metric_name": "point",
"metric_display_name": "Points",
"start_date": "null",
"end_date": "null",
"heading": "Today's Reward",
"subheading": "T-Shirt",
"body": "",
"details": "",
"image_url": "https://s3.amazonaws.com/stellar-growingtree-qyxdn1uk2xgzssjk6wya/contents/images/000/005/399/standard/__35.JPG?1449109087",
"thumb_image_url": "https://s3.amazonaws.com/stellar-growingtree-qyxdn1uk2xgzssjk6wya/contents/images/000/005/399/thumb/__35.JPG?1449109087",
"awarded": false,
"favorited": false,
"business_value": "$1.0",
"redeemable": true,
"respondable": true,
"target_url": "null",
"internal_url": "null"
},
{
"id": 1,
"type": "certificate",
"sku": "null",
"draw_date": "null",
"points": "0",
"metric_amount": "0",
"metric": "point",
"metric_name": "point",
"metric_display_name": "Points",
"start_date": "null",
"end_date": "null",
"heading": "Promo Codes",
"subheading": "",
"body": "",
"details": "",
"image_url": "",
"thumb_image_url": "",
"awarded": false,
"favorited": false,
"business_value": "$1.0",
"redeemable": true,
"respondable": true,
"target_url": "null",
"internal_url": "null"
}
]
}
}
Lists all rewards available to the user.
HTTP Request
GET <base_url>/api/rewards
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
| Accept-Language | string (Multi-lingual Support) | en-US |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| category | string (optional) | key from the list of Reward Categories |
| layout | string (optional) | The content layout name. Default is the access token's application name. Example: ios, android |
| html | boolean (optional) | Values can be true or false. |
| page | numeric (optional) | Offset page parameter |
| per_page | numeric (optional) | Number of items per page |
| result_with_categories | boolean (optional) | Values can be true or falseThis parameter will return the category keys of the reward in an array. NOTE: This parameter performs extra database queries. Please use sparingly. |
| result_with_response_count | boolean (optional) | Values can be true or false, default is falseThis parameter will return another attribute response_count by the current member. NOTE: This parameter performs extra database queries. Please use sparingly. |
| min_response_count | Integer (optional) | Value should be a value greater than zero. Returns rewards responded by current member equal or greater than min_response_count |
| sort_by | string (optional) | Sort options. Values can be update_date, rank, publish_date, name, label, aggregated_business_value, points, earned_metric, required_metric, start_at, effectivity_start or effectivity_enddefault: updated_at |
| sort_dir | string (optional) | Sort direction. Values can be desc or asc default: desc NOTE: default is desc if sort_by is date otherwise asc |
| New Attribute | Old Attribute | Description |
|---|---|---|
| metric_name | metric | `metric` is for backwards compatibility ONLY. Please use `metric_name`. |
| metric_amount | points | `points` is for backwards compatibility ONLY. Please use `metric_amount`. |
| respondable | redeemable | `redeemable` is for backwards compatibility ONLY. Please use `respondable`. |
Reward by ID
To get a specific reward by ID via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/rewards/<id>
NOTE TO DEVELOPERS:
metric is for backwards compatibility ONLY. Please use metric_name.
points is for backwards compatibility ONLY. Please use metric_amount.
redeemable is for backwards compatibility ONLY. Please use respondable.If successful, the response should look like this:
{
"success": true,
"data": {
"id": 2,
"type": "product",
"sku": "null",
"points": "100",
"metric_amount": "100",
"metric": "point",
"metric_name": "point",
"metric_display_name": "Points",
"start_date": "null",
"end_date": "null",
"heading": "Today's Reward",
"subheading": "T-Shirt",
"body": "",
"details": "",
"image_url": "https://s3.amazonaws.com/stellar-growingtree-qyxdn1uk2xgzssjk6wya/contents/images/000/005/399/standard/__35.JPG?1449109087",
"thumb_image_url": "https://s3.amazonaws.com/stellar-growingtree-qyxdn1uk2xgzssjk6wya/contents/images/000/005/399/thumb/__35.JPG?1449109087",
"awarded": false,
"favorited": false,
"business_value": "$1.0",
"redeemable": true,
"respondable": true,
"target_url": "null",
"internal_url": "null"
}
}
The example above shows a basic reward. If the reward has a combination, the reward_attributes and reward_configuration will have contents like:
"reward_attributes": [
{
"id": 5,
"label": "color",
"attribute_options": [
{
"id": 9,
"label": "red",
"default": false
},
{
"id": 10,
"label": "blue",
"default": false
},
{
"id": 18,
"label": "yellow",
"default": false
}
]
},
{
"id": 20,
"label": "Engine Type",
"attribute_options": [
{
"id": 39,
"label": "Manual",
"default": false
},
{
"id": 40,
"label": "Automatic",
"default": false
}
]
}
]
The reward_configuration contains all the possible combination for the reward. Below is a sample:
"reward_configuration": [
{
"id": 621,
"attribute_combination": [
"red",
"Manual"
],
"metric_name": "point",
"metric_amount": "1",
"sku": "1306-01",
"image_url": "",
"thumb_image_url": "",
"respondable": true
},
{
"id": 622,
"attribute_combination": [
"red",
"Automatic"
],
"metric_name": "point",
"metric_amount": "130",
"sku": "AW-Red-AT-0001",
"image_url": "",
"thumb_image_url": "",
"respondable": true
},
{
"id": 623,
"attribute_combination": [
"blue",
"Manual"
],
"metric_name": "point",
"metric_amount": "1",
"sku": "1306-01",
"image_url": "",
"thumb_image_url": "",
"respondable": true
},
{
"id": 624,
"attribute_combination": [
"blue",
"Automatic"
],
"metric_name": "point",
"metric_amount": "1",
"sku": "1306-01",
"image_url": "",
"thumb_image_url": "",
"respondable": true
},
{
"id": 625,
"attribute_combination": [
"yellow",
"Manual"
],
"metric_name": "point",
"metric_amount": "1",
"sku": "1306-01",
"image_url": "",
"thumb_image_url": "",
"respondable": true
},
{
"id": 626,
"attribute_combination": [
"yellow",
"Automatic"
],
"metric_name": "point",
"metric_amount": "1",
"sku": "1306-01",
"image_url": "",
"thumb_image_url": "",
"respondable": true
}
]
The example below shows the reward if product type and classes validation is required. Please note that there are still other data being returned.
required_attributesis are the relevant JSON key here.
{
"success": true,
"data": {
"id": 1,
"type": "product",
"sku": "null",
"rank": "null",
"draw_date": "null",
"points": "0",
"metric": "points",
"metric_display_name": "Points",
"start_date": "null",
"end_date": "null",
"heading": "REWARD FOR KAT",
"subheading": "",
"body": "",
"details": "",
"image_url": "",
"thumb_image_url": "",
"original_image_url": "",
"subject": "",
"action": "",
"heading_color": "",
"color": "",
"bgcolor": "",
"heading_bgcolor": "",
"image1_bg": "",
"layout_id": "master",
"awarded": false,
"favorited": false,
"redeemable": true,
"respondable": true,
"respondable_info": {
"value": true,
"code": "null",
"message": "null"
},
"required_attributes": [
{
"id": 8,
"name": "kat_class",
"label": "KAT CLASS",
"status": "published",
"description": "",
"reward_attributes": [
{
"name": "store_code",
"label": "Store Code",
"data_type": "string",
"attribute_options": [
{
"id": 21,
"code": "123",
"label": "Kat Makati",
"default": true,
"hint": "THIS IS THE MAIN BRANCH"
},
{
"id": 22,
"code": "456",
"label": "Kat Megamall",
"default": false,
"hint": ""
}
]
}
]
}
],
"reward_attributes": [],
"reward_configuration": [],
"business_value": "0.0",
"metric_amount": "0",
"metric_name": "points",
"target_url": "null",
"internal_url": "null",
"address_required": true,
"response_message": "",
"acceptance_required": false,
"acceptance_text": "null",
"acceptance_url": "null"
}
}
Allows the user to get a specific reward.
HTTP Request
GET <base_url>/api/rewards/<id>
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
| Accept-Language | string (Multi-lingual Support) | en-US |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| id | integer (required) | id of a specific reward |
| layout | string (optional) | The content layout name. Default is the access token's application name. Example: ios, android |
| html | boolean (optional) | Values can be true or false. |
| result_with_categories | boolean (optional) | Values can be true or falseThis parameter will return the category keys of the reward in an array. NOTE: This parameter performs extra database queries. Please use sparingly. |
| New Attribute | Old Attribute | Description |
|---|---|---|
| metric_name | metric | `metric` is for backwards compatibility ONLY. Please use `metric_name`. |
| metric_amount | points | `points` is for backwards compatibility ONLY. Please use `metric_amount`. |
| respondable | redeemable | `redeemable` is for backwards compatibility ONLY. Please use `respondable`. |
Reward by Internal Name
To get rewards by internal name
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/rewards/<internal_name>
Returned JSON
{
"success": true,
"data": {
"id": 40,
"internal_name": "example_reward",
"type": "product",
"sku": null,
"rank": null,
"draw_date": null,
"points": "0",
"metric": "point",
"metric_display_name": "Points",
"start_date": null,
"end_date": null,
"response_start_date": null,
"response_end_date": null,
"response_schedule": null,
"redeem_options": [
"ship"
],
"heading": "EXAMPLE REWARD",
"subheading": "",
"body": "",
"subject": "",
"details": "",
"action": "",
"heading_color": "",
"color": "",
"bgcolor": "",
"heading_bgcolor": "",
"image1_bg": "",
"layout_id": "master",
"image_url": "/images/standard/missing.png",
"thumb_image_url": "/images/thumb/missing.png",
"original_image_url": "/images/original/missing.png",
"awarded": false,
"favorited": false,
"redeemable": true,
"respondable": true,
"respondable_info": {
"value": true,
"code": "",
"message": ""
},
"extra_json": {
"enterpriseItemId": "DEFINED_IN_CLASS"
},
"required_attributes": [
{
"id": 2,
"name": "vans_conditions",
"label": "Vans Conditions",
"status": "published",
"description": "",
"reward_attributes": [
{
"name": "phone_case",
"label": "Phone Case",
"data_type": "string",
"hint": "",
"attribute_options": [
{
"id": 1,
"code": "927567AV",
"label": "IPhone X",
"default": false,
"hint": ""
},
{
"id": 2,
"code": "DAS3241",
"label": "Android",
"default": false,
"hint": ""
}
]
},
{
"name": "laptop",
"label": "Laptop",
"data_type": "string",
"hint": null,
"attribute_options": [
{
"id": 9,
"code": "razor00",
"label": "Razor",
"default": false,
"hint": ""
},
{
"id": 10,
"code": "aw00",
"label": "AlienWare",
"default": false,
"hint": ""
}
]
}
]
}
],
"reward_attributes": [],
"reward_configuration": [],
"business_value": "0.0",
"metric_amount": "0",
"metric_name": "point",
"properties": {
"require_shipping_address": "yes",
"verify_shipping_address": "no",
"in_store_redemption": "no"
},
"target_url": null,
"internal_url": "reward://40",
"address_required": true,
"tracking_code": null,
"response_message": null,
"acceptance_required": false,
"acceptance_text": "",
"acceptance_url": null
}
}
HTTP REQUEST
GET <base_url>/api/rewards/<internal_name>
HEADER PARAMETERS
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
| Accept-Language | string (Multi-lingual Support) | en-US |
QUERY PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| internal_name | string (required) | internal_name of a specific reward |
Saved Rewards
To get saved rewards via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/rewards/favorites
If successful, the response should look like this:
{
"success": true,
"data": {
"id": 2,
"type": "product",
"sku": "null",
"points": "100",
"metric_amount": "100",
"metric": "point",
"metric_name": "point",
"metric_display_name": "Points",
"start_date": "null",
"end_date": "null",
"heading": "Today's Reward",
"subheading": "T-Shirt",
"body": "",
"details": "",
"image_url": "https://s3.amazonaws.com/stellar-growingtree-qyxdn1uk2xgzssjk6wya/contents/images/000/005/399/standard/__35.JPG?1449109087",
"thumb_image_url": "https://s3.amazonaws.com/stellar-growingtree-qyxdn1uk2xgzssjk6wya/contents/images/000/005/399/thumb/__35.JPG?1449109087",
"awarded": false,
"favorited": false,
"redeemable": true,
"respondable": true,
"target_url": "null",
"internal_url": "null"
}
}
Lists all saved rewards.
HTTP Request
GET <base_url>/api/rewards/favorites
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
| Accept-Language | string (Multi-lingual Support) | en-US |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| layout | string (optional) | The content layout name. Default is the access token's application name. Example: ios, android |
| html | boolean (optional) | Values can be true or false. |
| Sorting Param | ||
| sort_by | string (optional) | Sort options. Values can be updated_at or last_favorited. default: updated_at |
| sort_dir | string (optional) | Sort direction. Values can be desc or asc. default: desc. |
| page | numeric (optional) | Offset page parameter |
| per_page | numeric (optional) | Number of items per page |
Save/Unsave a Reward
To save a reward via command line, invoke the following
cURLcommand:
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/rewards/<id>/favorite
On the other hand, to unsave a reward via command line, invoke the following
cURLcommand:
curl -X DELETE
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/rewards/<id>/favorite
If successful, the response for both endpoints should be:
{
"success": true
}
Allows the user to add/remove a reward to the list of favorites.
HTTP Request
POST <base_url>/api/rewards/<id>/favorite
DELETE <base_url>/api/rewards/<id>/favorite
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
| Accept-Language | string (Multi-lingual Support) | en-US |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| id | integer (required) | id of a specific reward |
Dismissed Rewards
To get dismissed rewards via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/rewards/dismissed
If successful, the response should look like this:
{
"success": true,
"data": {
"id": 2,
"type": "product",
"sku": "null",
"points": "100",
"metric_amount": "100",
"metric": "point",
"metric_name": "point",
"metric_display_name": "Points",
"start_date": "null",
"end_date": "null",
"heading": "Today's Reward",
"subheading": "T-Shirt",
"body": "",
"details": "",
"image_url": "https://s3.amazonaws.com/stellar-growingtree-qyxdn1uk2xgzssjk6wya/contents/images/000/005/399/standard/__35.JPG?1449109087",
"thumb_image_url": "https://s3.amazonaws.com/stellar-growingtree-qyxdn1uk2xgzssjk6wya/contents/images/000/005/399/thumb/__35.JPG?1449109087",
"awarded": false,
"favorited": false,
"redeemable": true,
"respondable": true,
"target_url": "null",
"internal_url": "null"
}
}
Lists all dismissed rewards.
HTTP Request
GET <base_url>/api/rewards/dismissed
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
| Accept-Language | string (Multi-lingual Support) | en-US |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
Dismiss/Undismiss a Reward
To dismiss a reward via command line, invoke the following
cURLcommand:
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/rewards/<id>/dismiss
On the other hand, to undismiss a reward via command line, invoke the following
cURLcommand:
curl -X DELETE
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/rewards/<id>/dismiss
If successful, the response for both endpoints should be:
{
"success": true
}
Allows the user to dismiss/undismiss a reward.
HTTP Request
POST <base_url>/api/rewards/<id>/dismiss
DELETE <base_url>/api/rewards/<id>/dismiss
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
| Accept-Language | string (Multi-lingual Support) | en-US |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| id | integer (required) | id of a specific reward |
Reward Awards
To get reward awards via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/rewards/<id>/awards
If successful, the response should look like this:
{
"success": true,
"data": {
"total_pages": 1,
"total_entries": 2,
"awards": [
{
"id": 1,
"status": "awarded",
"type": "Reward",
"object": {
"id": 10,
"type": "certificate",
"sku": "",
"draw_date": "null",
"points": "100",
"metric_amount": "100",
"metric": "point",
"metric_name": "point",
"metric_display_name": "Points",
"start_date": "null",
"end_date": "null",
"heading": "Certificate Reward",
"subheading": "null",
"body": "null",
"details": "null",
"image_url": "",
"thumb_image_url": "",
"original_image_url": "",
"action": "null",
"heading_color": "null",
"color": "null",
"bgcolor": "null",
"heading_bgcolor": "null",
"image1_bg": "null",
"layout_id": "ios",
"awarded": true,
"favorited": false,
"redeemable": false,
"respondable": false,
"target_url": "https://growingtree.demostellar.com/is?p=JUeyJyZW5kZXJUbyI6IiNzb2NpYWxzaGFyZSIsImltZ1NlbGVjdG9yIjoiLnNob3ctaW1hZ2UgaW1nIiwicHJvZ19pZCI6MSwiY29tcF90eXBlIjoicmV3YXJkIiwiY29tcF9pZCI6NTIsInRpdGxlIjoiQ2VydGlmaWNhdGUgRGVtbyIsImRlc2NyaXB0aW9uIjpudWxsLCJzaXRlX25hbWUiOiJHcm93aW5nIFRyZWUiLCJpbWciOiIvaW1hZ2VzL3N0YW5kYXJkL21pc3NpbmcucG5nIiwiZnVsbEltZyI6Ii9pbWFnZXMvb3JpZ2luYWwvbWlzc2luZy5wbmciLCJzaG93X3N0b3J5Ijp0cnVlLCJscF90eXBlIjoiZmFjZWJvb2sifQ==",
"internal_url": "reward://10",
"address_required": false
},
"start_date": "",
"end_date": "",
"awarded_at": "2015-10-12T05:30:42.000Z",
"claimed_at": ""
},
{
"id": 2,
"status": "awarded",
"type": "Reward",
"object": {
"id": 10,
"type": "certificate",
"sku": "",
"draw_date": "null",
"points": "100",
"metric_amount": "100",
"metric": "point",
"metric_name": "point",
"metric_display_name": "Points",
"start_date": "null",
"end_date": "null",
"heading": "Certificate Reward",
"subheading": "null",
"body": "null",
"details": "null",
"image_url": "",
"thumb_image_url": "",
"original_image_url": "",
"action": "null",
"heading_color": "null",
"color": "null",
"bgcolor": "null",
"heading_bgcolor": "null",
"image1_bg": "null",
"layout_id": "ios",
"awarded": true,
"favorited": false,
"redeemable": false,
"respondable": false,
"target_url": "https://growingtree.demostellar.com/is?p=JUeyJyZW5kZXJUbyI6IiNzb2NpYWxzaGFyZSIsImltZ1NlbGVjdG9yIjoiLnNob3ctaW1hZ2UgaW1nIiwicHJvZ19pZCI6MSwiY29tcF90eXBlIjoicmV3YXJkIiwiY29tcF9pZCI6NTIsInRpdGxlIjoiQ2VydGlmaWNhdGUgRGVtbyIsImRlc2NyaXB0aW9uIjpudWxsLCJzaXRlX25hbWUiOiJHcm93aW5nIFRyZWUiLCJpbWciOiIvaW1hZ2VzL3N0YW5kYXJkL21pc3NpbmcucG5nIiwiZnVsbEltZyI6Ii9pbWFnZXMvb3JpZ2luYWwvbWlzc2luZy5wbmciLCJzaG93X3N0b3J5Ijp0cnVlLCJscF90eXBlIjoiZmFjZWJvb2sifQ==",
"internal_url": "reward://10",
"address_required": false
},
"start_date": "",
"end_date": "",
"awarded_at": "2015-10-12T05:33:58.000Z",
"claimed_at": ""
}
]
}
}
Lists all given awards for a specific reward.
HTTP Request
GET <base_url>/api/rewards/<id>/awards
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
| Accept-Language | string (Multi-lingual Support) | en-US |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| status | string (optional) | Values can be awarded, claimed or cancelled. |
| page | numeric (optional) | Offset page parameter |
| per_page | numeric (optional) | Number of items per page |
Respond to a Reward
To respond to a reward via command line, invoke the following
cURLcommand:
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
-F "address[text]=<string text response>"
-F "extra_json[text]=<string text response>"
<base_url>/api/rewards/<id>/respond
If successful, the response should look like this:
{
"success": true
}
Allows the user to respond to a reward.
HTTP Request
POST <base_url>/api/rewards/<id>/respond
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
| Accept-Language | string (Multi-lingual Support) | en-US |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| id | integer (required) | id of a specific reward |
Form Parameters
Usually, the above query parameters are enough unless the Reward is a Product. Below are other parameters needed for a Product Reward.
| Parameter | Type | Description |
|---|---|---|
| combination_id | integer (optional) | The combination of attributes id from the reward_configuration in Reward by ID |
| award_id | integer (optional) | The award id from Reward Awards. Using an unclaimed award will let you respond without using points |
| update_address_profile | boolean (optional) | Update member profile address using submitted address attributes. Default is false |
| extra_json[text] | string (optional) | To add additional information/details. |
If reward is configured as require_shipping_address = true, the following parameters are required to be passed:
| Parameter | Type | Description |
|---|---|---|
| address_id | integer (required) | The user's valid address id from Addresses |
or
| Parameter | Type | Description |
|---|---|---|
| address[street_address] | string (required) | The user's street address |
| address[street_address2] | string (optional) | The user's second street address line |
| address[city] | string (required) | The user's city address |
| address[state] | string (optional) | The user's state address |
| address[country_code] | string (required) | The user's country code address |
| address[zip_code] | string (optional) | The user's zip code address |
| address[phone_number] | string (optional) | The user's shipping phone number. Validates if address verification is enabled on a reward |
If reward is configured as require_class_attributes = true, the following parameters are required to be passed:
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
-F 'required_attributes[shoe_class][color]=red' \
-F 'required_attributes[shoe_class][type]=m' \
<base_url>/api/rewards/<id>/respond
| Parameter | Type | Description |
|---|---|---|
required_attributes[<class_name>][<attribute_name1>] |
string (required) | Attribute domain value |
required_attributes[<class_name>][<attribute_name2>] |
string (required) | One more attribute domain value |
The classes, class attributes and domain values are defined in Reward and Reward Classes.
Reward Responses
To get reward responses via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/rewards/responses
NOTE TO DELEVELOPERS:
metric is for backwards compatibility ONLY. Please use metric_name.
points is for backwards compatibility ONLY. Please use metric_amount.
redeemable is for backwards compatibility ONLY. Please use respondable.
If successful, the response should look like this:
{
"success": true,
"data": {
"total_pages": 1,
"total_entries": 1,
"responses": [
{
"id": 1,
"redemption_status": "completed",
"member_name": "Chuck Norris",
"member_id": 1,
"redemption_amount": "100",
"metric_name": "point",
"metric_display_name": "Points",
"metric_amount": "100",
"sku": "null",
"draw_date": "null",
"integration_id": "null",
"shipping_address": {
"id": 1,
"street_address": "Reliance cor. Pines Street",
"city": "Mandaluyong",
"zip_code": "null",
"state": "null",
"country_code": "PH",
"created_at": "2015-09-21T07:06:33.000Z",
"updated_at": "2015-09-21T07:06:33.000Z"
},
"image_url": "",
"thumb_image_url": "",
"redemption_unit": "point",
"notes": [],
"created_at": "2015-11-24T09:50:57.000Z",
"updated_at": "2015-11-24T09:50:57.000Z",
"extra_json": {
"RECIPIENT_DATA": "GIUSEPPE|BERTOLINO||"
},
"reward": {
"id": 2,
"type": "product",
"sku": "null",
"draw_date": "null",
"points": "100",
"metric_amount": "100",
"metric": "point",
"metric_name": "point",
"metric_display_name": "Points",
"start_date": "null",
"end_date": "null",
"heading": "Today's Reward",
"subheading": "T-Shirt",
"body": "",
"details": "",
"image_url": "https://s3.amazonaws.com/stellar-growingtree-qyxdn1uk2xgzssjk6wya/contents/images/000/005/399/standard/__35.JPG?1449109087",
"thumb_image_url": "https://s3.amazonaws.com/stellar-growingtree-qyxdn1uk2xgzssjk6wya/contents/images/000/005/399/thumb/__35.JPG?1449109087",
"awarded": false,
"favorited": false,
"redeemable": true,
"respondable": true,
"target_url": "null",
"internal_url": "null"
}
}
]
}
}
Lists all reward responses made by the user.
Filter reward responses of a specific status by passing redemption_status param.
HTTP Request
GET <base_url>/api/rewards/responses
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
| Accept-Language | string (Multi-lingual Support) | en-US |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| redemption_status | string (optional) | Values can be pending, processing, completed, cancelled or errored |
| page | numeric (optional) | Offset page parameter |
| per_page | numeric (optional) | Number of items per page |
| New Attribute | Old Attribute | Description |
|---|---|---|
| metric_name | metric | `metric` is for backwards compatibility ONLY. Please use `metric_name`. |
| metric_amount | points | `points` is for backwards compatibility ONLY. Please use `metric_amount`. |
| respondable | redeemable | `redeemable` is for backwards compatibility ONLY. Please use `respondable`. |
Reward Responses by ID
To get a specific reward response by ID via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/rewards/responses/<id>
If successful, the response should look like this:
{
"success": true,
"data": {
"id": 1,
"redemption_status": "completed",
"member_name": "Chuck Norris",
"member_id": 1,
"redemption_amount": "100",
"metric_name": "point",
"metric_display_name": "Points",
"metric_amount": "100",
"sku": "null",
"integration_id": "null",
"shipping_address": {
"id": 1,
"street_address": "Reliance cor. Pines Street",
"city": "Mandaluyong",
"zip_code": "null",
"state": "null",
"country_code": "PH",
"created_at": "2015-09-21T07:06:33.000Z",
"updated_at": "2015-09-21T07:06:33.000Z"
},
"image_url": "",
"thumb_image_url": "",
"redemption_unit": "point",
"notes": [],
"created_at": "2015-11-24T09:50:57.000Z",
"updated_at": "2015-11-24T09:50:57.000Z",
"reward": {
"id": 2,
"type": "product",
"sku": "null",
"points": "100",
"metric_amount": "100",
"metric": "point",
"metric_name": "point",
"metric_display_name": "Points",
"start_date": "null",
"end_date": "null",
"heading": "Today's Reward",
"subheading": "T-Shirt",
"body": "",
"details": "",
"image_url": "https://s3.amazonaws.com/stellar-growingtree-qyxdn1uk2xgzssjk6wya/contents/images/000/005/399/standard/__35.JPG?1449109087",
"thumb_image_url": "https://s3.amazonaws.com/stellar-growingtree-qyxdn1uk2xgzssjk6wya/contents/images/000/005/399/thumb/__35.JPG?1449109087",
"awarded": false,
"favorited": false,
"redeemable": true,
"respondable": true,
"target_url": "null",
"internal_url": "null"
}
}
}
Allows the user to get a specific reward response made by the user.
HTTP Request
GET <base_url>/api/rewards/responses/<id>
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
| Accept-Language | string (Multi-lingual Support) | en-US |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| id | integer (required) | id of a specific reward response |
Reward Categories
To get reward categories via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/rewards/categories
If successful, the response should look like this:
{
"success": true,
"data": {
"categories": [
{
"key": "latest_rewards",
"label": "Latest Rewards"
}
]
}
}
Lists all available reward categories.
HTTP Request
GET <base_url>/api/rewards/categories
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
| Accept-Language | string (Multi-lingual Support) | en-US |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
Products
To get products via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/products
If successful, the response should look like this:
{
"success": true,
"data": {
"total_pages": 1,
"total_entries": 2,
"products": [
{
"id": 2,
"sku": "NYC-PIZZA",
"metric_amount": "100",
"metric_name": "point",
"metric_display_name": "Point",
"start_date": "null",
"end_date": "null",
"heading": "<h2>New York Pizza</h2>",
"subheading": "",
"body": "",
"details": "",
"image_url": "https://s3.amazonaws.com/contents/images/000/000/648/standard/IMG_20150624_151219869.jpg?1435197227",
"thumb_image_url": "https://s3.amazonaws.com/contents/images/000/000/648/thumb/IMG_20150624_151219869.jpg?1435197227",
"favorited": false
},
{
"id": 1,
"sku": "SS-12345",
"metric_amount": "100",
"metric_name": "point",
"metric_display_name": "Points",
"start_date": "null",
"end_date": "null",
"heading": "Make me a Sandwich",
"subheading": "",
"body": "",
"details": "",
"image_url": "",
"thumb_image_url": "",
"favorited": false
}
]
}
}
Lists all products available to the user.
HTTP Request
GET <base_url>/api/products
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| category | string (optional) | key from the list of Product Categories |
| layout | string (optional) | The content layout name. Default is the access token's application name. Example: ios, android |
| html | boolean (optional) | Values can be true or false. |
| page | numeric (optional) | Offset page parameter |
| per_page | numeric (optional) | Number of items per page |
Product by ID
To get a specific product by ID via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/products/<id>
If successful, the response should look like this:
{
"success": true,
"data": {
"id": 2,
"sku": "NYC-PIZZA",
"metric_amount": "100",
"metric_name": "point",
"metric_display_name": "Point",
"start_date": "null",
"end_date": "null",
"heading": "<h2>New York Pizza</h2>",
"subheading": "",
"body": "",
"details": "",
"image_url": "https://s3.amazonaws.com/contents/images/000/000/648/standard/IMG_20150624_151219869.jpg?1435197227",
"thumb_image_url": "https://s3.amazonaws.com/contents/images/000/000/648/thumb/IMG_20150624_151219869.jpg?1435197227",
"favorited": false,
"product_component": [
{
"id": 32,
"sku": "null",
"metric_amount": "130",
"metric_name": "point",
"metric_display_name": "Points",
"start_date": "null",
"end_date": "null",
"heading": "Crust",
"subheading": "",
"body": "",
"details": "",
"image_url": "",
"thumb_image_url": "",
"product_component_attributes": [],
"product_component_definition": {
"selected": false,
"add_component_price": false,
"configure_attribute_id": "null"
},
"product_component_configuration": []
},
{
"id": 79,
"heading": "Toppings",
"product_component_group_definition": {
"required": false,
"limit_selections": false,
"max_selections": "null",
"charge_additional": false,
"additional_charge_amount": "null",
"num_of_selections_to_charge": "null"
},
"product_components": [
{
"id": 38,
"sku": "null",
"metric_amount": "24",
"metric_name": "point",
"metric_display_name": "Points",
"start_date": "null",
"end_date": "null",
"heading": "Paminta",
"subheading": "",
"body": "",
"details": "",
"image_url": "",
"thumb_image_url": "",
"product_component_attributes": [
{
"id": 1,
"label": "size",
"attribute_options": [
{
"id": 1,
"label": "s",
"default": false
},
{
"id": 2,
"label": "m",
"default": false
}
]
}
],
"product_component_configuration": [
{
"id": 762,
"attribute_combination": [
"s"
],
"metric_name": "point",
"metric_display_name": "Points",
"metric_amount": "24",
"sku": "null",
"thumb_image_url": ""
},
{
"id": 763,
"attribute_combination": [
"m"
],
"metric_name": "point",
"metric_display_name": "Points",
"metric_amount": "24",
"sku": "null",
"thumb_image_url": ""
}
]
}
]
}
],
"product_attributes": [
{
"id": 29,
"label": "crust type",
"attribute_options": [
{
"id": 61,
"label": "thick",
"default": false
},
{
"id": 63,
"label": "thin",
"default": false
}
]
}
],
"product_configuration": [
{
"id": 734,
"attribute_combination": [
"thick"
],
"metric_name": "point",
"metric_display_name": "Points",
"metric_amount": "34343",
"sku": "nyc-thick-111",
"image_url": "",
"thumb_image_url": "https://s3.amazonaws.com/contents/images/000/001/488/thumb/peterpan.jpg?1447745319"
},
{
"id": 735,
"attribute_combination": [
"thin"
],
"metric_name": "point",
"metric_display_name": "Points",
"metric_amount": "3",
"sku": "nyc-thin-111",
"image_url": "",
"thumb_image_url": "https://s3.amazonaws.com/contents/images/000/001/488/thumb/peterpan.jpg?1447745319"
}
]
}
}
Allows the user to get a specific product.
HTTP Request
GET <base_url>/api/products/<id>
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| id | integer (required) | id of a specific product |
| layout | string (optional) | The content layout name. Default is the access token's application name. Example: ios, android |
| html | boolean (optional) | Values can be true or false. |
Saved Products
To get saved products via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/products/favorites
If successful, the response should look like this:
{
"success": true,
"data": {
"total_pages": 1,
"total_entries": 1,
"products": [
{
"id": 2,
"sku": "NYC-PIZZA",
"metric_amount": "100",
"metric_name": "point",
"metric_display_name": "Point",
"start_date": "null",
"end_date": "null",
"heading": "<h2>New York Pizza</h2>",
"subheading": "",
"body": "",
"details": "",
"image_url": "https://s3.amazonaws.com/contents/images/000/000/648/standard/IMG_20150624_151219869.jpg?1435197227",
"thumb_image_url": "https://s3.amazonaws.com/contents/images/000/000/648/thumb/IMG_20150624_151219869.jpg?1435197227",
"favorited": false
}
]
}
}
Lists all saved products.
HTTP Request
GET <base_url>/api/products/favorites
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| layout | string (optional) | The content layout name. Default is the access token's application name. Example: ios, android |
| html | boolean (optional) | Values can be true or false. |
| page | numeric (optional) | Offset page parameter |
| per_page | numeric (optional) | Number of items per page |
Save/Unsave a Product
To save a product via command line, invoke the following
cURLcommand:
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/products/<id>/favorite
On the other hand, to unsave a product via command line, invoke the following
cURLcommand:
curl -X DELETE
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/products/<id>/favorite
If successful, the response for both endpoints should be:
{
"success": true
}
Allows the user to add/remove a product to the list of favorites.
HTTP Request
POST <base_url>/api/products/<id>/favorite
DELETE <base_url>/api/products/<id>/favorite
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| id | integer (required) | id of a specific product |
Dismissed Products
To get dismissed products via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/products/dismissed
If successful, the response should look like this:
{
"success": true,
"data": {
"total_pages": 1,
"total_entries": 1,
"products": [
{
"id": 2,
"sku": "NYC-PIZZA",
"metric_amount": "100",
"metric_name": "point",
"metric_display_name": "Point",
"start_date": "null",
"end_date": "null",
"heading": "<h2>New York Pizza</h2>",
"subheading": "",
"body": "",
"details": "",
"image_url": "https://s3.amazonaws.com/contents/images/000/000/648/standard/IMG_20150624_151219869.jpg?1435197227",
"thumb_image_url": "https://s3.amazonaws.com/contents/images/000/000/648/thumb/IMG_20150624_151219869.jpg?1435197227",
"favorited": false
}
]
}
}
Lists all dismissed products.
HTTP Request
GET <base_url>/api/products/dismissed
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
Dismiss/Undismiss a Product
To dismiss a product via command line, invoke the following
cURLcommand:
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/products/<id>/dismiss
On the other hand, to undismiss a product via command line, invoke the following
cURLcommand:
curl -X DELETE
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/products/<id>/dismiss
If successful, the response for both endpoints should be:
{
"success": true
}
Allows the user to dismiss/undismiss a product.
HTTP Request
POST <base_url>/api/products/<id>/dismiss
DELETE <base_url>/api/products/<id>/dismiss
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| id | integer (required) | id of a specific product |
Product Categories
To get product categories via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/products/categories
If successful, the response should look like this:
{
"success": true,
"data": {
"categories": [
{
"key": "cool_products",
"label": "Cool Products"
},
{
"key": "old_products",
"label": "Old Products"
}
]
}
}
Lists all available product categories.
HTTP Request
GET <base_url>/api/products/categories
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
Codes
Respond without Code ID or internal name
To respond to a content Code via command line, invoke the following
cURLcommand:
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
-F "value=<string value of a Code Entry>"
<base_url>/api/codes/respond
If successful, the response should look like this:
{
"success": true,
"data": {
"id": 4,
"response": "9780373133446",
"status": "approved",
"respondable": false,
"metric_name": "points",
"metric_amount": "200.0"
}
}
HTTP Request
POST <base_url>/api/codes/respond
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
Form Parameters
| Parameter | Type | Description |
|---|---|---|
| value | string (required) | value of a Code Entry |
Respond with Code ID or internal name
To respond to a content Code via command line, invoke the following
cURLcommand:
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
-F "value=<string value of a Code Entry>"
<base_url>/api/codes/<id> or <internal_name>/respond
If successful, the response should look like this:
{
"success": true,
"data": {
"id": 4,
"response": "9780373133446",
"status": "approved",
"respondable": false,
"metric_name": "points",
"metric_amount": "200.0"
}
}
HTTP Request
POST <base_url>/api/codes/<id> or <internal_name>/respond
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| id | integer (required) | id or internal name of a specific code |
Form Parameters
| Parameter | Type | Description |
|---|---|---|
| value | string (required) | value of a Code Entry |
Lottery
To submit a ticket number via command line, invoke the following
cURLcommand:
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
-F "ticket_code=<ticket code string>"
-F "response_method=<ticket submission method. allowed values are 'manual' or 'scan'>"
-F "type=<type of game. allowed values are 'instant' or 'draw'>"
<base_url>/api/codes/system_lottery
If successful, the response should look something like this:
{
"success": true,
"message": "Congratulations, ticket accepted.",
"data": {
"id": 193,
"status": "approved",
"approval_status": "approved",
"respondable": true,
"metric_name": "point",
"metric_amount": "0.0",
"reward_name": "Second Chance Draw",
"reward_id": 10
}
}
Otherwise, an error code and message will be returned
{
"code": 4943,
"name": "invalid",
"message": "Ticket is not valid or game is not supported."
}
HTTP Request
POST <base_url>/api/codes/system_lottery
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
Form Parameters
| Parameter | Type | Description |
|---|---|---|
| ticket_code | string (required) | The lottery ticket code/number |
| response_method | string (required) | How the ticket is submitted. Allowed values are 'manual' or 'scan' |
| type | string (optional) | The type of lottery game. Allowed values are 'instant' or 'draw' |
Code Responses
To get code responses via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/codes/responses
If successful, the response should look like this:
{
"success": true,
"data": {
"total_pages": 1,
"total_entries": 2,
"responses": [
{
"id": 3,
"response": "9780373133446",
"status": "approved",
"created_at": "2016-02-03T05:04:19.000Z",
"updated_at": "2016-02-03T05:04:19.000Z",
"code": {
"id": 1036746,
"upc": "9780373133446",
"metric": "points",
"metric_amount": "200",
"award_amount": "200",
"start_period": "null",
"end_period": "null"
}
},
{
"id": 2,
"response": "373133448",
"status": "approved",
"created_at": "2016-02-03T02:42:13.000Z",
"updated_at": "2016-02-03T02:42:13.000Z",
"code": {
"id": 1036745,
"upc": "9780373133444",
"metric": "points",
"metric_amount": "1000",
"award_amount": "1000",
"start_period": "null",
"end_period": "null"
}
}
]
}
}
Lists all code responses made by the user.
HTTP Request
GET <base_url>/api/codes/responses
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| page | numeric (optional) | Offset page parameter |
| per_page | numeric (optional) | Number of items per page |
Awards
To get awards via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/awards
or
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/rewards/awards
If successful, the response should look like this:
{
"success": true,
"data": {
"total_pages": 1,
"total_entries": 2,
"awards": [
{
"id": 1,
"status": "claimed",
"type": "Reward",
"object": {
"id": 10,
"type": "certificate",
"sku": "",
"draw_date": "null",
"points": "100",
"metric_amount": "100",
"metric": "point",
"metric_name": "point",
"metric_display_name": "Points",
"start_date": "null",
"end_date": "null",
"heading": "Certificate Reward",
"subheading": "null",
"body": "null",
"details": "null",
"image_url": "",
"thumb_image_url": "",
"original_image_url": "",
"action": "null",
"heading_color": "null",
"color": "null",
"bgcolor": "null",
"heading_bgcolor": "null",
"image1_bg": "null",
"layout_id": "ios",
"awarded": true,
"favorited": false,
"redeemable": false,
"respondable": false,
"target_url": "https://growingtree.demostellar.com/is?p=JUeyJyZW5kZXJUbyI6IiNzb2NpYWxzaGFyZSIsImltZ1NlbGVjdG9yIjoiLnNob3ctaW1hZ2UgaW1nIiwicHJvZ19pZCI6MSwiY29tcF90eXBlIjoicmV3YXJkIiwiY29tcF9pZCI6NTIsInRpdGxlIjoiQ2VydGlmaWNhdGUgRGVtbyIsImRlc2NyaXB0aW9uIjpudWxsLCJzaXRlX25hbWUiOiJHcm93aW5nIFRyZWUiLCJpbWciOiIvaW1hZ2VzL3N0YW5kYXJkL21pc3NpbmcucG5nIiwiZnVsbEltZyI6Ii9pbWFnZXMvb3JpZ2luYWwvbWlzc2luZy5wbmciLCJzaG93X3N0b3J5Ijp0cnVlLCJscF90eXBlIjoiZmFjZWJvb2sifQ==",
"internal_url": "reward://10",
"address_required": false
},
"start_date": "",
"end_date": "",
"awarded_at": "2015-10-14T01:06:11.000Z",
"claimed_at": "2015-10-14T01:06:18.000Z"
},
{
"id": 2,
"status": "claimed",
"type": "Reward",
"object": {
"id": 10,
"type": "certificate",
"sku": "",
"draw_date": "null",
"points": "100",
"metric_amount": "100",
"metric": "point",
"metric_name": "point",
"metric_display_name": "Points",
"start_date": "null",
"end_date": "null",
"heading": "Certificate Reward",
"subheading": "null",
"body": "null",
"details": "null",
"image_url": "",
"thumb_image_url": "",
"original_image_url": "",
"action": "null",
"heading_color": "null",
"color": "null",
"bgcolor": "null",
"heading_bgcolor": "null",
"image1_bg": "null",
"layout_id": "ios",
"awarded": true,
"favorited": false,
"redeemable": false,
"respondable": false,
"target_url": "https://growingtree.demostellar.com/is?p=JUeyJyZW5kZXJUbyI6IiNzb2NpYWxzaGFyZSIsImltZ1NlbGVjdG9yIjoiLnNob3ctaW1hZ2UgaW1nIiwicHJvZ19pZCI6MSwiY29tcF90eXBlIjoicmV3YXJkIiwiY29tcF9pZCI6NTIsInRpdGxlIjoiQ2VydGlmaWNhdGUgRGVtbyIsImRlc2NyaXB0aW9uIjpudWxsLCJzaXRlX25hbWUiOiJHcm93aW5nIFRyZWUiLCJpbWciOiIvaW1hZ2VzL3N0YW5kYXJkL21pc3NpbmcucG5nIiwiZnVsbEltZyI6Ii9pbWFnZXMvb3JpZ2luYWwvbWlzc2luZy5wbmciLCJzaG93X3N0b3J5Ijp0cnVlLCJscF90eXBlIjoiZmFjZWJvb2sifQ==",
"internal_url": "reward://10",
"address_required": false
},
"start_date": "",
"end_date": "",
"awarded_at": "2015-10-14T01:01:36.000Z",
"claimed_at": "2015-10-14T01:01:43.000Z"
}
]
}
}
Lists all given awards for all or a specific awardable type.
HTTP Request
GET <base_url>/api/awards or
GET <base_url>/api/rewards/awards
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| awardable_type | string (optional) | Values can be reward, offer or contest. |
| status | string (optional) | Values can be awarded, claimed or cancelled. |
| page | numeric (optional) | Offset page parameter |
| per_page | numeric (optional) | Number of items per page |
Awards by ID
To get a specific award by ID via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/awards/<id>
If successful, the response should look like this:
{
"success": true,
"data": {
"id": 1,
"status": "claimed",
"type": "Reward",
"object": {
"id": 10,
"type": "certificate",
"sku": "",
"draw_date": "null",
"points": "100",
"metric_amount": "100",
"metric": "point",
"metric_name": "point",
"metric_display_name": "Points",
"start_date": "null",
"end_date": "null",
"heading": "Certificate Reward",
"subheading": "null",
"body": "null",
"details": "null",
"image_url": "",
"thumb_image_url": "",
"original_image_url": "",
"action": "null",
"heading_color": "null",
"color": "null",
"bgcolor": "null",
"heading_bgcolor": "null",
"image1_bg": "null",
"layout_id": "ios",
"awarded": true,
"favorited": false,
"redeemable": false,
"respondable": false,
"target_url": "https://growingtree.demostellar.com/is?p=JUeyJyZW5kZXJUbyI6IiNzb2NpYWxzaGFyZSIsImltZ1NlbGVjdG9yIjoiLnNob3ctaW1hZ2UgaW1nIiwicHJvZ19pZCI6MSwiY29tcF90eXBlIjoicmV3YXJkIiwiY29tcF9pZCI6NTIsInRpdGxlIjoiQ2VydGlmaWNhdGUgRGVtbyIsImRlc2NyaXB0aW9uIjpudWxsLCJzaXRlX25hbWUiOiJHcm93aW5nIFRyZWUiLCJpbWciOiIvaW1hZ2VzL3N0YW5kYXJkL21pc3NpbmcucG5nIiwiZnVsbEltZyI6Ii9pbWFnZXMvb3JpZ2luYWwvbWlzc2luZy5wbmciLCJzaG93X3N0b3J5Ijp0cnVlLCJscF90eXBlIjoiZmFjZWJvb2sifQ==",
"internal_url": "reward://10",
"address_required": false
},
"start_date": "",
"end_date": "",
"awarded_at": "2015-10-14T01:06:11.000Z",
"claimed_at": "2015-10-14T01:06:18.000Z"
}
}
Allows the user to get a specific award.
HTTP Request
GET <base_url>/api/awards/<id>
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| id | integer (optional) | id of a specific award |
Badges
All badges
To get badges via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Accept-Language: en'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/badges
If successful, the response should look like this:
{
"success": true,
"data": {
"total_pages": 1,
"total_entries": 3,
"badges": [
{
"badge": {
"id": 19,
"name": "badge_import_52",
"label": "Badge Import 52",
"type": "CollectorBadge",
"categories": [
{
"id": 25,
"key": "badge_category_123",
"label": "badge category 123"
}
],
"description": "Badge Description",
"status": "published",
"start_period": "null",
"end_period": "null",
"expiration_interval": 1,
"expiration_interval_period": "month",
"payment_type": "any",
"response_currency_amount": "5.99",
"response_currency_name": "USD"
}
},
{
"badge": {
"id": 18,
"name": "badge_import_43",
"label": "Badge Import 43",
"type": "CollectorBadge",
"categories": [
{
"id": 25,
"key": "badge_category_123",
"label": "badge category 123"
}
],
"description": "Badge Description",
"status": "published",
"start_period": "null",
"end_period": "null",
"expiration_interval": 1,
"expiration_interval_period": "month",
"payment_type": "any",
"response_currency_amount": "2.99",
"response_currency_name": "USD"
}
},
{
"badge": {
"id": 17,
"name": "badge_import_33",
"label": "Badge Import 33",
"type": "StatusBadge",
"categories": [
{
"id": 25,
"key": "badge_category_123",
"label": "badge category 123"
}
],
"description": "Badge Description",
"levels": 2,
"status": "published",
"start_period": "null",
"end_period": "null",
"expiration_interval": "null",
"expiration_interval_period": "null"
}
}
]
}
}
Lists all available badges
HTTP Request
GET <base_url>/api/badges
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
| Accept-Language | string (Multi-lingual Support) | en-US |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| page | numeric (optional) | Offset page parameter |
| per_page | numeric (optional) | Number of items per page |
| sort_by | string (optional) | Sort options. Values can be name, label, type, created_at, updated_at, or published_at. Default is created_at. |
| sort_dir | string (optional) | Sort direction. Values can be desc or asc. Default is desc. |
| categories | array(string) (optional) | Filter by categories. Default is []. |
Member Badges
To get all badges awarded to a user via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Accept-Language: en'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/badges/me
If successful, the response should look like this:
{
"success": true,
"data": {
"total_pages": 1,
"total_entries": 2,
"badges": [
{
"earned": false,
"id": 2,
"name": "challenge_medals",
"label": "Challenge Medals",
"type": "StatusBadge",
"description": "Badge Description",
"categories": [
{
"id": 25,
"key": "badge_category_123",
"label": "badge category 123"
}
],
"image_url": "/images/original/missing.png",
"levels": [
{
"earned": false,
"level": 1,
"name": "challenger",
"label": "Challenger",
"description": "You've done a great deal of Challenges! Congratulations!",
"image_url": "/images/original/missing.png"
}
],
},
{
"id": 9,
"label": "The Prom King",
"type": "StatusBadge",
"description": "Badge Description",
"categories": [
{
"id": 25,
"key": "badge_category_123",
"label": "badge category 123"
}
],
"image_url": "/images/original/missing.png",
"level": {
"id": 27,
"value": 1,
"label": "The Prom King",
"description": "Everybody wants to dance with you!",
"image_url": "https://s3.amazonaws.com/stellar-growingtree-qyxdn1uk2xgzssjk6wya/badge_levels/images/000/000/027/original/the-prom-king.png?1458267795"
},
}
]
}
}
HTTP Request
GET <base_url>/api/badges/me
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
| Accept-Language | string (Multi-lingual Support) | en-US |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| page | numeric (optional) | Offset page parameter |
| per_page | numeric (optional) | Number of items per page |
| sort_by | string (optional) | Sort options. Values can be name, label, type, created_at, updated_at, or published_at. Default is created_at. |
| sort_dir | string (optional) | Sort direction. Values can be desc or asc. Default is desc. |
| categories | array(string) (optional) | Filter by categories. Default is []. |
Badge by ID
To get a badge by ID and details if it's earned by the current user via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Accept-Language: en'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/badges/:id/me
If successful, the response should look like this:
{
"data": {
"badge": {
"earned": true,
"id": 1,
"name": "test",
"label": "Test",
"type": "StatusBadge",
"categories": [
{
"id": 25,
"key": "badge_category_123",
"label": "badge category 123"
}
],
"description": "Badge Description",
"image_url": "/images/original/missing.png",
"levels": [
{
"earned": true,
"level": 1,
"name": "level_1",
"label": "Test",
"description": "null",
"image_url": "/images/original/missing.png"
},
{
"earned": false,
"level": 2,
"name": "level_2",
"label": "Test",
"description": "null",
"image_url": "/images/original/missing.png"
},
{
"earned": false,
"level": 3,
"name": "level_3",
"label": "Test",
"description": "null",
"image_url": "/images/original/missing.png"
}
]
}
}
}
HTTP Request
GET <base_url>/api/badges/:id/me
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
| Accept-Language | string (Multi-lingual Support) | en-US |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| id | integer/string (required) | id or internal name of a specific badge |
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| page | numeric (optional) | Offset page parameter |
| per_page | numeric (optional) | Number of items per page |
Locations
Below are list of resources available for member related to places, addresses, country codes and beacons. Place nested resources can be accessed via access_token or a pair of client_id & client_secret.
Places
To get member places via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/places
If successful, the response should look like this:
{
"success": true,
"data": {
"total_pages": 1,
"total_entries": 1,
"places": [
{
"id": 119,
"label": "Shangri-la",
"name": "shangri_la",
"integration_id": "",
"url": "null",
"place_id": "ChIJoVcqehXIlzMRP17awzDepAc",
"address": "Edsa Shangri-La, Manila, Garden Way, Ortigas Center, Mandaluyong, Metro Manila, Philippines",
"country_code": "ph",
"country": "Philippines",
"state": "Metro Manila",
"county": "",
"city": "Mandaluyong",
"zip_code": "1650",
"latitude": "14.5814094",
"longitude": "121.0567595",
"timezone": "Asia/Hong_Kong",
"utc_offset": "+08:00",
"owner": "null",
"email": "null",
"phone": "null",
"thumb_image_url": "",
"original_image_url": "",
"operating_hours": "",
"operating_hours_detailed": [
{
"day": "Monday",
"hours": [
{
"open": "09:10",
"close": "14:10"
}
]
}
],
"status": "published",
"categories": [
{
"id": 34,
"label": "category 3",
"name": "category_3",
"description": "",
"image_url": "",
"thumbnail_url": ""
},
{
"id": 33,
"label": "category 2",
"name": "category_2",
"description": "",
"image_url": "",
"thumbnail_url": ""
}
],
"distance": 438.0655726457947,
"distance_unit": "m",
"radius": 20000,
"radius_unit": "m",
"dwell": 0,
"extra_info": {},
"client_event_types": [],
"links": {
"home_page": "null",
"facebook": "null",
"instagram": "null",
"twitter": "null",
"beverage_menu": "null",
"food_menu": "null",
"grubhub_link": "null",
"postmates_link": "null",
"door_dash_link": "null"
}
}
]
}
}
Lists all member places.
Filter search by providing search term parameter q.
HTTP Request
GET <base_url>/api/places
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
Required Query Parameters
| Parameter | Type | Description |
|---|---|---|
| access_token | string (required) | access_token from successful login. If not using client_id & client_secret pair. |
| client_id | string (required) | client_id with the same scope used by member during signin. If not using access_token. |
| client_secret | string (required) | client_secret with the same scope used by member during signin. If not using access_token. |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| q | string (optional) | Search parameter, will filter - label, address, country_code, zip_code, phone and operating_hours |
| page | integer (optional) | page number offset, default is 1 |
| per_page | integer (optional) | Number of items per_page, size is handled by Member API Default List Size program setting |
| zip_code | string (optional) | Place zip code. Used if q is not provided |
| city | string (optional) | Place city. Used if q is not provided |
| country | string (optional) | Place country. Used if q is not provided |
| country_code | string (optional) | Place country code. Used if q is not provided |
| integration_id | string (optional) | Place integration_id. Used if q is not provided |
| sort_by | string (optional) | Sort option. Values can be label and name. Default is label |
| sort_dir | string (optional) | Sort direction. Values can be asc and desc. Default is asc |
| categories | array (optional) | Place categories. If one category is satisfied place belongs to the list |
| subcategories | array (optional) | Place categories. All categories in the array should be satisfied for the place to belong to the list |
Get Places
Get all member places
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
<base_url>/program/api/places
Returns simple JSON
{
"success": true,
"data": {
"total_pages": 1,
"total_entries": 1,
"places": [
{
"id": 97,
"name": "fedrizzi_s_r_l_unipersonale",
"label": "FEDRIZZI S.R.L. UNIPERSONALE",
"place_id": "null",
"address": "COMANO TERME",
"country_code": "null",
"zip_code": "null",
"phone": "null",
"latitude": "46.0265418",
"longitude": "10.874793",
"timezone": "",
"utc_offset": "",
"integration_id": "10201024",
"operating_hours": "",
"operating_hours_detailed": [],
"radius": "null",
"radius_unit": "m",
"dwell": 0,
"city": "COMANO TERME",
"country": "Italy",
"county": "nord",
"state": "Calif",
"extra_info": {
"owner": "BELTRAMINI FAUSTO",
"notes": "0",
"loyalty_subscription": "0"
},
"client_event_types": []
}
]
}
}
Return JSON if resource does not exist
{
"code": 4044,
"name": "not_available",
"message": "Resource not available."
}
HTTP Request
GET <base_url>/api/places
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
Get Place by ID
Get place by id
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
<base_url>/program/api/places/<id>
Returns simple JSON
{
"success": true,
"data": {
"id": 54,
"label": "10 Rollins",
"name": "rollins",
"integration_id": "",
"url": "null",
"place_id": "ChIJM_rk0rB3j4AR1n6yUUOi_jk",
"address": "10 Rollins Road, Millbrae, CA, United States",
"country_code": "us",
"country": "United States",
"state": "California",
"county": "San Mateo County",
"city": "Millbrae",
"zip_code": "94030",
"latitude": "37.59980720000001",
"longitude": "-122.38396060000002",
"timezone": "",
"utc_offset": "",
"owner": "null",
"email": "null",
"phone": "null",
"thumb_image_url": "",
"original_image_url": "",
"operating_hours": "",
"operating_hours_detailed": [],
"status": "published",
"categories": [
{
"id": 36,
"label": "test category",
"name": "test_category",
"description": "null",
"image_url": "",
"thumbnail_url": ""
}
],
"radius": "null",
"radius_unit": "m",
"dwell": 0,
"extra_info": {},
"client_event_types": [],
"links": {
"home_page": "null",
"facebook": "null",
"instagram": "null",
"twitter": "null",
"beverage_menu": "null",
"food_menu": "null",
"grubhub_link": "null",
"postmates_link": "null",
"door_dash_link": "null"
}
}
}
Return JSON if resource does not exist
{
"code": 4044,
"name": "not_available",
"message": "Resource not available."
}
HTTP Request
GET <base_url>/api/places/<id>
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| id | string (required) | id or integration_id value of place to retrieve |
| [DEPRECATED] access_token | string (required) | access_token from successful login |
Nearby Places
To get nearby places query via command line using
latandlonfields, invoke the followingcURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
-F "lat=14.697718"
-F "lon=121.033167"
-F "distance=1"
<base_url>/api/places/nearby
To get nearby places query via command line using
addressfield, invoke the followingcURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
-F "address=90210"
-F "distance=50"
<base_url>/api/places/nearby
If successful, the response should look like this:
{
"success": true,
"data": {
"total_pages": 1,
"total_entries": 1,
"distance": 50000,
"radius": 50000,
"unit": "m",
"centerpoint": [
14.5819341840644,
121.060793960454
],
"places": [
{
"id": 119,
"label": "Shangri-la",
"name": "shangri_la",
"integration_id": "",
"url": "null",
"place_id": "ChIJoVcqehXIlzMRP17awzDepAc",
"address": "Edsa Shangri-La, Manila, Garden Way, Ortigas Center, Mandaluyong, Metro Manila, Philippines",
"country_code": "ph",
"country": "Philippines",
"state": "Metro Manila",
"county": "",
"city": "Mandaluyong",
"zip_code": "1650",
"latitude": "14.5814094",
"longitude": "121.0567595",
"timezone": "Asia/Hong_Kong",
"utc_offset": "+08:00",
"owner": "null",
"email": "null",
"phone": "null",
"thumb_image_url": "",
"original_image_url": "",
"operating_hours": "",
"operating_hours_detailed": [
{
"day": "Monday",
"hours": [
{
"open": "09:10",
"close": "14:10"
}
]
}
],
"status": "published",
"categories": [
{
"id": 34,
"label": "category 3",
"name": "category_3",
"description": "",
"image_url": "",
"thumbnail_url": ""
},
{
"id": 33,
"label": "category 2",
"name": "category_2",
"description": "",
"image_url": "",
"thumbnail_url": ""
}
],
"distance": 438.0655726457947,
"distance_unit": "m",
"radius": 20000,
"radius_unit": "m",
"dwell": 0,
"extra_info": {},
"client_event_types": [],
"links": {
"home_page": "null",
"facebook": "null",
"instagram": "null",
"twitter": "null",
"beverage_menu": "null",
"food_menu": "null",
"grubhub_link": "null",
"postmates_link": "null",
"door_dash_link": "null"
}
}
]
}
}
Allows the user to query nearby places by submitting lat (latitude) and lon (longitude) values or an address string to this endpoint.
Optionally include distance parameter, default is 20 miles if not specified.
{{client_url}}/api/places/nearby?client_id=<client_id>&client_secret=<client_id>&address=<zipcode>&distance=<range in miles>
HTTP Request
GET <base_url>/api/places/nearby
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| access_token | string (required) | access_token from successful login |
| lat | string (required if not using address search) | Place latitude value |
| lon | string (required if not using address search) | Place longitude value |
| address | string (required if not using lat/lon) | Place string address, i.e. street address, city, state or zip_code |
| with_client_events | boolean (optional) | Only return places with client events |
| distance | numeric (optional) | Distance parameter in miles, default is 20 miles |
| count | integer (optional) | Number of places we want to search |
| unit | string (optional) | Unit used for searching place distance. Valus are m, km, mi and ft |
| is_open | boolean (optional) | If set to true, all open places for the current time are returned. If set to false, all closed places are returned. |
| categories | array (optional) | Place category. If one category is satisfied place belongs to the list |
| subcategories | array (optional) | Place category. All categories in the array should be satisfied for the place to belong to the list |
| page | integer (optional) | page number offset, default is 1 |
| per_page | integer (optional) | Number of items per_page, size is handled by Member API Default List Size program setting |
| sort_by | string (optional) | Sort option. Values can be label and name. Default is label |
| sort_dir | string (optional) | Sort direction. Values can be asc and desc. Default is asc |
Addresses
To get addresses via command line using latitude and longitude, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/addresses
If successful, the response should look like this:
{
"success": true,
"data": [
{
"id": 1,
"street_address": "San Miguel Ave.",
"city": "Pasig",
"zip_code": "1600",
"state": "NCR",
"country_code": "PH",
"created_at": "2015-06-24T12:07:08.000Z",
"updated_at": "2015-06-24T12:07:08.000Z"
},
{
"id": 2,
"street_address": "Joel Street",
"city": "Quezon City",
"zip_code": "1116",
"state": "NCR",
"country_code": "PH",
"created_at": "2015-06-24T12:09:24.000Z",
"updated_at": "2015-06-24T12:09:24.000Z"
}
]
}
Lists all user addresses.
HTTP Request
GET <base_url>/api/addresses
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| page | numeric (optional) | Offset page parameter |
| per_page | numeric (optional) | Number of items per page |
Country Codes
To get country codes via command line using latitude and longitude, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/countries
If successful, the response should look like this:
{
"success": true,
"data": [
{
"AD": "Andorra"
},
{
"AE": "United Arab Emirates"
},
..
{
"ZM": "Zambia"
},
{
"ZW": "Zimbabwe"
}
]
}
Lists all countries together with their corresponding country codes.
HTTP Request
GET <base_url>/api/countries
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
Beacon UUIDs
To get a list of beacon uuids via command line, invoke the following cURL command:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/beacons/uuids
If successful, the response should look like this:
{
"success": true,
"data": {
"uuids": [
"B9407F30-F5F8-466E-AFF9-25556B57FE6D",
"F2391G54-H7S2-939J-VNE6-20034S22DK0F"
]
}
}
Lists all beacon uuids.
HTTP Request
GET <base_url>/api/beacons/uuids
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
Create a Beacon Activity
To create a beacon activity via command line, invoke the following cURL command:
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
-F "uuid=<beacon uuid>"
-F "major=<major>"
-F "minor=<minor>"
<base_url>/api/beacons
If successful, the response should look like this:
{
"success": true
}
This allows the user to post a beacon activity.
HTTP Request
POST <base_url>/api/beacons
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
Form Parameters
| Parameter | Type | Description |
|---|---|---|
| uuid | string (required) | access_token from successful login |
| major | string (required) | beacon major id |
| minor | string (required) | beacon minor id |
Content Blocks
To get content blocks via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/content_blocks
If successful, the response should look like this:
{
"success": true,
"data": {
"total_pages": 1,
"total_entries": 2,
"content_blocks": [
{
"id": 2,
"label": "Content Block 2",
"description": "",
"name": "content_block_2",
"heading": "Content Block 2",
"subheading": "",
"body": "",
"details": "",
"image_url": "",
"thumb_image_url": ""
},
{
"id": 1,
"label": "Content Block 1",
"description": "",
"heading": "Content Block 1",
"subheading": "",
"body": "",
"details": "",
"image_url": "",
"thumb_image_url": ""
}
]
}
}
Lists all content blocks.
HTTP Request
GET <base_url>/api/content_blocks
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| layout | string (optional) | The content layout name. Default is the access token's application name. Example: ios, android |
| html | boolean (optional) | Values can be true or false. |
Content Block by ID
To get a specific content block by ID via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/content_blocks/<id>
If successful, the response should look like this:
{
"success": true,
"data": {
"id": 1,
"label": "Content Block 1",
"description": "",
"heading": "Content Block 1",
"subheading": "",
"body": "",
"details": "",
"image_url": "",
"thumb_image_url": ""
}
}
Allows the user to get a specific content block.
HTTP Request
GET <base_url>/api/content_blocks/<id>
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| id | integer (required) | id of a specific content block |
| layout | string (optional) | The content layout name. Default is the access token's application name. Example: ios, android |
| html | boolean (optional) | Values can be true or false. |
Content Pages
To get content pages via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/content_pages
If successful, the response should look like this:
{
"success": true,
"data": {
"total_pages": 1,
"total_entries": 2,
"content_pages": [
{
"id": 2,
"label": "Content Page 2",
"description": "",
"page_type": "content_gallery",
"name": "content_page_2",
"template_set_version_id": 98,
"heading": "Content Page 2",
"subheading": "",
"body": "",
"details": "",
"image_url": "",
"thumb_image_url": ""
},
{
"id": 1,
"label": "Content Page 1",
"description": "",
"page_type": "content_gallery",
"name": "content_page_1",
"template_set_version_id": 98,
"heading": "Content Page 1",
"subheading": "",
"body": "",
"details": "",
"image_url": "",
"thumb_image_url": ""
}
]
}
}
Lists all content pages.
HTTP Request
GET <base_url>/api/content_pages
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| layout | string (optional) | The content layout name. Default is the access token's application name. Example: ios, android |
| html | boolean (optional) | Values can be true or false. |
Content Page by ID
To get a specific content page by ID via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/content_pages/<id>
If successful, the response should look like this:
{
"success": true,
"data": {
"id": 1,
"label": "Content Page 1",
"description": "Content Page Description",
"page_type": "content_gallery",
"name": "content_page_1",
"template_set_version_id": 98,
"heading": "Content Block 1",
"subheading": "",
"body": "",
"details": "",
"image_url": "",
"thumb_image_url": ""
}
}
Allows the user to get a specific content page.
HTTP Request
GET <base_url>/api/content_pages/<id>
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| id | integer (required) | id of a specific content page |
| layout | string (optional) | The content layout name. Default is the access token's application name. Example: ios, android |
| html | boolean (optional) | Values can be true or false. |
| sso_target_client_id | string (optional) | Valid Oauth Application client_id to return new access_token for the current user. If submitted and subject content_page is set to require_login, url node will include query stl_params_hash with encrypted access_token. |
Groups
To get all groups via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/groups
If successful, the response should look like this:
{
"success": true,
"data": [
{
"id": 1,
"group_id": "U-000000144",
"description": "THE STREETS, CA2",
"name": "SCHOOL OF ROCK2",
"display_name": "SCHOOL OF ROCK2",
"avatar_url": ""
},
{
"id": 2,
"group_id": "U-000000145",
"description": "Menlo Park, CA",
"name": "Punchtab MDV HS1",
"display_name": "Punchtab MDV HS1",
"avatar_url": ""
},
{
"id": 3,
"group_id": "U-000000146",
"description": "New York, NY",
"name": "Punchtab MDV HS2",
"display_name": "Punchtab MDV HS2",
"avatar_url": ""
}
]
}
Lists all groups.
HTTP Request
GET <base_url>/api/groups
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| page | numeric (optional) | Offset page parameter |
| per_page | numeric (optional) | Number of items per page |
| group_class | string | name from the list of Group Classes |
Joined Groups
To get the list of joined groups via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/groups/joined
If successful, the response should look like this:
{
"success": true,
"data": [
{
"id": 160,
"group_id": "U-000000144",
"description": "THE STREETS, CA2",
"name": "SCHOOL OF ROCK2",
"display_name": "SCHOOL OF ROCK2",
"avatar_url": ""
}
]
}
Get groups joined by current member.
HTTP Request
GET <base_url>/api/groups/joined
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
Join Group
To join an existing group via command line, invoke the following
cURLcommand:
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/groups/<id>/join
If successful, the response should look like this:
{
"success": true
}
Join an existing group.
HTTP Request
POST <base_url>/api/groups/<id>/join
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| id | integer (required) | id of a specific group |
Leave Group
To leave a group via command line, invoke the following
cURLcommand:
curl -X DELETE
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/groups/<id>/leave
If successful, the response for both endpoints should look like:
{
"success": true
}
Leave a group joined by the current member.
HTTP Request
DELETE <base_url>/api/groups/<id>/leave
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| id | integer (required) | id of a specific group |
Get Group Members
To get group members via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/groups/<id>/members
If successful, the response for both endpoints should look like:
{
"success": true,
"data": {
"total_pages": 1,
"total_entries": 1,
"members": [
{
"name": "Jesus Feeney",
"first_name": "Jesus",
"last_name": "Feeney",
"email": "valentina_powlowski51@fritsch.info",
"member_id": "V-000000001",
"mobile_phone": "null",
"avatar_url": ""
}
]
}
}
Returns
not_allowederror when not enabled
{
"code": 4702,
"name": "not_allowed",
"message": "Group Members endpoint is disabled"
}
Get members of a specific group. This endpoint is not enabled by default. Go to <base_url>/console/program_settings then turn on Enable Group Members API
HTTP Request
GET <base_url>/api/groups/<id>/members
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| id | integer (required) | id of a specific group |
| page | numeric (optional) | Offset page parameter |
| per_page | numeric (optional) | Number of items per page |
| sort | string (optional) | Sort returned records, default none. first_name asc/desc, last_name asc/desc |
Group classes
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/groups/classes
The above command returns JSON structured like this:
{
"success": true,
"data": {
"total_pages": 1,
"total_entries": 4,
"classes": [
{
"label": "Default Class",
"name": "default_class"
},
{
"label": "Magagaling",
"name": "magagaling"
},
{
"label": "Malulupet",
"name": "malulupet"
},
{
"label": "Saling Pusa",
"name": "saling_pusa"
}
]
}
}
HTTP Request
GET <base_url>/api/groups/classes
Query Parameters
| Required | Name | Type | Description |
|---|---|---|---|
| ✓ | [DEPRECATED] access_token | String | access_token from successful login |
Members
All Members
To get all members via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/members
If successful, the response should look like this:
{
"success": true,
"data": {
"total_pages": 1,
"total_entries": 11,
"members": [
{
"name": "Hobart Kutch",
"first_name": "Hobart",
"last_name": "Kutch",
"email": "otilia.hilpert23@olson.info",
"member_id": "K-000000001",
"mobile_phone": "null",
"avatar_url": "",
"primary_group": "null"
},
{
"name": "Hobart Kutch",
"first_name": "Hobart",
"last_name": "Kutch",
"email": "rachel_rice24@kihnkonopelski.co",
"member_id": "K-000000002",
"mobile_phone": "null",
"avatar_url": "",
"primary_group": "voluptatum3"
},
{
"name": "Hobart Kutch",
"first_name": "Hobart",
"last_name": "Kutch",
"email": "therese25@lubowitzhermann.org",
"member_id": "K-000000003",
"mobile_phone": "null",
"avatar_url": "",
"primary_group": "null"
},
{
"name": "Hobart Kutch",
"first_name": "Hobart",
"last_name": "Kutch",
"email": "rhianna_ankunding26@crona.name",
"member_id": "K-000000004",
"mobile_phone": "null",
"avatar_url": "",
"primary_group": "null"
},
{
"name": "Hobart Kutch",
"first_name": "Hobart",
"last_name": "Kutch",
"email": "fabian_weinat27@weinat.co",
"member_id": "K-000000005",
"mobile_phone": "null",
"avatar_url": "",
"primary_group": "null"
},
{
"name": "Hobart Kutch",
"first_name": "Hobart",
"last_name": "Kutch",
"email": "leanne28@hills.name",
"member_id": "K-000000006",
"mobile_phone": "null",
"avatar_url": "",
"primary_group": "null"
},
{
"name": "Hobart Kutch",
"first_name": "Hobart",
"last_name": "Kutch",
"email": "mireya29@carrollshields.info",
"member_id": "K-000000007",
"mobile_phone": "null",
"avatar_url": "",
"primary_group": "null"
},
{
"name": "Hobart Kutch",
"first_name": "Hobart",
"last_name": "Kutch",
"email": "savion.zieme30@emardbogan.net",
"member_id": "K-000000008",
"mobile_phone": "null",
"avatar_url": "",
"primary_group": "null"
},
{
"name": "Hobart Kutch",
"first_name": "Hobart",
"last_name": "Kutch",
"email": "arnulfo31@schinner.name",
"member_id": "K-000000009",
"mobile_phone": "null",
"avatar_url": "",
"primary_group": "null"
},
{
"name": "Hobart Kutch",
"first_name": "Hobart",
"last_name": "Kutch",
"email": "craig_olson32@hirthe.info",
"member_id": "K-000000010",
"mobile_phone": "null",
"avatar_url": "",
"primary_group": "null"
},
{
"name": "Hobart Kutch",
"first_name": "Hobart",
"last_name": "Kutch",
"email": "eleonore33@mann.co",
"member_id": "K-000000011",
"mobile_phone": "null",
"avatar_url": "",
"primary_group": "null"
}
]
}
}
Return error
not_allowedif endpoint is not enabled.
{
"code": 4703,
"name": "not_allowed",
"message": "Member lookup is disabled"
}
Lists all members. This endpoint is not enabled by default. Go to <base_url>/console/program_settings then turn on Enable Lookup on All Members API
HTTP Request
GET <base_url>/api/members
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| page | numeric (optional) | Offset page parameter |
| per_page | numeric (optional) | Number of items per page |
| sort | string (optional) | Sort returned records, default none. first_name asc/desc, last_name asc/desc |
| q | string (optional) | Search parameter to query against first_name, last_name, email, member_id and mobile_phone |
Get Member
To get a specific members via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/members/<member_id>
If successful, the response should look like this:
{
"success": true,
"data": {
"email": "francisca.bogan35@swaniawski.com",
"first_name": "Annette",
"last_name": "Koepp",
"mailing_street": "",
"mailing_city": "",
"mailing_state": "",
"mailing_postal_code": "",
"mailing_country": "",
"birthdate": "",
"mobile_phone": "",
"member_since": "2016-08-18",
"member_id": "M-000000002",
"receive_email_offers": true,
"receive_sms_offers": true,
"receive_mobile_app_offers": true,
"receive_mail_offers": true,
"receive_e_statements": true,
"current_tier": "",
"expiration_date": "",
"tier_in_progression": "",
"referrer_id": "",
"gender": "",
"marital_status": "",
"education": "",
"income": "",
"has_children": "",
"employment": "",
"ethnicity": "",
"housing": "",
"test_member": false,
"visitor": false,
"card_id": "",
"receive_newsfeed_like_notification": true,
"receive_newsfeed_comment_notification": true,
"avatar_url": ""
}
}
Return error
not_allowedif endpoint is not enabled.
{
"code": 4703,
"name": "not_allowed",
"message": "Member lookup is disabled"
}
Get a member record via member_id. This endpoint is not enabled by default. Go to <base_url>/console/program_settings then turn on Enable Lookup on All Members API
HTTP Request
GET <base_url>/api/members/<member_id>
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| member_id | string (required) | member_id of member to lookup |
Leaderboards
To get leaderboards via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/leaderboards
If successful, the response should look like this:
{
"success": true,
"data": {
"total_pages": 1,
"total_entries": 2,
"leaderboards": [
{
"id": 1,
"label": "High Times",
"name": "high_times",
"description": "",
"metric_name": "point",
"metric_display_name": "Point"
},
{
"id": 2,
"label": "Annual High",
"name": "annual_high",
"description": "",
"metric_name": "point",
"metric_display_name": "Point",
"class": {
"label": "Awesome",
"name": "awesome"
}
}
]
}
}
Lists all score boards available to the user.
HTTP Request
GET <base_url>/api/leaderboards
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| page | numeric (optional) | Offset page parameter |
| per_page | numeric (optional) | Number of items per page |
| group_class | string | name from the list of Group Classes |
Top Leaders
To fetch the top leaders of a leaderboard via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/leaderboards/<id>/top
If successful, the response should look like this:
{
"success": true,
"data": {
"page_size": 2,
"total_pages": 10,
"total_entries": 20,
"current_member_page": 1,
"leaders": [
{
"id": 1,
"email": "chuck@norris.com",
"first_name": "Chuck",
"last_name": "Norris",
"display_name": "The Man",
"description": "",
"avatar_url": "",
"rank": 1,
"score": 1330341766,
"highlight": true
},
{
"id": 2,
"email": "juan@delacruz",
"first_name": "Juan",
"last_name": "dela Cruz",
"display_name": "Juan dela Cruz",
"description": "",
"avatar_url": "",
"rank": 2,
"score": 1021276122,
"highlight": false
}
]
}
}
Fetch the top leaders of a leaderboard.
HTTP Request
GET <base_url>/api/leaderboards/<id>/top
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| id | integer (required) | id of a specific leaderboard |
| size | integer (optional) | The number of leaders to fetch, starting from the first rank downward. Default is 10. |
My Rank
To fetch the current user's rank and points via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/leaderboards/<id>/me
If successful, the response should look like this:
{
"success": true,
"data": {
"total_entries": 38089,
"leader": {
"id": 1,
"email": "chuck@norris.com",
"first_name": "Chuck",
"last_name": "Norris",
"display_name": "The Man",
"description": "",
"avatar_url": "",
"rank": 1,
"score": 1330341766,
"highlight": false
}
}
}
Fetch current user's rank and score.
HTTP Request
GET <base_url>/api/leaderboards/<id>/me
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| id | integer (required) | id of a specific leaderboard |
Leaders Around Me
To find leaders around the current user's rank via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/leaderboards/<id>/around_me
To specify the buffer around the user's rank via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/leaderboards/<id>/around_me?buffer=3
If successful, the response for both endpoints should look like:
{
"success": true,
"data": {
"page_size": 7,
"total_pages": 5,
"total_entries": 35,
"current_member_page": 2,
"leaders": [
{
"id": 35,
"email": "mountain@gmail.com",
"first_name": "Sandor",
"last_name": "Clegane",
"display_name": "mountain@gmail.com",
"avatar_url": "",
"rank": 8,
"score": 257,
"highlight": false
},
{
"id": 14,
"email": "arya@gmail.com",
"first_name": "Arya",
"last_name": "Stark",
"display_name": "arya@gmail.com",
"avatar_url": "",
"rank": 9,
"score": 253,
"highlight": false
},
{
"id": 23,
"email": "cersei@gmail.com",
"first_name":"Cersei",
"last_name": "Lannister",
"display_name": "cersei@gmail.com",
"avatar_url": "",
"rank": 10,
"score": 251,
"highlight": false
},
{
"id": 40,
"email": "loras@gmail.com",
"first_name": "Loras",
"last_name": "Tyrell",
"display_name": "loras@gmail.com",
"avatar_url": "",
"rank": 11,
"score": 248,
"highlight": true
},
{
"id": 24,
"email": "jamie@gmail.com",
"first_name": "Jaime",
"last_name": "Lannister",
"display_name": "jaime@gmail.com",
"avatar_url": "",
"rank": 12,
"score": 247,
"highlight": false
},
{
"id": 31,
"email": "rhaegar@gmail.com",
"first_name": "Rhaegar",
"last_name": "Targaryen",
"display_name": "rhaegar@gmail.com",
"avatar_url": "",
"rank": 13,
"score": 239,
"highlight": false
},
{
"id": 26,
"email": "renly@gmail.com",
"first_name": "Renly",
"last_name": "Baratheon",
"display_name": "renly@gmail.com",
"avatar_url": "",
"rank": 14,
"score": 239,
"highlight": false
}
]
}
}
Note: The current user is 'highlighted' in the response (highlight: true)
Fetch users around the current user's rank with optional buffer size.
HTTP Request
GET <base_url>/api/leaderboards/<id>/around_me
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| id | integer (required) | id of a specific leaderboard |
| buffer | integer (optional) | Size of the buffer around the user. Default is 3. |
Ranked Friends
To get ranks of friends in a leaderboard via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/leaderboards/<id>/friends
If successful, the response should look like this:
{
"success": true,
"data": {
"page_size": 7,
"total_pages": 5,
"total_entries": 35,
"current_member_page": 2,
"leaders": [
{
"id": 35,
"email": "mountain@gmail.com",
"first_name": "Sandor",
"last_name": "Clegane",
"display_name": "mountain@gmail.com",
"avatar_url": "",
"rank": 8,
"score": 257,
"highlight": false
},
{
"id": 14,
"email": "arya@gmail.com",
"first_name": "Arya",
"last_name": "Stark",
"display_name": "arya@gmail.com",
"avatar_url": "",
"rank": 21,
"score": 253,
"highlight": false
},
{
"id": 23,
"email": "cersei@gmail.com",
"first_name":"Cersei",
"last_name": "Lannister",
"display_name": "cersei@gmail.com",
"avatar_url": "",
"rank": 27,
"score": 251,
"highlight": false
},
{
"id": 31,
"email": "rhaegar@gmail.com",
"first_name": "Rhaegar",
"last_name": "Targaryen",
"display_name": "rhaegar@gmail.com",
"avatar_url": "",
"rank": 28,
"score": 239,
"highlight": false
},
{
"id": 26,
"email": "renly@gmail.com",
"first_name": "Renly",
"last_name": "Baratheon",
"display_name": "renly@gmail.com",
"avatar_url": "",
"rank": 32,
"score": 239,
"highlight": false
}
]
}
}
List all ranks of the current user's friends
HTTP Request
GET <base_url>/api/leaderboards/<id>/friends
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| id | integer (required) | id of a specific leaderboard |
Ranked Group Mates
To get ranks of group users in a leaderboard via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/leaderboards/<id>/group_mates
If successful, the response should look like this:
{
"success": true,
"data": {
"page_size": 7,
"total_pages": 5,
"total_entries": 35,
"current_member_page": 2,
"leaders": [
{
"id": 35,
"email": "mountain@gmail.com",
"first_name": "Sandor",
"last_name": "Clegane",
"display_name": "mountain@gmail.com",
"avatar_url": "",
"rank": 8,
"score": 257,
"highlight": false
},
{
"id": 14,
"email": "arya@gmail.com",
"first_name": "Arya",
"last_name": "Stark",
"display_name": "arya@gmail.com",
"avatar_url": "",
"rank": 21,
"score": 253,
"highlight": false
},
{
"id": 23,
"email": "cersei@gmail.com",
"first_name":"Cersei",
"last_name": "Lannister",
"display_name": "cersei@gmail.com",
"avatar_url": "",
"rank": 27,
"score": 251,
"highlight": false
},
{
"id": 31,
"email": "rhaegar@gmail.com",
"first_name": "Rhaegar",
"last_name": "Targaryen",
"display_name": "rhaegar@gmail.com",
"avatar_url": "",
"rank": 28,
"score": 239,
"highlight": false
},
{
"id": 26,
"email": "renly@gmail.com",
"first_name": "Renly",
"last_name": "Baratheon",
"display_name": "renly@gmail.com",
"avatar_url": "",
"rank": 32,
"score": 239,
"highlight": false
}
]
}
}
List all ranks of the current user group mates, given a group and leaderboard. If no group_id provided, we use the current user's primary group.
HTTP Request
GET <base_url>/api/leaderboards/<id>/group_mates
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| id | integer (required) | id of a specific leaderboard |
| group_id | integer (optional) | id of one of the current user's groups. If no group_id provided, we use the user's primary group |
Events
Events
To get events via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/events
If successful, the response should look like this:
{
"success": true,
"data": {
"total_pages": 1,
"total_entries": 10,
"events": [
{
"id": 1,
"name": "quisquam1",
"label": "quisquam1",
"metric_name": "points",
"metric_amount": "10",
"image": "null",
"created_at": "2016-08-22T07:20:04.000Z",
"updated_at": "2016-08-22T07:20:04.000Z"
},
{
"id": 2,
"name": "ut2",
"label": "ut2",
"metric_name": "points",
"metric_amount": "10",
"image": "null",
"created_at": "2016-08-22T07:20:04.000Z",
"updated_at": "2016-08-22T07:20:04.000Z"
},
{
"id": 3,
"name": "sit3",
"label": "sit3",
"metric_name": "points",
"metric_amount": "10",
"image": "null",
"created_at": "2016-08-22T07:20:04.000Z",
"updated_at": "2016-08-22T07:20:04.000Z"
},
{
"id": 4,
"name": "repellendus4",
"label": "repellendus4",
"metric_name": "points",
"metric_amount": "10",
"image": "null",
"created_at": "2016-08-22T07:20:04.000Z",
"updated_at": "2016-08-22T07:20:04.000Z"
},
{
"id": 5,
"name": "iusto5",
"label": "iusto5",
"metric_name": "points",
"metric_amount": "10",
"image": "null",
"created_at": "2016-08-22T07:20:04.000Z",
"updated_at": "2016-08-22T07:20:04.000Z"
},
{
"id": 6,
"name": "autem6",
"label": "autem6",
"metric_name": "points",
"metric_amount": "10",
"image": "null",
"created_at": "2016-08-22T07:20:04.000Z",
"updated_at": "2016-08-22T07:20:04.000Z"
},
{
"id": 7,
"name": "rem7",
"label": "rem7",
"metric_name": "points",
"metric_amount": "10",
"image": "null",
"created_at": "2016-08-22T07:20:04.000Z",
"updated_at": "2016-08-22T07:20:04.000Z"
},
{
"id": 8,
"name": "expedita8",
"label": "expedita8",
"metric_name": "points",
"metric_amount": "10",
"image": "null",
"created_at": "2016-08-22T07:20:04.000Z",
"updated_at": "2016-08-22T07:20:04.000Z"
},
{
"id": 9,
"name": "ea9",
"label": "ea9",
"metric_name": "points",
"metric_amount": "10",
"image": "null",
"created_at": "2016-08-22T07:20:04.000Z",
"updated_at": "2016-08-22T07:20:04.000Z"
},
{
"id": 10,
"name": "ea10",
"label": "ea10",
"metric_name": "points",
"metric_amount": "10",
"image": "null",
"created_at": "2016-08-22T07:20:04.000Z",
"updated_at": "2016-08-22T07:20:04.000Z"
}
]
}
}
Lists all events available to the user.
HTTP Request
GET <base_url>/api/events
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| page | numeric (optional) | Offset page parameter |
| per_page | numeric (optional) | Number of items per page |
| result_with_categories | boolean (optional) | Values can be true or false |
| sort_by | string (optional) | Sort options. Values can be name or start_at default: start_at |
| sort_dir | string (optional) | Sort direction. Values can be desc or asc default: desc NOTE: default is desc if sort_by is date otherwise asc |
Get Event
To get a specific event by ID via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/events/<id>
If successful, the response should look like this:
{
"success": true,
"data": {
"name": "velit11",
"label": "velit11",
"metric_name": "points",
"description": "null",
"location": "null",
"start_at": "2016-08-07T07:19:44.000Z",
"end_at": "null",
"timezone": "Etc/UTC",
"isrecurring": false,
"recurring_date": "null",
"response_end_at": "null",
"response_start_at": "null",
"effectivity_start": "null",
"effectivity_end": "null",
"effectivity_timezone": "null",
"recurring": false,
"recurring_schedule": {},
"metric_amount": "10",
"image": "null",
"created_at": "2016-08-22T07:20:07.000Z",
"updated_at": "2016-08-22T07:20:07.000Z"
}
}
Allows the user to get a specific event.
HTTP Request
GET <base_url>/api/events/<id>
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| result_with_categories | boolean (optional) | Values can be true or false |
| id | integer (required) | id of a specific event |
Event Categories
To get list of event categories via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/events/categories
If successful, the response should look like this:
{
"success": true,
"data": {
"categories": [
{
"key": "popular",
"label": "Popular"
}
]
}
}
Allows the user to get a specific event.
HTTP Request
GET <base_url>/api/events/categories
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
Gift Cards
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/giftcards
The above command returns JSON structured like this:
{
"success": true,
"data": {
"total_pages": 1,
"total_entries": 2,
"giftcards": [
{
"card_number": "1800KATPADI",
"active": true,
"name": "",
"description": "",
"balance": "51.50",
"class": {
"label": "MAR",
"image_url": "https://s3.amazonaws.com/stellar/standard/Screen_Shot.png",
"thumb_image_url": "https://s3.amazonaws.com/stellar/thumb/Screen_Shot.png",
"original_image_url": "https://s3.amazonaws.com/stellar/original/Screen_Shot.png"
},
"auto_reload": true,
"reload_threshold": "20.00",
"reload_amount": "50.00",
"reload_description": "Discover ending in 1117"
},
{
"card_number": "1434414344",
"active": true,
"name": "gc18494856",
"description": "null",
"balance": "90.00",
"auto_reload": false,
"reload_threshold": "",
"reload_amount": "",
"reload_description": ""
}
]
}
}
HTTP Request
GET <base_url>/api/giftcards
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | String (required) | access_token from successful login |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| clipped_only | boolean (optional) | Filter the results to only show clipped gift cards |
| category | string (optional) | Comma-separated string of category internal names of Gift Card Classes to include in the response |
Token for Braintree
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/giftcards/client_token
The above command returns JSON structured like this:
{
"success": true,
"data": {
"client_token": "eyJ2ZXJzaW9uIjoyLCJhdXRob3JpemF0aW9uRmluZ2VycHJpbnQiOiI0ZWYwZWY4NWNiNGM4OGFjYjQ2OWZiZjY1YjVkOTAzODdjYzY2N2VjY2Y3NmFjYzUwMTAxMTc3MDM2MjY1ZDEwfGNyZWF0ZWRfYXQ9MjAxNi0wNS0yNVQwNTo1NDoyMS45MTc5NzYxNTErMDAwMFx1MDAyNm1lcmNoYW50X2lkPXl3c2M5ZnRuamNzdDJtejZcdTAwMjZwdWJsaWNfa2V5PXc3cHdoZzU3cDZjY3AzaDQiLCJjb25maWdVcmwiOiJodHRwczovL2FwaS5zYW5kYm94LmJyYWludHJlZWdhdGV3YXkuY29tOjQ0My9tZXJjaGFudHMveXdzYzlmdG5qY3N0Mm16Ni9jbGllbnRfYXBpL3YxL2NvbmZpZ3VyYXRpb24iLCJjaGFsbGVuZ2VzIjpbXSwiZW52aXJvbm1lbnQiOiJzYW5kYm94IiwiY2xpZW50QXBpVXJsIjoiaHR0cHM6Ly9hcGkuc2FuZGJveC5icmFpbnRyZWVnYXRld2F5LmNvbTo0NDMvbWVyY2hhbnRzL3l3c2M5ZnRuamNzdDJtejYvY2xpZW50X2FwaSIsImFzc2V0c1VybCI6Imh0dHBzOi8vYXNzZXRzLmJyYWludHJlZWdhdGV3YXkuY29tIiwiYXV0aFVybCI6Imh0dHBzOi8vYXV0aC52ZW5tby5zYW5kYm94LmJyYWludHJlZWdhdGV3YXkuY29tIiwiYW5hbHl0aWNzIjp7InVybCI6Imh0dHBzOi8vY2xpZW50LWFuYWx5dGljcy5zYW5kYm94LmJyYWludHJlZWdhdGV3YXkuY29tL3l3c2M5ZnRuamNzdDJtejYifSwidGhyZWVEU2VjdXJlRW5hYmxlZCI6ZmFsc2UsInBheXBhbEVuYWJsZWQiOnRydWUsInBheXBhbCI6eyJkaXNwbGF5TmFtZSI6IlNMIiwiY2xpZW50SWQiOm51bGwsInByaXZhY3lVcmwiOiJodHRwOi8vZXhhbXBsZS5jb20vcHAiLCJ1c2VyQWdyZWVtZW50VXJsIjoiaHR0cDovL2V4YW1wbGUuY29tL3RvcyIsImJhc2VVcmwiOiJodHRwczovL2Fzc2V0cy5icmFpbnRyZWVnYXRld2F5LmNvbSIsImFzc2V0c1VybCI6Imh0dHBzOi8vY2hlY2tvdXQucGF5cGFsLmNvbSIsImRpcmVjdEJhc2VVcmwiOm51bGwsImFsbG93SHR0cCI6dHJ1ZSwiZW52aXJvbm1lbnROb05ldHdvcmsiOnRydWUsImVudmlyb25tZW50Ijoib2ZmbGluZSIsInVudmV0dGVkTWVyY2hhbnQiOmZhbHNlLCJicmFpbnRyZWVDbGllbnRJZCI6Im1hc3RlcmNsaWVudDMiLCJiaWxsaW5nQWdyZWVtZW50c0VuYWJsZWQiOnRydWUsIm1lcmNoYW50QWNjb3VudElkIjoic2wiLCJjdXJyZW5jeUlzb0NvZGUiOiJVU0QifSwiY29pbmJhc2VFbmFibGVkIjpmYWxzZSwibWVyY2hhbnRJZCI6Inl3c2M5ZnRuamNzdDJtejYiLCJ2ZW5tbyI6Im9mZiJ9"
}
}
HTTP Request
GET <base_url>/api/giftcards/client_token
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
Giftcard classes
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/giftcards/classes
The above command returns JSON structured like this:
{
"success": true,
"data": {
"total_pages": 1,
"total_entries": 2,
"classes": [
{
"label": "MLK",
"name": "mlk",
"image_url": "https://s3.amazonaws.com/stellar/standard/Screen_Shot_2016-05-06_at_4.57.44_PM.png",
"thumb_image_url": "https://s3.amazonaws.com/stellar/thumb/Screen_Shot_2016-05-06_at_4.57.44_PM.png",
"original_image_url": "https://s3.amazonaws.com/stellar/original/Screen_Shot_2016-05-06_at_4.57.44_PM.png"
},
{
"label": "Halloween Class",
"name": "halloween_class",
"image_url": "https://s3.amazonaws.com/stellar/standard/Screen_Shot_2016-05-11_at_5.09.45_PM.png",
"thumb_image_url": "https://s3.amazonaws.com/stellar/thumb/Screen_Shot_2016-05-11_at_5.09.45_PM.png",
"original_image_url": "https://s3.amazonaws.com/stellar/original/Screen_Shot_2016-05-11_at_5.09.45_PM.png"
}
]
}
}
HTTP Request
GET <base_url>/api/giftcards/classes
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Name | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | String (required) | access_token from successful login |
Purchase digital gift card
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
-F "amount=<amount>"
-F "payment_method_nonce=<payment_method_nonce>"
<base_url>/api/giftcards/purchase
The above command returns JSON structured like this:
{
"success": true,
"data": {
"giftcard": {
"card_number": "12345678912345",
"active": true,
"name": "Name of Card",
"description": "",
"balance": "2.00",
"auto_reload": false,
"reload_threshold": "",
"reload_amount": "",
"reload_description": ""
},
"transaction": {
"id": "9fq4hx",
"amount": "10.00"
}
}
}
HTTP Request
POST <base_url>/api/giftcards/purchase
Query Parameters
| Name | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | String (required) | access_token from successful login |
| amount | String (required) | Amount to use for purchase |
| payment_method_nonce | String (required) | Payment method nonce from Braintree |
| giftcard_class | String (required) | Specifies a giftcard_class to purchase from; default: default_class seeded initially |
| card_uid | String (optional) | card_uid is the unique identifier of the giftcard |
Get a specific giftcard
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/giftcards/<card_number>
The above command returns JSON structured like this:
{
"success": true,
"data": {
"card_number": "143441234",
"active": true,
"name": "Kat's Awesome Card",
"description": "",
"balance": "2.00",
"class": {
"label": "Summer Theme",
"image_url": "https://s3.amazonaws.com/stellar/standard/Screen_Shot_2016-05-06_at_4.57.44_PM.png",
"thumb_image_url": "https://s3.amazonaws.com/stellar/thumb/Screen_Shot_2016-05-06_at_4.57.44_PM.png",
"original_image_url": "https://s3.amazonaws.com/stellar/original/Screen_Shot_2016-05-06_at_4.57.44_PM.png"
},
"auto_reload": true,
"reload_threshold": "20.00",
"reload_amount": "50.00",
"reload_description": "Visa ending in 1881"
}
}
HTTP Request
GET <base_url>/api/giftcards/<card_number>
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
Update a specific giftcard
curl -X PUT
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
-F "auto_reload=<auto_reload>"
-F "reload_threshold=<reload_threshold>"
-F "reload_amount=<reload_amount>"
-F "name=<name>"
-F "description=<description>"
<base_url>/api/giftcards/<card_number>
The above command returns JSON structured like this:
{
"success": true,
"data": {
"card_number": "143441234",
"active": true,
"name": "My Card",
"description": "",
"balance": "2.00",
"auto_reload": true,
"reload_threshold": "2.00",
"reload_amount": "50.00"
}
}
HTTP Request
PUT <base_url>/api/giftcards/<card_number>
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| auto_reload | Boolean | Flag to indicate if auto-reload is on or off |
| reload_threshold | String | Amount theshold to trigger auto-reload |
| reload_amount | String | Amount to add during auto-reload |
| name | String | Name for gift card |
| description | String | Description for card |
| payment_method_nonce | String | Payment method nonce from Braintree |
Link a member to a gift card
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
-F "pin=<pin>"
<base_url>/api/giftcards/<card_number>/link
The above command returns JSON structured like this:
{
"success": true,
"data": {
"card_number": "143441234",
"active": true,
"name": "",
"description": "",
"balance": "2.00",
"auto_reload": false,
"reload_threshold": "20.00",
"reload_amount": "50.00"
}
}
HTTP Request
POST <base_url>/api/giftcards/<card_number>/link
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| pin | String | PIN of gift card |
Unlink a member to a gift card
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/giftcards/<card_number>/unlink
The above command returns JSON structured like this:
{
"success": true,
"data": {
"card_number": "My Card",
"active": true,
"name": "",
"description": "",
"balance": "25.50",
"auto_reload": false,
"reload_threshold": "20.00",
"reload_amount": "50.00"
}
}
HTTP Request
POST <base_url>/api/giftcards/<card_number>/unlink
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
Top up gift card
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
-F "amount=<amount>"
-F "payment_method_nonce=<payment_method_nonce>"
<base_url>/api/giftcards/<giftcard_number>/credit
The above command returns JSON structured like this:
{
"success": true,
"data": {
"giftcard": {
"card_number": "123456654321",
"active": true,
"name": "",
"description": "",
"balance": "47.00",
"auto_reload": false,
"reload_threshold": "20.00",
"reload_amount": "50.00"
},
"transaction": {
"id": "jf9h9n",
"amount": "10.00"
}
}
}
HTTP Request
POST <base_url>/api/giftcards/<card_number>/credit
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| amount | String (required) | Amount to use for purchase |
| payment_method_nonce | String (required) | Payment method nonce from Braintree |
Get transactions
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/giftcards/<card_number>/transactions
The above command returns JSON structured like this:
{
"success": true,
"data": {
"total_pages": 1,
"total_entries": 4,
"transactions": [
{
"type": "credit",
"created_at": "2016-05-25T06:11:55.000Z",
"description": "",
"amount": "2.00"
},
{
"type": "link",
"created_at": "2016-05-25T06:11:55.000Z",
"description": "",
"amount": "0.00"
},
{
"type": "activate",
"created_at": "2016-05-25T06:11:28.000Z",
"description": "",
"amount": "0.00"
},
{
"type": "start",
"created_at": "2016-05-25T06:11:13.000Z",
"description": "",
"amount": "0.00"
}
]
}
}
HTTP Request
GET <base_url>/api/giftcards/<card_number>/transactions
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
Clip/Unclip a Gift card
To clip a gift card via command line, invoke the following
cURLcommand:
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/giftcards/<card_number>/clip
To unclip a gift card via command line, invoke the following
cURLcommand:
curl -X DELETE
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/giftcards/<card_number>/clip
Successful clipping returns JSON structured like this:
{
"success": true,
"data": {
"card_number": "12345678",
"active": true,
"clipped": true,
"name": "",
"description": "",
"balance": "0.00",
"currency": "USD",
"usage_start_date": "null",
"usage_end_date": "null",
"usage_schedule": "null",
"class": {
"title": "Default Class",
"label": "Default Class",
"name": "default_class",
"response_start_date": "null",
"response_end_date": "null",
"response_schedule": "null",
"heading": "Default Class",
"subheading": "",
"body": "",
"subject": "",
"details": "",
"action": "",
"heading_color": "",
"color": "",
"bgcolor": "",
"heading_bgcolor": "",
"image1_bg": "",
"layout_id": "master",
"image_url": "/images/standard/missing.png",
"thumb_image_url": "/images/thumb/missing.png",
"original_image_url": "/images/original/missing.png",
"respondable": true,
"respondable_info": {
"value": true,
"code": "",
"message": ""
}
},
"auto_reload": true,
"reload_threshold": "300.00",
"reload_amount": "100.00",
"reload_description": "null"
}
}
Successful unclipping returns JSON structured like this:
{
"success": true,
"data": {
"card_number": "12345678",
"active": true,
"clipped": false,
"name": "",
"description": "",
"balance": "0.00",
"currency": "USD",
"usage_start_date": "null",
"usage_end_date": "null",
"usage_schedule": "null",
"class": {
"title": "Default Class",
"label": "Default Class",
"name": "default_class",
"response_start_date": "null",
"response_end_date": "null",
"response_schedule": "null",
"heading": "Default Class",
"subheading": "",
"body": "",
"subject": "",
"details": "",
"action": "",
"heading_color": "",
"color": "",
"bgcolor": "",
"heading_bgcolor": "",
"image1_bg": "",
"layout_id": "master",
"image_url": "/images/standard/missing.png",
"thumb_image_url": "/images/thumb/missing.png",
"original_image_url": "/images/original/missing.png",
"respondable": true,
"respondable_info": {
"value": true,
"code": "",
"message": ""
}
},
"auto_reload": true,
"reload_threshold": "300.00",
"reload_amount": "100.00",
"reload_description": "null"
}
}
HTTP Request
POST <base_url>/api/giftcards/<card_number>/clip
DELETE <base_url>/api/giftcards/<card_number>/clip
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
Punch Cards
List All Punch Card Types
To get all possible published types of punch cards, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/punchcards/types
If successful, the response should look like this:
{
"success": true,
"data": {
"total_pages": 1,
"total_entries": 2,
"punchcards": [
{
"id": 14,
"label": "coffee place",
"name": "coffee_place",
"description": "",
"required_punches": 8,
"created": "2017-03-23T07:38:36.000Z",
"published_at": "2017-03-23T07:40:01.000Z",
"status": "published",
"effectivity_start": null,
"effectivity_end": null,
"expiration_type": "fixed_date",
"respondable": true,
"heading": "coffee place",
"subheading": "",
"body": "",
"details": "",
"image_url": "",
"thumb_image_url": "",
"original_image_url": "",
"subject": "",
"action": "",
"heading_color": "",
"color": "",
"bgcolor": "",
"heading_bgcolor": "",
"image1_bg": "",
"layout_id": "master",
"expiration_date": "2017-04-27T15:38:00.000Z",
"punches" : [
{
"id": 1,
"label" : "Special Drink",
"name" : "special",
"sequence" : 1,
"image_url" : "http://example.com/image.png",
"max_allowed" : 5
},
{
"id": 2,
"label" : "Regular Drink",
"name" : "regular",
"sequence" : 2,
"image_url" : "http://example.com/image.png",
"max_allowed" : 3
}
],
"rewards" : [
{
"id": 1,
"punches": 8,
"prize_id": 10,
"prize_type": "Offer",
"metric_name" : "points",
"metric_amount" : 100
}
]
},
{
"id": 13,
"label": "coffee card",
"name": "coffee_card",
"description": "",
"required_punches": 5,
"created": "2017-03-23T07:37:05.000Z",
"published_at": "2017-03-23T07:37:44.000Z",
"status": "published",
"effectivity_start": null,
"effectivity_end": null,
"expiration_type": "none",
"respondable": true,
"heading": "coffee card",
"subheading": "",
"body": "",
"details": "",
"image_url": "",
"thumb_image_url": "",
"original_image_url": "",
"subject": "",
"action": "",
"heading_color": "",
"color": "",
"bgcolor": "",
"heading_bgcolor": "",
"image1_bg": "",
"layout_id": "master",
"prize_name": "coffee_card",
"punches" : [
{
"id": 1,
"label" : "Seasonal Drink",
"name" : "seasonal",
"sequence" : 1,
"image_url" : "http://example.com/image.png",
"max_allowed" : 5
},
{
"id": 2,
"label" : "Regular Drink",
"name" : "regular",
"sequence" : 2,
"image_url" : "http://example.com/image.png",
"max_allowed" : 3
}
],
"rewards" : [
{
"id": 1,
"punches": 3,
"prize_id": 11,
"prize_type": "Reward",
"metric_name" : "points",
"metric_amount" : 100
}
{
"id": 2,
"punches": 8,
"prize_id": 10,
"prize_type": "Offer",
"metric_name" : "points",
"metric_amount" : 100
}
]
}
]
}
}
Lists all published punch card types. If respondable is set, then only punch card types that are applicable to the current user will be returned.
HTTP Request
GET <base_url>/api/punchcards/types
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| page | integer (optional) | For pagination, specifies the page number |
| per_page | integer (optional) | The number of results per page, defaults to program settings value |
| respondable | boolean (optional) | Retrieve only punchcard types that the user is allowed to obtain. |
Get Punch Card Type Detail
To obtain information about a specific punch card type, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/punchcards/types/<id>
If successful, the response should look like this:
{
"success": true,
"data": {
"id": 169,
"label": "Iron Fist Punch!!!",
"name": "iron_first_punch",
"description": "",
"required_punches": 5,
"created": "2017-09-19T12:31:32.000Z",
"published_at": "2017-09-20T04:15:13.000Z",
"status": "published",
"expiration_type": "none",
"effectivity_start": null,
"effectivity_end": null,
"response_start_date": null,
"response_end_date": null,
"response_schedule": null,
"respondable": true,
"respondable_info": {
"value": true,
"code": "",
"message": ""
},
"heading": "Iron First Punch",
"subheading": "",
"body": "",
"details": "",
"image_url": "https://s3.amazonaws.com/stellar-growingtree-qyxdn1uk2xgzssjk6wya/contents/4978/static_files/iron02_2_2_2_2.jpg?1511780472",
"thumb_image_url": "https://s3.amazonaws.com/stellar-growingtree-qyxdn1uk2xgzssjk6wya/contents/4978/static_files/iron02_2_2_2_2.jpg?1511780472",
"original_image_url": "https://s3.amazonaws.com/stellar-growingtree-qyxdn1uk2xgzssjk6wya/contents/4978/static_files/iron02_2_2_2_2.jpg?1511780472",
"subject": "",
"action": "",
"heading_color": "",
"color": "",
"bgcolor": "",
"heading_bgcolor": "",
"image1_bg": "",
"layout_id": "master",
"punches": [
{
"id": 40,
"label": "kat",
"name": "kat",
"sequence": null,
"max_allowed": 1,
"image_url": "/images/thumb/missing.png"
}
],
"rewards": [
{
"id": 19,
"punches": 2,
"metric_name": "",
"metric_amount": null,
"upgrade_tier": false
}
],
"locations": []
}
}
Get details of a punchcard type given an id
HTTP Request
GET <base_url>/api/punchcards/types/:id
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| id | integer | The id of the punchcard type |
{
"success": true,
"data": {
"id": 169,
"label": "Iron Fist Punch!!!",
"name": "iron_first_punch",
"description": "",
"required_punches": 5,
"created": "2017-09-19T12:31:32.000Z",
"published_at": "2017-09-20T04:15:13.000Z",
"status": "published",
"expiration_type": "none",
"effectivity_start": null,
"effectivity_end": null,
"response_start_date": null,
"response_end_date": null,
"response_schedule": null,
"respondable": true,
"respondable_info": {
"value": true,
"code": "",
"message": ""
},
"heading": "Iron First Punch",
"subheading": "",
"body": "",
"details": "",
"image_url": "https://s3.amazonaws.com/stellar-growingtree-qyxdn1uk2xgzssjk6wya/contents/4978/static_files/iron02_2_2_2_2.jpg?1511780472",
"thumb_image_url": "https://s3.amazonaws.com/stellar-growingtree-qyxdn1uk2xgzssjk6wya/contents/4978/static_files/iron02_2_2_2_2.jpg?1511780472",
"original_image_url": "https://s3.amazonaws.com/stellar-growingtree-qyxdn1uk2xgzssjk6wya/contents/4978/static_files/iron02_2_2_2_2.jpg?1511780472",
"subject": "",
"action": "",
"heading_color": "",
"color": "",
"bgcolor": "",
"heading_bgcolor": "",
"image1_bg": "",
"layout_id": "master",
"punches": [
{
"id": 40,
"label": "kat",
"name": "kat",
"sequence": null,
"max_allowed": 1,
"image_url": "/images/thumb/missing.png"
}
],
"rewards": [
{
"id": 19,
"punches": 2,
"metric_name": "",
"metric_amount": null,
"upgrade_tier": false
}
],
"locations": []
}
}
Accept Punch Card Type
To accept the member punch cards of a punch card type, invoke the following
cURLcommand:
curl --location --request POST '<base_url>/api/punchcards/types/<id_or_name>/accept' \
--header 'Accept: application/vnd.stellar-v1+json' \
--header 'Authorization: Bearer <access_token>'
If successful, the response should look like this:
{
"success": true
}
Accepts a punch card given the punch card type identifier. When a punch card is accepted, prizes will be awarded once the member obtains the required number of punches defined in the prize rules.
HTTP Request
POST <base_url>/api/punchcards/types/<id>/accept
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| id | integer | The id or name of the punchcard type |
List Punch Cards
To get member's punch cards via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/punchcards
If successful, the response should look like this:
{
"success": true,
"data": {
"total_pages": 1,
"total_entries": 2,
"punchcards": [
{
"id": 19,
"name": "bandwidth13",
"label": "bandwidth13",
"status": "active",
"description": "Try to program the SAS card, maybe it will connect the primary transmitter!",
"required_punches": 20,
"effectivity_start": "null",
"effectivity_end": "null",
"usage_start_date": "null",
"usage_end_date": "null",
"usage_schedule": "null",
"heading": "bandwidth13",
"subheading": "",
"body": "",
"details": "",
"image_url": "",
"thumb_image_url": "",
"original_image_url": "",
"punches": 0,
"start_date": "2018-07-24T04:43:50.000Z",
"expiration": "null",
"punch_detail": [
],
"punchcard_type": {
"id": 13,
"created": "2018-07-24T04:43:49.000Z",
"published_at": "2018-07-24T04:43:49.000Z",
"status": "published",
"expiration_type": "none",
"respondable": true,
"punches": [
],
"rewards": [
]
}
},
{
"id": 20,
"name": "circuit14",
"label": "circuit14",
"status": "active",
"description": "Try to program the SAS card, maybe it will connect the primary transmitter!",
"required_punches": 20,
"effectivity_start": "null",
"effectivity_end": "null",
"usage_start_date": "null",
"usage_end_date": "null",
"usage_schedule": "null",
"heading": "circuit14",
"subheading": "",
"body": "",
"details": "",
"image_url": "",
"thumb_image_url": "",
"original_image_url": "",
"punches": 0,
"start_date": "2018-07-24T04:43:50.000Z",
"expiration": "null",
"punch_detail": [
],
"punchcard_type": {
"id": 14,
"created": "2018-07-24T04:43:50.000Z",
"published_at": "2018-07-24T04:43:50.000Z",
"status": "published",
"expiration_type": "none",
"respondable": true,
"punches": [
],
"rewards": [
]
}
}
]
}
}
Lists all punchcards currently owned by user.
HTTP Request
GET <base_url>/api/punchcards
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| page | integer (optional) | For pagination, specifies the page number |
| per_page | integer (optional) | The number of results per page, defaults to program settings value |
| category | string (optional) | key from the list of Punch Card Categories |
| status | string (optional) | Filter by status, Values can be active, expired, all or completeddefault: active |
| show_hidden | boolean (optional) | Shows invisible punch cards default: false |
| sort_by | string (optional) | Sort options. Values can be effectivity_start, effectivity_end, expiration_date, update_date, publish_date, name, label, points or required_metric |
| details_sort_by | string (optional) | If a punchcard has named punches, this parameter sorts this list. Values can be created_at, updated_at or label |
| details_sort_dir | string (optional) | If a punchcard has named punches this sort spunch details direction. Values can be desc or asc |
| virtual | boolean (optional) | If set to true, eligible punch card types will be mixed in the response and will appear as empty punch cards default: false |
| hide_expired | boolean (optional) | Hide expired punchcards default: true |
| sort_dir | string (optional) | Sort direction. Values can be desc or asc default: desc NOTE: default is desc if sort_by is date otherwise asc |
| show_contents | boolean (optional) | Shows punch card contents default: true |
{
"success": true,
"data": {
"total_pages": 1,
"total_entries": 2,
"punchcards": [
{
"id": 19,
"name": "bandwidth13",
"label": "bandwidth13",
"status": "active",
"description": "Try to program the SAS card, maybe it will connect the primary transmitter!",
"required_punches": 20,
"effectivity_start": "null",
"effectivity_end": "null",
"usage_start_date": "null",
"usage_end_date": "null",
"usage_schedule": "null",
"heading": "bandwidth13",
"subheading": "",
"body": "",
"details": "",
"image_url": "",
"thumb_image_url": "",
"original_image_url": "",
"punches": 0,
"start_date": "2018-07-24T04:43:50.000Z",
"expiration": "null",
"punch_detail": [
],
"punchcard_type": {
"id": 13,
"created": "2018-07-24T04:43:49.000Z",
"published_at": "2018-07-24T04:43:49.000Z",
"status": "published",
"expiration_type": "none",
"respondable": true,
"punches": [
],
"rewards": [
]
}
},
{
"id": 20,
"name": "circuit14",
"label": "circuit14",
"status": "active",
"description": "Try to program the SAS card, maybe it will connect the primary transmitter!",
"required_punches": 20,
"effectivity_start": "null",
"effectivity_end": "null",
"usage_start_date": "null",
"usage_end_date": "null",
"usage_schedule": "null",
"heading": "circuit14",
"subheading": "",
"body": "",
"details": "",
"image_url": "",
"thumb_image_url": "",
"original_image_url": "",
"punches": 0,
"start_date": "2018-07-24T04:43:50.000Z",
"expiration": "null",
"punch_detail": [
],
"punchcard_type": {
"id": 14,
"created": "2018-07-24T04:43:50.000Z",
"published_at": "2018-07-24T04:43:50.000Z",
"status": "published",
"expiration_type": "none",
"respondable": true,
"punches": [
],
"rewards": [
]
}
}
]
}
}
Below is a sample response if the punch card has named punches:
{
"success": true,
"data": {
"total_pages": 1,
"total_entries": 1,
"punchcards": [
{
"id": 284,
"name": "coffee_bean",
"label": "coffee bean",
"status": "active",
"description": "",
"required_punches": 8,
"effectivity_start": "null",
"effectivity_end": "null",
"heading": "coffee bean",
"subheading": "",
"body": "",
"details": "",
"image_url": "",
"thumb_image_url": "",
"original_image_url": "",
"subject": "",
"action": "",
"heading_color": "",
"color": "",
"bgcolor": "",
"heading_bgcolor": "",
"image1_bg": "",
"layout_id": "master",
"punches": 3,
"punch_detail": [
{
"name": "regular",
"punches": 1,
"punched_date": "2016-11-28T07:29:04.000Z",
"label" : "Regular Coffee",
"image_url" : "null"
},
{
"name": "special",
"punches": 2,
"punched_date": "2016-11-28T07:29:04.000Z",
"label" : "Heineken",
"image_url" : "null"
}
],
"start_date": "2017-03-31T08:11:59.000Z",
"expiration": "2017-04-27T15:38:00.000Z",
"punchcard_type": {
"id": 14,
"created": "2017-03-23T07:38:36.000Z",
"published_at": "2017-03-23T07:40:01.000Z",
"status": "published",
"expiration_type": "fixed_date",
"respondable": true,
"expiration_date": "2017-04-27T15:38:00.000Z",
"punches" : [
{
"id": 1,
"label" : "Seasonal Drink",
"name" : "seasonal",
"sequence" : 1,
"image_url" : "http://example.com/image.png",
"max_allowed" : 5
},
{
"id": 2,
"label" : "Regular Drink",
"name" : "regular",
"sequence" : 2,
"image_url" : "http://example.com/image.png",
"max_allowed" : 3
},
{
"id": 3,
"label" : "Extra special Drink",
"name" : "extra_special",
"sequence" : 3,
"image_url" : "http://example.com/image.png",
"max_allowed" : 4
}
],
"rewards" : [
{
"id": 1,
"punches": 3,
"prize_id": 11,
"prize_type": "Reward",
"metric_name" : "points",
"metric_amount" : 100
},
{
"id": 2,
"punches": 8,
"prize_id": 10,
"prize_type": "Offer",
"metric_name" : "points",
"metric_amount" : 100
}
]
}
}
]
}
}
Get Punch Card
To get a specific punch card instance by ID via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/punchcard/<id>
If successful, the response should look like this:
{
"success": true,
"data": {
"id": 35,
"member_id": 11,
"name": "transmitter25",
"label": "transmitter25",
"status": "active",
"description": "You can't compress the hard drive without generating the optical SMS matrix!",
"required_punches": 20,
"effectivity_start": "null",
"effectivity_end": "null",
"usage_start_date": "null",
"usage_end_date": "null",
"usage_schedule": "null",
"heading": "transmitter25",
"subheading": "",
"body": "",
"details": "",
"image_url": "",
"thumb_image_url": "",
"original_image_url": "",
"punches": 0,
"start_date": "2018-07-24T04:50:39.000Z",
"expiration": "null",
"punch_detail": [
],
"punchcard_type": {
"id": 25,
"created": "2018-07-24T04:50:39.000Z",
"published_at": "2018-07-24T04:50:39.000Z",
"status": "published",
"expiration_type": "none",
"respondable": true,
"punches": [
],
"rewards": [
]
},
"transactions": [
]
}
}
Lists all punchcards currently owned by user.
HTTP Request
GET <base_url>/api/punchcard/<id>
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| id | integer (required) | Punchcard id |
{
"success": true,
"data": {
"id": 35,
"member_id": 11,
"name": "transmitter25",
"label": "transmitter25",
"status": "active",
"description": "You can't compress the hard drive without generating the optical SMS matrix!",
"required_punches": 20,
"effectivity_start": "null",
"effectivity_end": "null",
"usage_start_date": "null",
"usage_end_date": "null",
"usage_schedule": "null",
"heading": "transmitter25",
"subheading": "",
"body": "",
"details": "",
"image_url": "",
"thumb_image_url": "",
"original_image_url": "",
"punches": 0,
"start_date": "2018-07-24T04:50:39.000Z",
"expiration": "null",
"punch_detail": [
],
"punchcard_type": {
"id": 25,
"created": "2018-07-24T04:50:39.000Z",
"published_at": "2018-07-24T04:50:39.000Z",
"status": "published",
"expiration_type": "none",
"respondable": true,
"punches": [
],
"rewards": [
]
},
"transactions": [
]
}
}
Get Punch Card Status
To show the progress of a member punch card, invoke the following
cURLcommand:
curl --location '<base_url>/api/punchcards/<id>/status' \
--header 'Accept: application/vnd.stellar-v1+json' \
--header 'Authorization: Bearer <access_token>'
If successful, the response should look like this:
{
"success": true,
"data": {
"label": "Punchcard_23975_220202202100728_SP730554_child1",
"status": "active",
"accepted_at": null,
"first_punched_at": null,
"prizes": {
"next_prizes": [
{
"id": null,
"prize": null,
"prize_type": null,
"metric_amount": 20,
"metric_name": "point",
"remaining_punches": 1
}
],
"issued_prizes": []
},
"punches": [],
"expiration": {
"expires_at": null,
"continuity": null
}
}
}
Shows the progress of a punch card. The response includes the status (active, missed, lapsed, cancelled, reprocessed,
inactive, completed, expired), prizes, opt-in date, expiration date, and continuity date.
HTTP Request
GET <base_url>/api/punchcard/<id>/status
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| id | integer (required) | Punchcard id |
Accept Punch Card
To accept a member punch card, invoke the following
cURLcommand:
curl --location --request POST '<base_url>/api/punchcards/<id>/accept' \
--header 'Accept: application/vnd.stellar-v1+json' \
--header 'Authorization: Bearer <access_token>'
If successful, the response should look like this:
{
"success": true
}
Accepts a punch card given the punch card identifier. When a punch card is accepted, prizes will be awarded once the member obtains the required number of punches defined in the prize rules.
HTTP Request
POST <base_url>/api/punchcards/<id>/accept
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| id | integer (required) | Punchcard id |
Create Punch Card Punch
To post a punch to a punch card for the current user, invoke the following
cURLcommand:
curl --location --request POST '<base_url>/api/punchcards/punch' \
--header 'Accept: application/vnd.stellar-v1+json' \
--header 'Authorization: Bearer <access_token>' \
--form 'email=urban_hilll@ewell.org' \
--form 'punchcard=iron_first_punch' \
--form 'amount=2' \
--form 'punches=1'
If successful, the response should look like this:
{
"success": true,
"id": 568,
"status": "active",
"required_punches": 5,
"punches": 2,
"punch_detail": []
}
Creates a punch for the current user
HTTP Request
POST <base_url>/api/punchcards/punch
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| punchcard | string (required) | The internal name of the punchcard type |
| punches | integer (required if punch_names or punch_values not specified | The number of punches to give |
| punch_names | string (required if punches or punch_values) not specified | A comma seperated list of named punches to give or with colons if a value is to be specified for each (e.g. name1,name2, name3:1,name4:2) |
| punch_values | string (required if punches or punch_names) not specified | A comma seperated list of named punch values to give or with colons if a value is to be specified for each (e.g. VAL001,VAL002,VAL003:1,VAL004:2) |
{
"success": true,
"id": 568,
"status": "active",
"required_punches": 5,
"punches": 4,
"punch_detail": []
}
Passes
To get member's installed passes via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/passes
If successful, the response should look like this:
{
"success": true,
"data": {
"passes": [
{
"id": 28,
"label": "Tim Test v13",
"name": "tim_test_v13",
"description": "",
"type": "storeCard",
"serial_number": "3388000000022142966.tim_test_v13.LOY062022-0000000023",
"version": "1667465287",
"installed_at": "2022-11-03T08:03:50.000Z",
"last_updated_at": "2022-11-03T08:48:07.000Z",
"latest_message": null
},
{
"id": 29,
"label": "Tim Test v14",
"name": "tim_test_v14",
"description": "",
"type": "storeCard",
"serial_number": "3388000000022142966.tim_test_v14.LOY062022-0000000023",
"version": "1667557386",
"installed_at": "2022-11-03T08:56:55.000Z",
"last_updated_at": "2022-11-04T10:23:06.000Z",
"latest_message": null
}
]
}
}
Lists all pass installation currently owned by user.
HTTP Request
GET <base_url>/api/passes
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| page | integer (optional) | For pagination, specifies the page number |
| per_page | integer (optional) | The number of results per page, defaults to program settings value |
Pass Embed
Get minimum details of a Pass needed for embedding, given the pass' internal name via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/passes/<pass_name>/embed
If successful, the response should look like this:
{
"success": true,
"data": {
"id": 30,
"label": "Tim Test v15",
"name": "tim_test_v15",
"description": "",
"type": "storeCard",
"install_status": {
"apple": "never",
"google": [
{
"status": "installed"
}
]
},
"download_url": "https://growingtree.demostellar.com/pass/download/021175b94ff30491630801da896204ae6123963b437ca0885e23c31a2e786c3c",
"pass_json": {
"description": "No description",
"foregroundColor": "#383838",
"backgroundColor": "#FFFFFF",
"labelColor": "#383838",
"storeCard": {
"headerFields": [],
"primaryFields": [],
"secondaryFields": [],
"auxiliaryFields": [],
"backFields": []
}
},
"download_qr_code": "",
"logo": "/images/original/missing.png",
"thumbnail": "/images/original/missing.png",
"strip": "/images/original/missing.png",
"icon": "/images/original/missing.png",
"background": "/images/original/missing.png",
"google_hero_image": "https://s3.us-east-1.amazonaws.com/stellar-tnf-staging-4iqch3u8w40elu1o81pt/passes/hero_images/000/000/030/original/beacon-hero.png?1668050847",
"google_main_image": "https://s3.us-east-1.amazonaws.com/stellar-tnf-staging-4iqch3u8w40elu1o81pt/passes/main_images/000/000/030/original/beacon-main.png?1668050849",
"google_program_logo": "https://s3.us-east-1.amazonaws.com/stellar-tnf-staging-4iqch3u8w40elu1o81pt/passes/program_logos/000/000/030/original/beacon-logo.png?1668050849",
"s2gp_jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJ0aW0tbG9jYWwtZGV2QGNoZWV0YWgtdGltLWxvY2FsLWRldi5pYW0uZ3NlcnZpY2VhY2NvdW50LmNvbSIsImF1ZCI6Imdvb2dsZSIsInR5cCI6InNhdmV0b3dhbGxldCIsImlhdCI6MTY2OTk1MzUyMiwib3JpZ2lucyI6WyJodHRwOi8vbG9jbGFob3N0OjgwODAiXSwicGF5bG9hZCI6eyJsb3lhbHR5T2JqZWN0cyI6W3sia2luZCI6IndhbGxldG9iamVjdHMjbG95YWx0eU9iamVjdCIsInN0YXRlIjoiaW5hY3RpdmUiLCJpZCI6IjMzODgwMDAwMDAwMjIxNDI5NjYudGltX3Rlc3RfdjE1LkxPWTA2MjAyMi0wMDAwMDAwMDIzIiwiY2xhc3NJZCI6IjMzODgwMDAwMDAwMjIxNDI5NjYudGltX3Rlc3RfdjE1In1dLCJsb3lhbHR5Q2xhc3NlcyI6W10sIm9mZmVyT2JqZWN0cyI6W10sIm9mZmVyQ2xhc3NlcyI6W10sImdpZnRDYXJkT2JqZWN0cyI6W10sImdpZnRDYXJkQ2xhc3NlcyI6W10sImV2ZW50VGlja2V0T2JqZWN0cyI6W10sImV2ZW50VGlja2V0Q2xhc3NlcyI6W119fQ.rn9e6_7zHIhJku-wlnzVg5bnkZ303RHkfnJQAV6GF91B5UsSKE0zvW4OFAQBOvwE2GemEPB2thfU8xX1Af9lKaBwJlrOTEmDeT1zY5BT7_DY4P9xSNHy419QlBMHTvtoWpDVvoMF96ysmJkpA3ictJi9FqU6qABsFa_fOybS8FYQRgsMOp9LAdThlUN0eWIPwEbTIORFau1hp59zDj1rw81pGiVQrW4be9neR-xxkxGtcLtVnG7QcrOcU0lOri4CRK3Jqi_nxNSg2tPLSvaM-1Nwklm2LEOeFgRu7EEmyPzOvvRb7KvuYFV66KEKPrpSlZbidorXIIZVToE0XGGlrQ"
}
}
minimum details of a Pass needed for embedding
HTTP Request
GET <base_url>/api/passes/<pass_name>/embed
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| pass_name | string (required) | Pass' internal name |
| origin | string (optional) | URLs CSV of the embedding web page/s |
Google Install
Create a Google Pass Installation via command line, invoke the following
cURLcommand:
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/passes/<pass_name>/google_install
If successful, the response should look like this:
{
"success": true,
"data": {
"id": 41,
"user_device_id": null,
"pass_id": 30,
"member_id": 28,
"serial_number": "3388000000022142966.tim_test_v15.LOY062022-0000000028",
"version": "1669958878",
"overrides": {},
"current_pass_data": {
"kind": "walletobjects#loyaltyObject",
"id": "3388000000022142966.tim_test_v15.LOY062022-0000000028",
"classId": "3388000000022142966.tim_test_v15",
"state": "active",
"loyaltyPoints": {
"label": "Points",
"balance": {
"string": "10"
}
},
"secondaryLoyaltyPoints": {
"label": "",
"balance": {
"string": ""
}
},
"barcode": {
"kind": "walletobjects#barcode",
"type": "qrCode",
"value": "Testing Barcode",
"alternateText": ""
}
},
"latest_message": null,
"latest_message_notification": null,
"deleted_at": null,
"activated_at": "2022-12-02T05:27:53.799Z",
"created_at": "2022-12-02T05:27:53.825Z",
"updated_at": "2022-12-02T05:27:58.008Z",
"latest_message_header": null,
"latest_message_interval": {}
}
}
Create a Google Pass Installation
HTTP Request
POST <base_url>/api/passes/<pass_name>/google_install
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| serial_number | string (optional) | Generated card ID when member installs the Pass, e.g. 3274402460030480506.loyalty.EVE-000000063. Note: The value of the serial_number can be found by inspecting JWT returned value of the /api/passes/ |
| pass_name | string (required) | Pass' internal name |
Push Updates
Update the device passes of a member, given the pass' internal name via command line, invoke the following
cURLcommand:
curl -X PUT
-H 'Accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/passes/<pass_name>/push_updates
If successful, the response should look like this:
{
"success": true,
"data": [
{
"id": 41,
"user_device_id": null,
"pass_id": 30,
"member_id": 28,
"serial_number": "3388000000022142966.tim_test_v15.LOY062022-0000000028",
"version": "1669959147",
"overrides": {},
"current_pass_data": {
"kind": "walletobjects#loyaltyObject",
"id": "3388000000022142966.tim_test_v15.LOY062022-0000000028",
"classId": "3388000000022142966.tim_test_v15",
"state": "active",
"loyaltyPoints": {
"label": "Points",
"balance": {
"string": "10"
}
},
"secondaryLoyaltyPoints": {
"label": "",
"balance": {
"string": ""
}
},
"barcode": {
"kind": "walletobjects#barcode",
"type": "qrCode",
"value": "Testing Barcode",
"alternateText": ""
}
},
"latest_message": null,
"latest_message_notification": null,
"deleted_at": null,
"activated_at": "2022-12-02T05:27:53.000Z",
"created_at": "2022-12-02T05:27:53.000Z",
"updated_at": "2022-12-02T05:32:27.569Z",
"latest_message_header": null,
"latest_message_interval": {}
}
]
}
Update the device passes of a member, given the pass' internal name
HTTP Request
PUT <base_url>/api/passes/<pass_name>/push_updates
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (required) | access_token from successful login |
| pass_name | string (required) | Pass' internal name |
Feedbacks
Submit Feedback
Allows the user to submit a feedback. When used while the member is logged-in, it will override the email, first name and last name parameter. An email will be sent to the Feedback Recipient set in the Program Settings.
To submit a fedback via command line, invoke the following
cURLcommand:
curl -X POST
-H 'accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
-F 'email=riley_greenholt@example.net'
-F 'first_name=Riley'
-F 'last_name=Greenholt'
-F 'category=pricing'
-F 'subject=Rates Inquiry'
-F 'body=Dolorem voluptas ipsum eos porro vitae consectetur adipisci. In eum alias voluptate praesentium ut.'
<base_url>/api/feedbacks
If successful, the response should look like this:
{
"success": true,
"data": {}
}
HTTP Request
POST <base_url>/api/feedbacks
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (optional) | access_token from successful login. |
| subject | string (required) | Subject of the feedback |
| body | string (required) | Message body of the feedback |
| category | string (optional) | Category of the feedback |
| string (optional) | Email of the member. This will be overridden with the logged-in member. | |
| first_name | string (optional) | First name of the member. This will be overridden with the logged-in member. |
| last_name | string (optional) | Last name of the member. This will be overridden with the logged-in member. |
Get Feedback Categories
Lists all feedback categories
To get the list of feedback categories via command line, invoke the following
cURLcommand:
curl -X GET
-H 'accept: application/vnd.stellar-v1+json'
-H 'Authorization: Bearer <access_token>'
<base_url>/api/feedbacks/categories
If successful, the response should look like this:
{
"success": true,
"data": {
"customer_support": {
"label": "Customer Support",
"recipients": "cs@example.com"
},
"sysadmin": {
"label": "SysAdmin",
"recipients": "admin@example.com"
},
"test": {
"label": "Test",
"recipients": "test@example.com"
}
}
}
HTTP Request
GET <base_url>/api/feedbacks/categories
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| [DEPRECATED] access_token | string (optional) | access_token from successful login. |
Location Tracking
If location tracking is available in the server, API calls can pass the location for tracking.
To track the location, the location data should be set in the HTTP header when calling the endpoints. The data will then be used to resolve the location from the pool of places set in the Marketing Console.
Via HTTP Headers
Passing the location via HTTP headers works on all API endpoints.
Via Coordinates
To pass the coordinates, add a header parameter sl-user-location with the coordinates in a JSON string in lat and lon keys. These coordinates will be resolved to the nearest location from the pool of places defined in the marketing console. It will also track the original coordinates and its distance to the nearest place.
To pass the coordinates via
cURLcommand:
curl -X POST
-H 'accept: application/vnd.stellar-v1+json'
-H 'sl-user-location: { \"lat\": 37.563855, \"lon\": -122.268522 }'
-H 'Authorization: Bearer <access_token>'
<base_url>/<api endpoint>
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
| Sl-User-Location | json (required) | JSON encoded hash of lat and long |
Via Location Internal Name
To pass the location internal name, add a header parameter sl-user-location with the location's internal name in a json hash in the place key. This internal name will be resolved from the places defined in the marketing console.
To pass the location internal id via
cURLcommand:
curl -X POST
-H 'accept: application/vnd.stellar-v1+json'
-H 'sl-user-location: { \"place\": \"stellar_locayalty_office\" }'
-H 'Authorization: Bearer <access_token>'
<base_url>/<api endpoint>
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
| Sl-User-Location | json (required) | JSON encoded hash of place with location's internal name |
Via Location Integration ID
To pass the location integration id, add a header parameter sl-user-location with the location's integration id in a JSON hash in the place key. This integration id will be resolved from the places defined in the marketing console.
To pass the location integration id via
cURLcommand:
curl -X POST
-H 'accept: application/vnd.stellar-v1+json'
-H 'sl-user-location: { \"place\": \"111111\" }'
-H 'Authorization: Bearer <access_token>'
<base_url>/<api endpoint>
Header Parameters
| Parameter | Type | Value |
|---|---|---|
| Accept | string (required) | application/vnd.stellar-v1+json |
| Authorization | string (required) | Bearer <access_token> |
| Sl-User-Location | json (required) | JSON encoded hash of place with location's integration id |
Errors
This list can be downloaded from GET <base_url>/api/error_definitions using either access_token or a pair of valid client_id and client_secret
The Marigold Loyalty API uses the following error codes:
| Error Code | Name | Description |
|---|---|---|
| 4000 | missing_token | Access token is required. |
| 4001 | invalid_token | Access token is invalid. |
| 4002 | expired_token | Access token is expired. |
| 4003 | revoked_token | Access token was revoked. |
| 4004 | unauthorized_token | Access token is unauthorized to access this endpoint. |
| 4005 | invalid_grant | The provided authorization grant is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client. |
| 4006 | oauth_email | Email cannot be blank or it cannot be read from given provider. |
| 4007 | oauth_email_first_name | Email and first name cannot be blank. |
| 4008 | oauth_email_first_name_last_name | Email, first name and last name cannot be blank. |
| 4009 | oauth_email_first_name_last_name_token | Email, first name, last name and token cannot be blank or token submitted. is invalid |
| 4010 | oauth_email_first_name_token | Email, first name and token cannot be blank or token submitted is invalid. |
| 4011 | oauth_email_last_name | Email and last name cannot be blank. |
| 4012 | oauth_email_last_name_token | Email, last name and token cannot be blank or token submitted is invalid. |
| 4013 | oauth_email_token | Email and token cannot be blank or token submitted is invalid. |
| 4014 | oauth_first_name | First name cannot be blank. |
| 4015 | oauth_first_name_last_name | First name and last name cannot be blank. |
| 4016 | oauth_first_name_last_name_token | First name, last name and token cannot be blank or token submitted is invalid. |
| 4017 | oauth_first_name_token | First name and token cannot be blank or token submitted is invalid. |
| 4018 | oauth_last_name | Last name cannot be blank. |
| 4019 | oauth_last_name_token | Last name and token cannot be blank or token submitted is invalid. |
| 4020 | oauth_token | Token cannot be blank or is invalid. |
| 4021 | oauth_invalid_provider | Assertion provider is invalid and can only be either facebook or google. |
| 4022 | oauth_member_does_not_exist | Member does not exist. |
| 4023 | oauth_member_already_registered | Member is already registered. |
| 4024 | oauth_member_deactivated | Member account is deactivated. |
| 4025 | missing_credentials | Client credentials are required. |
| 4026 | reset_password | Reset password required. |
| 4027 | assertion_no_matching_email | Email not registered. |
| 4028 | member_save_failed | Member login failed, please try again later. |
| 4029 | require_confirmation | You have to confirm your email address before continuing. |
| 4030 | unauthorized | You are not authorized to connect to member. |
| 4040 | endpoint_error | Endpoint not found. |
| 4044 | not_available | Resource not available. |
| 4060 | invalid_params | Given parameters are invalid. |
| 4061 | invalid_record | Email cant be blank. |
| 4062 | invalid_record | Email is invalid. |
| 4063 | invalid_record | Email has already been taken. |
| 4064 | invalid_record | Password cant be blank. |
| 4065 | invalid_record | Password is too short (minimum is 8 characters). |
| 4066 | invalid_record | Password confirmation doesnt match Password. |
| 4067 | invalid_record | Last name cant be blank. |
| 4068 | invalid_record | Wrong value for a boolean field. |
| 4069 | invalid_params | Missing required parameters. |
| 4070 | invalid_record | Member preference name cant be blank. |
| 4071 | invalid_record | Domain cant be blank. |
| 4072 | invalid_record | Member preference not found. |
| 4073 | invalid_record | Domain not found. |
| 4074 | data_unavailable | Data not available this time. |
| 4075 | invalid | Domain creation not allowed. |
| 4076 | invalid | Only one domain is allowed. |
| 4077 | invalid_record | Read-only attribute cannot be changed. |
| 4078 | invalid_record | Current password is invalid. |
| 4079 | internal_server_error | Server not responding. |
| 4080 | invalid | Domain already in list. |
| 4081 | invalid | Admin domain cannot be deleted. |
| 4082 | invalid | Avatar content type is invalid. |
| 4083 | invalid | User has not uploaded avatar before. |
| 4084 | not_found | Location not found. |
| 4085 | invalid | Invalid response to Challenge. |
| 4086 | invalid | Invalid wall post. |
| 4087 | invalid | Message cant be blank. |
| 4088 | unauthorized | Unauthorized client credentials. |
| 4089 | invalid_format | Period type should be Day or Month. |
| 4090 | invalid_format | Period date is invalid. |
| 4091 | not_found | Beacon or Beacon Location not found. |
| 4092 | already_joined_group | You already joined this group. |
| 4093 | not_joined_group | You have not yet joined this group. |
| 4094 | not_allowed | Profile view on other member disabled. |
| 4095 | invalid | Invalid class passed as argument. |
| 4096 | already_connected | Already connected with this member. |
| 4097 | not_connected | Not currently connected with this member. |
| 4098 | pending_request | Member has pending connect request. |
| 4100 | not_allowed | Redemption failed. |
| 4101 | not_allowed | Failed to claim the award. |
| 4102 | invalid | Invalid class passed as argument. |
| 4200 | not_allowed | Member is not allowed to post to this News Feed. |
| 4201 | not_allowed | Member is not allowed to post a comment to this News Feed. |
| 4400 | invalid_record | Invalid record. |
| 4401 | not_allowed | Frequency limit reached. |
| 4402 | not_allowed | User submissions limit reached. |
| 4403 | not_allowed | Total maximum submissions limit reached. |
| 4404 | not_allowed | Required minimum metric not met. |
| 4405 | not_allowed | Required minimum tier not met. |
| 4406 | not_allowed | Responding is not allowed. |
| 4500 | not_available | Referral code is invalid. |
| 4501 | failed_trigger | Leaderboard update failed. |
| 4502 | already_referred | You already submitted a referral code. |
| 4503 | no_associated_identity | You have not connected any identity. |
| 4504 | self_referral | You are not allowed to use your own referral code. |
| 4505 | expired_referral_code | Referral code already expired. |
| 4506 | not_supported | Not yet supported. |
| 4507 | invalid | Social account already owned by another member. |
| 4508 | not_supported | Integration key not supported. |
| 4509 | invalid | Response params are invalid. |
| 4510 | invalid | Response entry not created. |
| 4511 | not_supported | Not configured as public_key. |
| 4512 | not_found | Visitor to merge does not exist. |
| 4513 | not_allowed | Visitor to merge is already a member. |
| 4514 | not_allowed | Not allowed to submit activity. |
| 4551 | failed | Query string is not yet defined. |
| 4700 | not_allowed | Operation is not allowed for User Scoreboards. |
| 4701 | not_allowed | Operation is not allowed for Group Scoreboards. |
| 4702 | not_allowed | Group Members endpoint is disabled. |
| 4703 | not_allowed | Member lookup is disabled. |
| 4750 | not_allowed | Failed to execute analytics query. |
| 4800 | invalid_params | Invalid member preference attribute. |
| 4850 | not_allowed | Contest entry cannot be updated. |
| 4898 | failed | Push notification is not configured. |
| 4899 | failed | Device already registered. |
| 4900 | failed | Device registration error. |
| 4901 | missing_file | Missing Receipt JSON/HTML/Image file. |
| 4902 | invalid | Uploaded file does not contain a valid JSON. |
| 4903 | invalid | JSON data is incomplete. |
| 4904 | invalid | Vendor is not recognized. |
| 4905 | invalid | Points source cannot be found. |
| 4906 | invalid | Invalid or missing input. JSON/HTML/Image file upload or JSON string expected. |
| 4907 | invalid | Receipt cannot be created. |
| 4908 | invalid | Found duplicate OR number / Receipt ID. |
| 4909 | invalid | Missing Transaction ID. |
| 4910 | invalid | Transaction ID does not exist. |
| 4911 | invalid | Receipt/Transaction is already claimed. |
| 4912 | invalid | Member cannot claim transactions prior to join date. |
| 4913 | invalid | Amount is required to find the transaction. |
| 4914 | invalid | Vendor is required. |
| 4915 | invalid | Submitted Transaction Amount should be greater than zero. |
| 4916 | invalid | Transaction being claimed is older than 90 days. |
| 4920 | invalid | Inactive card. |
| 4921 | not_allowed | Not allowed. |
| 4922 | failed | Transaction failed. |
| 4923 | invalid | PIN is required. |
| 4924 | invalid | Invalid PIN. |
| 4925 | timeout | Payment gateway server timeout. |
| 4926 | not_available | Resource not found. |
| 4927 | retry | Unexpected error occurred. Please retry. |
| 4928 | invalid | Invalid class. |
| 4929 | invalid | Invalid payment method. |
| 4930 | invalid | Invalid parameter given on update. |
| 4932 | not_allowed | Card currently linked to another user. |
| 4933 | not_allowed | Already linked to current user. |
| 4934 | invalid | Invalid amount. |
| 4935 | not_allowed | Not enough balance. |
| 4936 | failed | Update failed - invalid payment nonce. |
| 4937 | invalid | Amount is required. |
| 4938 | invalid | Payment method nonce is required. |
| 4939 | failed | Unlink failed. |
| 4940 | failed | Braintree internal server error. |
| 4941 | invalid | Code Entry is already claimed. |
| 4942 | invalid | Code Entry is already expired. |
| 4943 | invalid | Unknown Code or Game ID. |
| 4944 | invalid | Invalid Checksum. |
| 4945 | invalid | No matching entry. |
| 4946 | invalid | Invalid ticket length. |
| 5000 | not_allowed | Offer is not a certificate. |
| 5001 | not_allowed | Responding to this offer is not allowed. |
| 5002 | invalid | Offer response error encountered. |
| 5003 | invalid | Multiple offer certificate found. |
| 5004 | invalid | Offer certificate no longer effective. |
| 5050 | invalid | Export cannot be created. |
| 5051 | not_allowed | Export cannot be run asynchronously. |
| 5052 | not_available | Export is not asynchronous. It cannot have a Background Job Status. |
| 5053 | invalid | Tokens should be a proper JSON. |
| 5060 | invalid | Import cannot be created. |
| 5061 | invalid | ImportDefinition is not found for your resource. |
| 5062 | invalid | Invalid filename for import. |
| 5070 | not_available | Requested and Default Leaderboards do not exist. |
| 5080 | not_available | News Feed does not exist. |
| 5081 | not_available | Default News Feed cannot be found. |
| 7000 | invalid | Metric is invalid. |
| 7001 | invalid | Reward is not a contest. |
| 7002 | invalid | Attribute is invalid. |
| 7003 | not_allowed | Can not set attributes other than redemption_status and activity_processed. |
| 7004 | not_allowed | Reward type is not a product. |
| 8800 | failed | Error encountered. Please try again later. |
| 8801 | not_allowed | Payment processing failed. |
| 9000 | invalid | Invalid PunchCard type. |
| 9050 | invalid | Unknown Action given. |
Upgrade Check
To check if client is required to update via command line, invoke the following
cURLcommand:
curl -X GET
-H 'Accept: application/vnd.stellar-v1+json'
-H 'User-Agent: Sol/1.1.0/ iOS/9.1/iPhone6'
<base_url>/api/upgrade_check
If successful, the response should look like this:
{
"success": true,
"data": {
"upgrade_action": "none",
"ios_download_link": "null",
"android_download_link": "null"
}
}
Value of upgrade_action is either
required_upgradeornone
This endpoint does not need any parameter, it will just compare User-Agent header information against Unsupported Agents settings. To modify 'Unsupported Agents' settings, Go to Marketing Console > Program tab, and click on 'Settings' next to 'Edit' button. This will open a modal dialog box. In 'Unsupported Agents' field, enter known User-Agent string that you want to receive the required_upgrade response.