Using Postman To Test Notion API Requests

Postman does lots of things but for our purposes, it’s a HTTP client. This just means that we can use it to send API requests and analyse responses.

Postman is probably the most popular HTTP client, as a result, lots of companies that have APIs create Postman collections. These are templates for every type of API request that their API supports. So rather than having to copy the details of your request from documentation into Postman, if you download the collection, the request will be ready for you to select.

All you have to do is copy the collection, configure your environment - which often just means adding the service’s API key to the collection - and then you’ll be ready to start making requests.

Bear in mind that the changes that you make to the content in your Notion workspace via the API can’t be undone as easily so think before you send that request. Fetching data will always be safe but creating, updating and deleting data requires a little more care.

1. Create a free Postman account here

2. Optionally, download the Postman desktop app here

3. Fork the Notion API collection, to copy it into your Postman workspace, from here

4. Add your Internal Integration Secret, from your integrations, to the Token field in the Authorization tab, then use cmd + s or click the Save button to save your settings

   

We’re going to test the Retrieve A Database request. This is a good type of request to start with because if you make any mistakes, the content in your Notion workspace won’t be affected.

1. To do this in Postman, go to Collections > Notion API > Databases > Retrieve A Database

2. Replace the {{DATABASE_ID}} placeholder with the ID of your expenses database

3. Click Send or use cmd + return to test your API request

You should see a response like this -

The most common error for this type of request is the 404 object_not_found error.

This either means that you’ve used the wrong database ID or you’ve not shared your database with your integration.

Checking Your Database ID

Make sure that you’re viewing the source database, not a linked database view displaying the database.

Copy the ID of the database from the page URL -

Checking That Your Integration Is Connected To The Database

Make sure that you’re viewing the source database, not a linked database view that’s displaying the database.

From the top right hand corner of the page click on the ••• > Connections > [name of your integration].

If you’ve tested API requests with Postman before, make sure that the right API key is being sent in the request by checking the token in the collection’s Authorization tab and that the Auth Type in the request’s Authorization tab is set to ‘Inherit auth from parent’, as shown in the below screenshot.

It’s often helpful to use the code inspector to check all of the content that’s being sent in your request.

If you hover your mouse over the ****** in the Authorization header, you can check that the right API key is being used for the request.