How to use Workstars TV data in your own system

You have two choices:

1. Embed in a page

To embed the Workstars TV in a web page, use an <iframe> that contains a Workstars TV URL (See Workstars TV for how to generate a URL)

2. JSON Data

If you want to build a custom integration with your own system (intranet, Sharepoint, HR portal etc.), you can request the raw data (in JSON format). You can then write some code (client side e.g. Javascript or server side e.g. .NET, PHP, etc.) to display the data as required.

How to request a JSON response

To request a JSON response instead of the HTML page, you simply need to add a couple of parameters (“response=json” & “version=3”) onto the end of a Workstars TV URL (See Workstars TV for how to generate a URL).

You do this by adding a “?” on the end of the URL and a “&” between the 2 values, below is an example URL:

https://subdomain.workstars.com/tv/47io11c5l9m6ykjzpeh959jlb31npy3s?response=json&version=3

which would generate the following response:

HTTP/1.1 200 OK
{
    "wall": [
        {
            "type": "adhoc_award",
            "initiator": {
                "first_name": "Anne",
                "last_name": "Lewis",
                "image": "https://d32rcf07aj0hbp.cloudfront.net/pDwQ5K49dIo8GfhOEsgnxt6jNvAm23yiWR7Pa.jpeg"
            },
            "recipients": [
                {
                    "first_name": "Richard",
                    "last_name": "Jones",
                    "image": "https://d32rcf07aj0hbp.cloudfront.net/3yiWR7PaK49dIpDwQfhOEsgnxt6jNvAm52o8G.jpeg"
                }
            ],
            "title": "Sales Person of the Month",
            "reason": "Well done on your sales figures last week, it made all the difference to the company!",
            "created_at": "2014-10-20T11:55:29Z"
        },
        {
            "type": "recognition",
            "initiator": {
                "first_name": "Anne",
                "last_name": "Lewis",
                "image": "https://d32rcf07aj0hbp.cloudfront.net/pDwQ5K49dIo8GfhOEsgnxt6jNvAm23yiWR7Pa.jpeg"
            },
            "recipients": [
                {
                    "first_name": "Alex",
                    "last_name": "Murphy",
                    "image": "https://d32rcf07aj0hbp.cloudfront.net/pDwQ5K49dIo8GfhOEsgnxt6jNvAm23yiWR7Pa.jpeg"
                },
                {
                    "first_name": "Chris",
                    "last_name": "Jones",
                    "image": "https://d32rcf07aj0hbp.cloudfront.net/pDwQ5K49dIo8GfhOEsgnxt6jNvAm23yiWR7Pb.jpeg"
                }
            ],
            "title": "We Play to Win",
            "reason": "Well done everyone for managing the network last night",
            "created_at": "2014-09-30T15:25:22Z"
        },
        {
            "type": "service_award_onboarding",
            "initiator": {
                "first_name": "Anne",
                "last_name": "Lewis",
                "image": "https://d32rcf07aj0hbp.cloudfront.net/pDwQ5K49dIo8GfhOEsgnxt6jNvAm23yiWR7Pa.jpeg"
            },
            "recipients": [
                {
                    "first_name": "Burt",
                    "last_name": "Halsey",
                    "image": "https://d32rcf07aj0hbp.cloudfront.net/gnxt6jpDwQ523yiWRdIo8GfhOEsNvAm7PaK49.jpeg"
                }
            ],
            "title": "1 Week",
            "reason": "Can you believe it has been 1 weeks since you started?",
            "created_at": "2014-09-30T15:25:22Z"
        },
        {
            "type": "service_award_long",
            "initiator": {
                "first_name": "Anne",
                "last_name": "Lewis",
                "image": "https://d32rcf07aj0hbp.cloudfront.net/pDwQ5K49dIo8GfhOEsgnxt6jNvAm23yiWR7Pa.jpeg"
            },
            "recipients": [
                {
                    "first_name": "Burt",
                    "last_name": "Halsey",
                    "image": "https://d32rcf07aj0hbp.cloudfront.net/gnxt6jpDwQ523yiWRdIo8GfhOEsNvAm7PaK49.jpeg"
                }
            ],
            "title": "2 Years",
            "reason": "Can you believe it has been 1 weeks since you started?",
            "created_at": "2014-09-30T15:25:22Z"
        },
        {
            "type": "company_award_nomination",
            "initiator": {
                "first_name": "Anne",
                "last_name": "Lewis",
                "image": "https://d32rcf07aj0hbp.cloudfront.net/pDwQ5K49dIo8GfhOEsgnxt6jNvAm23yiWR7Pa.jpeg"
            },
            "recipients": [
                {
                    "first_name": "Burt",
                    "last_name": "Halsey",
                    "image": "https://d32rcf07aj0hbp.cloudfront.net/gnxt6jpDwQ523yiWRdIo8GfhOEsNvAm7PaK49.jpeg"
                }
            ],
            "title": "Employee of the Year",
            "reason": "Bert's customer service ratings have been outstanding, 5/5 stars on every ticket he's completed",
            "created_at": "2014-09-30T15:25:22Z"
        },
        {
            "type": "company_award_winners",
            "initiator": {
                "first_name": "Anne",
                "last_name": "Lewis",
                "image": "https://d32rcf07aj0hbp.cloudfront.net/pDwQ5K49dIo8GfhOEsgnxt6jNvAm23yiWR7Pa.jpeg"
            },
            "recipients": [
                {
                    "first_name": "Burt",
                    "last_name": "Halsey",
                    "image": "https://d32rcf07aj0hbp.cloudfront.net/pDwQ5K49dIo8GfhOEsgnxt6jNvAm23yiWR7Pa.jpeg"
                },
                {
                    "first_name": "Chris",
                    "last_name": "Jones",
                    "image": "https://d32rcf07aj0hbp.cloudfront.net/pDwQ5K49dIo8GfhOEsgnxt6jNvAm23yiWR7Pb.jpeg"
                },
                {
                    "first_name": "Anne",
                    "last_name": "Lewis",
                    "image": "https://d32rcf07aj0hbp.cloudfront.net/pDwQ5K49dIo8GfhOEsgnxt6jNvAm23yiWR7Pc.jpeg"
                }
            ],
            "title": "Employee of the Year",
            "reason": "Well done everyone on their performance this year, it has been exceptional!",
            "created_at": "2014-10-11T15:25:22Z"
        }
    ]
}

The following types are returned:

Type Number Recipients Description
adhoc_award 1 When an administrator makes an adhoc financial reward
recognition 1 or many When a recocognition is given
service_award_onboarding 1 or many When an onboarding service award is processed
service_award_long 1 or many When a long service award is processed
company_award_nomination 1 When an employee nominates someone for a company award
company_award_winners 1 or many When the company award winners have been announced


FAQs

Why cant I see new posts immediately?

This is because we cache the response for 5 minutes to help with performance.

Why am I being blocked?

If you access a URL with the wrong token (the random part after /tv/) too many times, you will be blocked for 10 minutes. This is for security reasons and is usually because you are using an old URL or you have copied it incorrectly.

Why am I being throttled?

If you access URL more than 60 times in a minute you will be temporarily blocked.

  • This is once every second, which is enough to have it embedded in a web page (intranet, sharepoint, etc.). If you have a lot of traffic to your site you might hit this limit, in this case you should use the raw JSON data instead, you can write some code to display it while caching the response for 5 minutes.
  • If you are using the URL in a script, we suggest you only access it once every 5 minutes as the responses are cached anyway.
Was this article helpful?
1 out of 1 found this helpful
Have more questions?
Submit a request