Using Postman To Test Notion API Requests
How to download Postman, copy the Notion API collection and start testing API requests
What Is Postman?
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.
Setting Up Postman
Create a free Postman account here
Optionally, download the Postman desktop app here
Fork the Notion API collection, to copy it into your Postman workspace, from here
Add your Internal Integration Secret, from your integrations, to the Token field in the Authorization tab, then use
cmd + sor click the Save button to save your settings
Making An API Request
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.
To do this in Postman, go to
Collections > Notion API > Databases > Retrieve A DatabaseReplace the
{{DATABASE_ID}}placeholder with the ID of your expenses databaseClick Send or use
cmd + returnto test your API request
You should see a response like this -
Common Errors
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.
General Troubleshooting
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.
