NAV
cURL

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
Multi-lingual Program Setting

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 cURL command:

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 following cURL command:

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>&nbsp;テキ&nbsp;</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 cURL command:

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
email 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 cURL command:

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
email 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

Resend Email Confirmation

To request email confirmation via command line, invoke the following cURL command:

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
email 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 cURL command:

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 cURL command:

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 cURL command:

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
email 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 cURL command:

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 cURL command:

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
email 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 cURL command:

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
email 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 cURL command:

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/apps
and 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 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 cURL command:

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/apps
and 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

  1. mfa_required - An OTP has been sent to the member and it needs to be validated with the mfa_otp grant.

  2. 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 cURL command:

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/apps
and 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 cURL command:

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 cURL command:

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/apps
and 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 cURL command:

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/apps
and 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:

  1. As Authorization Bearer
  2. 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 cURL command:

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

  1. 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.
  2. 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.
  3. Select from Lookup Attribute options which member field matches integration key from step 2. Usually this is integration_id. Other options are listed below.

    JWT Settings

Lookup Attribute options

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/apps
and 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 cURL command:

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

  1. Go to <base_url>/console/apps, and create your Oauth Application. In this example, 'growingtree.demostellar.com' is your base url.

    Create App

  2. Define callback URL to Oauth2 consumer. Here, it points to https://myapphost.com/users/auth/marigold/callback

    App Callback URL
    Leave the rest of the fields as is.

  3. Copy client_id & client_secret from Oauth Application detail page. This will serve as your MARIGOLD_APP_ID and MARIGOLD_APP_SECRET credential keys to be installed in your Oauth (Consumer) Resource server. Click on 'Show secret' button to reveal the secret key.

    Show Secrets
    Show Secrets

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

  1. Enter the code verifier into the first box
  2. 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).
  3. Click Generate Code Challenge
  4. Copy out the Code Challenge and post it into the Params tab of the Get Authorization Call

    Code Verifier Generator

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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_name via command line, invoke the following cURL command:

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_statements via command line, invoke the following cURL command:

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 following cURL command:

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 following cURL command:

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 cURL command:

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 following cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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

  1. 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

  2. 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 cURL command:

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 cURL command:

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_at via command line, invoke the following cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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"
      }
    ]
  }
}

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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:

UI Hints

For the ui_hint attribute, the values you can receive are:

Preferences Metadata

To get member preferences metadata 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/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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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
email 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 cURL command:

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 cURL command:

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 cURL command:

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&trade;",
                        "description": "The Works&trade;-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 cURL command:

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&trade;",
                "description": "The Works&trade;-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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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:
delivered
opened

Mark a Notification as Read

To mark a message as read via command line, invoke the following cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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.

  1. Responding to offer id specified in the request path with valid access_token.
  2. Responding with a code parameter 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 cURL command:

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 cURL command:

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 cURL command:

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
email 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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL commands:

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 cURL command:

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 cURL command:

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

  1. Create a Campaign and add/include Offers in the "Offers" tab
  2. Set up the Audience of the Campaign.
  3. Set the Campaign's target to a predefined ML Model in the "Targeting" tab
  4. 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.

  5. Publish the Campaign

  6. Activate the Campaign as the source of Allocated Offers by providing its internal name in the Active ML Campaign Program Setting.

  7. 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 cURL command:

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 false
This 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 cURL command:

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 false
This 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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 false
This 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 false
This 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_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
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 cURL command:

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_attributes is 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 false
This 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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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 cURL command:

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.

HT