# Test the Datasets API or Custom Widgets with Postman Postman enables you to test the Datasets API or Custom Widgets without writing your own code, or for reference if your own code shows errors. March 25, 2026 Geckoboard's Datasets API and Custom Widgets are powerful and flexible ways to compile data from in-house systems, third-party tools, and databases on your dashboard. Postman is a REST client that allows developers to test, develop, and document APIs. Use the pre-built Postman collection below to quickly test our Datasets API and Custom Widget, no coding required. # **Before you start** ## **Install Postman** [Download a free version of Postman](https://www.getpostman.com/postman). The free plan is sufficient for importing and testing this collection. ## **Import the collection to your Postman workspace** After installing Postman, you can [download the collection below](https://www.postman.com/collections/2aeb64c30e26f6519ef1) and import it into your own environment. ## **Find your Geckoboard API key** You will need your API key to hand for each of these methods so it is best to have this ready now. You can find your Geckoboard API key [using these steps](https://support.geckoboard.com/en/articles/6055693-find-your-geckoboard-api-key). ## **Modify the collection (optional)** If you're only testing our methods, don't change the dataset id or the content contained in the Body. If you would like to use your own schema, our [developer documentation](https://developer.geckoboard.com/) provides a complete reference to the schema, field definitions, and API requests, along with examples. Please refer to the documentation to plan your dataset schema and modify the requests in our Postman collection as per your needs. If you get stuck at any point or run into issues, please get in touch, and we'll be happy to help! ## **Learn about the Datasets API methods** The methods we are going to cover are each of the methods detailed within our Developer Documentation, these are the GET, PUT, POST and DELETE methods. - **GET** - This method is used to test the connection between your endpoint and the Geckoboard API, using your API key identifies your individual account as the endpoint. - **PUT** - This method can be used to create a Dataset or replace the contents of an existing Dataset. It is at this point you will need to know the structure of your Dataset (if you are planning on creating your own schema). You can see more about planning your schema and supported data types in our [developer documentation](https://developer.geckoboard.com/). - **NOTE:** This is a destructive method and when used with an existing Dataset, will completely overwrite the existing data replacing it with the specified payload. You should only do this if you are absolutely certain that you will not need the overwritten data as this cannot be undone. - **POST** - This method can be used to add data to a Dataset, This method is non-destructive and POSTS data to your specified Dataset by adding it to the end of the existing data entries. - **DELETE** - This method is used when you would like to completely delete the Dataset and all of its data. # **Use Postman to test the Datasets API methods** ## **Test the Datasets authentication using the GET method** 1. Select the _GET: Datasets authentication_ method. 2. Make sure the _URL_ is set to [https://api.geckoboard.com/](https://api.geckoboard.com/) 3. Under the _Authorisation_ tab, select the _Type_ as _Basic Auth_. 4. Fill in your Geckoboard API key in the _Username_ field. 5. Leave the _Password_ field empty. 6. Make the request by clicking on _Send_. **Tip:** A _{}_ response indicates a 200 OK Status has been received. In other words, the _{}_ response confirms the authentication was successful. ## **Create a dataset using the PUT method** 1. Select the _PUT: Create dataset_ method. 2. Update the dataset name, if needed, in the _URL_ like so: [https://api.geckoboard.com/datasets/](https://api.geckoboard.com/datasets/) . We've set the dataset name to _postman_example_ in our example. 3. Under the Authorisation tab, select the Type as Basic Auth. 4. Fill in your Geckoboard API key in the _Username_ field. 5. Leave the Password field empty. 6. In the _Headers_ tab, add _Content-Type_ in the _KEY_ field and _application/json_ in the _VALUE_ field. 7. Under the _Body_ tab, select _raw_ and add your dataset schema here. Our collection includes a sample schema that you can use directly without modifications. 8. Make the request by clicking on _Send_. **Tip:** Use the _Save Response_ option to download the dataset schema response. You can use this as a reference, if needed, for pushing data to the dataset later on. ## **Add or append data to your Dataset using the POST method** 1. Select the _POST: Add or append data_ method. 2. Make sure you have the correct dataset name in the _URL_ in the following format: _[https://api.geckoboard.com/datasets/postman_example/data](https://api.geckoboard.com/datasets/postman_example/data). As before, we've set the dataset name to _postman_example_ in our example. 3. Under the Authorisation tab, select the Type as Basic Auth. 4. Fill in your Geckoboard API key in the _Username_ field. 5. Leave the Password field empty. 6. In the Headers tab, add Content-Type in the KEY field and application/json in the VALUE field. 7. Under the Body tab, select raw and add your dataset payload here. Our collection includes a sample payload that you can use directly without modifications. 8. Make the request by clicking on Send. **Tip:** A {} response indicates a 200 OK Status has been received. In other words, the {} response confirms the data has been posted successfully. ## **Replace all of the data in your Dataset using the PUT method** 1. Select the _PUT: Replace data_ method. 2. Make sure you have the correct dataset name in the _URL_ in the following format: _[https://api.geckoboard.com/datasets/postman_example/data](https://api.geckoboard.com/datasets/postman_example/data). As before, we've set the dataset name to _postman_example_ in our example. 3. Under the Authorisation tab, select the Type as Basic Auth. 4. Fill in your Geckoboard API key in the _Username_ field. 5. Leave the Password field empty. 6. In the Headers tab, add Content-Type in the KEY field and application/json in the VALUE field. 7. Under the Body tab, select raw and add your dataset payload here. Our collection includes a sample payload that you can use directly without modifications. 8. Make the request by clicking on Send. **Tip:** A {} response indicates a 200 OK Status has been received. In other words, the {} response confirms the data has been pushed successfully. ## **Delete all of the data and the Dataset using the DELETE method** 1. Select the _DEL Delete a dataset_ method. 2. Make sure you have the correct dataset name in the _URL_ in the following format: _[https://api.geckoboard.com/datasets/](https://api.geckoboard.com/datasets/) . As before, we've set the dataset name to _postman_example_. 3. Under the Authorisation tab, select the Type as Basic Auth. 4. Fill in your Geckoboard API key in the _Username_ field. 5. Leave the Password field empty. 6. Make the request by clicking on Send. **Tip:** A {} response indicates a 200 OK Status has been received. In other words, the {} response confirms the dataset has been deleted successfully. ## **Use Postman to test Custom Widgets** 1. Create a new request or use one of the examples. 2. Select _POST_. 3. Update the URL to reflect the following and be sure the widget key is added: [https://push.geckoboard.com/v1/send/widget-key-here](https://push.geckoboard.com/v1/send/widget-key-here) 4. Select the _Headers_ tab. 5. In the _Key_ field and add _Content-Type_. 6. In the _Value_ field add application/json or application/xml. 7. On the _Body_ tab, select _Raw_. 8. Add your data formatted as JSON or XML as per our [documentation](https://developer-custom.geckoboard.com/#introduction). 9. Click _Send_ to POST payload to Geckoboard. **Tip:** You can see more information about supported types and schemas for our Custom Widgets in our developer documentation [here](https://developer-custom.geckoboard.com/#introduction).