Sending API Requests through Postman

# Sending API Requests through Postman ## Overview [Postman](https://www.postman.com/) is a very popular tool for building, testing, using, and sharing APIs. With a few simple steps, Postman can easily be used to send all of your HTTP requests to SignalWire with ease! Follow the steps below to set up Postman in a way that is perfect for utilizing their services with SignalWire. ## Setting up Postman Environments Navigate to your SignalWire Space within the project you want and copy the **Project ID**, **SignalWire Space**, and **Auth Token**. These will be needed for every request. Check out our guide about [navigating your Space](/guides/navigating-your-space#api) if you do not know where to find your authentication variables. From within Postman, select **Environments** on the left-hand sidebar. Environments allow you to create some set variables that can be used throughout all your requests without having to put the values directly in the request. This saves a LOT of time!

:::tip What can go inside of environments? This example will show how to use the environment to handle authentication variables (API Token, Space URL, and Project ID), but you could also use this to create a variable for your From numbers, To numbers, caller IDs, video room session IDs, and much much more! ::: Click on the drop-down menu that says **No Environment** and choose the one you just created.

:::info Projects vs Environments Each environment will contain one project ID, so it will only work for that one project! If you have multiple projects, create an environment for each so you can easily switch between them as needed without having to modify your requests. ::: ## Setting up a Postman Collection Next, we will create a collection to store your requests which will allow you to authenticate once at the **collection** level instead of at the **request** level every time. Please note that if you prefer, you can use our [curated Postman collections](https://github.com/signalwire/rest-apis) instead: they already include all our APIs. To create one yourself, click the **New** button to open a **Create New** submenu and select **Collection**.

Go to the **Authorization** tab and choose **Basic Auth** from the dropdown menu. For Basic Auth, you will enter your **Project ID** as the username and your **Auth Token** as the password. :::info Using Variable Names in Collection and Environments In the Environment example above, Proj was used for Project ID, Auth was used for API Token, and Space was used for Space URL. You dont have to use this same naming HOWEVER you MUST have the same variable names in your environments as you do in the collection, or it will **not** authenticate the requests. Make sure your naming is consistent! ::: Use your environment variable names in between two sets of curly braces as shown below to access the values stored within them securely. If the variables turn red instead of orange, check to make sure you have selected an environment at the top.

Hover over the collection on the left sidebar, and three dots appear. Click the three dots then click **Add Request.**

Now you can set up the request in accordance with the documentation in just a few seconds! Keep reading to the next section to see some real examples with our APIs. ## Postman SignalWire API examples We have shown several examples of different types of requests that Postman can simplify for you, but any of our API requests can be run on Postman! If you need additional parameters for a GET request, you can use the key-value pairs in the **query params**. If you need additional parameters for a POST request, you will use the **Body** tab with **x-www-form-urlencoded** key-value pairs or **raw** data with the type **JSON**. :::info Environment Variable Names This section will use the variable names shown above - **Proj**, **Auth**, and **Space**. If you did not use these, make sure to use your own version when you try the following examples! ::: ### List Video Room Sessions Take a look at the documentation for [listing all room sessions from the Video API](/rest/signalwire-rest/endpoints/video/list-room-sessions).

At the top, you can see that this request will use the GET method and has the URL https://.signalwire.com/api/video/room_sessions. Copy this URL and paste it directly into the request URL on Postman. Replace **<demo>.signalwire.com** with {{Space}} to invoke your environment variable, and press send!

### Search for and Buy a Phone Number Postman makes searching for and purchasing numbers super simple! Copy the URL in the [Number Search API](/rest/signalwire-rest/endpoints/space/search-available-phone-numbers) along with any helpful parameters that you would like to use to help narrow down your search. In this example, we will use starts_with as the key and 817 as the value to only return numbers beginning with 817.

Copy the E164 number that you want to purchase and well move on to our next request, the [Purchase Number API](/rest/signalwire-rest/endpoints/space/purchase-phone-number). Copy the Request URL and replace **demo.signalwire.com** with {{Space}} Make sure to change the request type from GET (default) to POST. This also means that instead of using the **Query Params** section, we will instead select the **Body** section. You can select **x-www-form-urlencoded** to use the same key-value type format as before for whatever body parameters youd like to use. Press send to proceed with purchasing the number and view data about your newly purchased number!

### Pulling All Calls within a Date Range Next, take a look at the documentation for [Listing Calls](/rest/compatibility-api/endpoints/list-all-calls). This component is very useful for getting reports on calls by date range, number pairs, status, and more. This example will show how you can filter all the failed calls from a particular number! This is a GET request, so we dont have to change the HTTP method type. Copy the Request URL and paste it into Postman, but notice that this time there is an **Account SID** parameter in the URL as well! Replace **demo.signalwire.com** with {{Space}} and **AccountSID** with {{Proj}}. Now, we will add two Query Params key-value pairs: From and Status. Make sure to encode the number with %2b in front of the number, and dont forget the country code! Now press send, and view your call logs easily formatted for you!

### Create a Domain App Our last example will show the other type of POST body parameters - raw JSON data. A good example of this is [creating a domain application](/rest/signalwire-rest/endpoints/space/create-domain-application) to handle inbound or outbound SIP traffic. Copy the request URL and make sure to replace **demo.signalwire.com** with {{Space}}. Switch to POST and select the body tab, but this time select **Raw** data with the type **JSON**. Enter the parameters you want in [JSON format](https://www.w3schools.com/whatis/whatis_json.asp) and press send, and your domain app is created!

## Saving Results When you send a request where the returned data is very important, you can also use Postmans **Save Response** feature to save it to a file. SignalWire API data is always returned in JSON format, so you can easily download and handle yourself with a database or your own applications!

## Generating Code in cURL or other languages Once you have run a request successfully on Postman, you might want to save the cURL code for it or even replicate the same request in your application instead. Click the icon on the right next to **Cookies** to generate the curl code for your request or the same request in popular languages! This is the generated version of the request above in Javascript - jQuery.

## Possible Encountered Errors Although this is by no means an exhaustive list, here are a few errors we see pop up commonly with Postman! | Error Name | Possible Error Cause | Steps to Try | |:--|:|:--| | Resource Not Found | The request is working, but the resource you are requesting does not exist. | Make sure the SIDs you are using match the environment that you are in, and that you are using the correct SID! | | 404 Error | You are attempting to do something the API does not recognize as a real request. | Double-check to make sure the URL is correct with no extra or hidden characters. | | Unauthorized | Your API credentials dont match. | Check to make sure your project ID, auth token, and Space URL are correct. Make sure to eliminate any whitespace or hidden characters. | | URL variables {{Space}} and {{Proj}} are red instead of orange. | Postman does not see any variables with this name. | Check to make sure there are no hidden characters or whitespace in your environment variable names. Ensure that you have an environment currently selected. Variable names are case sensitive! |