Fetching Export Results

To fetch export results, a client_id that has a role that contains the automated-exports-view permission can be used to create a client_access_token that will be used in the following endpoints

Getting a `client_access_token`

A client_access_token can be retrieved by sending a request to the endpoint POST <GATEWAY-URL>/api/1/oauth2/access_token using the client_id and client_secret mentioned above. Sample payload would be

{
    "grant_type": "client_credentials",
    "client_id": "<CLIENT-ID>",
    "client_secret": "<CLIENT-SECRET>"
}

The response would contain the access_token

{
    "token_type": "Bearer",
    "expires_in": 15897600,
    "access_token": "<CLIENT-ACCESS-TOKEN>"
}

The access_token above is the equivalent of the client_access_token that can be used in the header for the endpoints below

Content-Type: application/json
Authorization: Bearer <CLIENT-ACCESS-TOKEN>
User-Agent: PostmanRuntime/7.39.0
Accept: */*
Host: <GATEWAY-HOST>
Accept-Encoding: gzip, deflate, br
Connection: keep-alive

Getting a list of all active automated-exports

Create a request to the endpoint GET <GATEWAY-URL>/api/1/data-exporter/automated using the client_access_token in the header would have a sample response:

[
    {
        "id": "XXXXXXXXXXXXXXXXXXXXXXXXX",
        "system_name": "win-info",
        "last_run": {
            "id": "XXXXXXXXXXXXXXXXXXXXXXXXX",
            "expires_at": "2123-06-20T09:35:21+00:00",
            "created_at": "2024-06-20T09:35:57+00:00"
        }
    }
]

The system_name represents the export name
The last_run would identify the most recent result for this export name
The last_run.id would be the result_id of the most recent export result. This can be used in downloading the data for the result of the export.
The last_run.expires_at value would determine when the export result would expire
The last_run.created_at value would determine when the result was created

Getting the list of results for an export name

Create a request to the endpoint GET <GATEWAY-URL>/api/1/data-exporter/automated/<EXPORT-NAME>/results?page=1&perPage=10 using the client_access_token in the header would result in the following response

{
    "results": [
        {
            "id": "XXXXXXXXXXXXXXXXXXXXXXXXX",
            "expires_at": "2123-06-20T09:35:21+00:00",
            "created_at": "2024-06-20T09:35:57+00:00"
        }
    ],
    "total": 1
}

The page query parameter would be used to identify which page number to return for the results
The perPage query parameter would be used to set how many items per page would be returned
The id of the list of results would be the result_id that can be used when downloading the data for the result of the export

Downloading data for an export result

Create a request to the endpoint GET <GATEWAY-URL>/api/1/data-exporter/automated/fetch/<RESULT-ID> using the client_access_token in the header would result in the following response

{
    "result": {
        "id": "jlitk6w3fzow15k9bvrpu4p62",
        "download_url": "https://assets-XXXXXXX.ams3.digitaloceanspaces.com/automated-exports/win-info/XXXXXXXXXXXXXXXXXXXXXXXXX.json?XXXXXXXXXX
    }
}

Use the entire result.download_url to download the data of the export. This URL doesn’t require the client_access_token anymore. A sample response would be as follows

{
    "win_info": [
        {
            "userid": "XXXXXXXXXXXXXXXXXXXXXXXXX",
            "stackid": "XXXXXXXXXXXXXXXXXXXXXXXXX",
            "haswon": "0",
            "participation_date": "20XX-XX-XX XX:XX:XX.XXX"
        }
    ]
}

Export Types

Campaign Info

Basic campaign details

{
    "campaign_info": [
        {
            "campaign_name": "<CAMPAIGN-NAME>",
            "campaign_code": "XXXXXXXXXXXXXXXXXXXXXXXXX",
            "campaign_start": "202X-XX-XXT00:00:00+00:00",
            "campaign_end": "202X-XX-XXT00:00:00+00:00"
        }
    ]
}

User Base Connections

Basic user base information coming from third-party registration

{
    "user_base_connections": [
        {
            "userid": "XXXXXXXXXXXXXXXXXXXXXXXXX",
            "client_id": "<EXTERNAL-ID>"
        }
    ]
}

a. external_id would be the user’s identifier on the third-party service/application

Player Info User Participation

Basic player participation information

{
    "player_info_user_id": [
        {
            "userid": "XXXXXXXXXXXXXXXXXXXXXXXXX",
            "stackinstanceid": "XXXXXXXXXXXXXXXXXXXXXXXXX",
            "value": "10000",
            "participation_date": "202X-XX-XX 00:00:00"
        }
    ]
}

Player Info Game Type

Game information on the stackInstance from above results

{
    "player_info_game_type": [
        {
            "stackinstanceid": "XXXXXXXXXXXXXXXXXXXXXXXXX",
            "stackid": "XXXXXXXXXXXXXXXXXXXXXXXXX",
            "game_type": "gamification"
        }
    ]
}

Win Information

Basic win information for a user and campaign

{
    "win_info": [
        {
            "userid": "XXXXXXXXXXXXXXXXXXXXXXXXX",
            "stackid": "XXXXXXXXXXXXXXXXXXXXXXXXX",
            "haswon": "0",
            "participation_date": "202X-XX-XX 00:00:00.000"
        }
    ]
}

All Coupons

Basic information on coupons created for users

{
    "all_coupons": [
        {
            "userid": "XXXXXXXXXXXXXXXXXXXXXXXXX",
            "coupon_name": " exact-code-no-exp",
            "received_date": "202X-XX-XX 00:00:00"
        }
    ]
}

Challenges User Information

User progress information for a campaign

{
    "challenges_user_id": [
        {
            "userid": "XXXXXXXXXXXXXXXXXXXXXXXXX",
            "stackinstanceid": "XXXXXXXXXXXXXXXXXXXXXXXXX",
            "hascompleted": "0",
            "participation_date": "202X-XX-XX 00:00:00"
        }
    ]
}

Challenges Game Information

Game information for a user progress

{
    "challenges_game_type": [
        {
            "stackinstanceid": "XXXXXXXXXXXXXXXXXXXXXXXXX",
            "stackid": "XXXXXXXXXXXXXXXXXXXXXXXXX",
            "game_type": "lottery"
        }
    ]
}

Gamification Prize User Information

{
    "gamification_prize_user_id": [
        {
            "userid": "XXXXXXXXXXXXXXXXXXXXXXXXX",
            "game_id": "XXXXXXXXXXXXXXXXXXXXXXXXX",
            "game_name": "Scratch-and-Win",
            "prizeid": "XXXXXXXXXXXXXXXXXXXXXXXXX",
            "claimed_date": null
        }
    ]
}

Gamification Prize Information

{
    "gamification_prize_prize_type": [
        {
            "prizeid": "XXXXXXXXXXXXXXXXXXXXXXXXX",
            "game_id": "XXXXXXXXXXXXXXXXXXXXXXXXX",
            "prize_name": "sorry",
            "prize_type": "no-prize"
        }
    ]
}