Troubleshooting API Connectivity with Postman

  • API Documentation

Often, connectivity problems result in a general "SSL handshake error", which can be caused by various errors related to a mutual TLS Authentication failure. This article described how to test and verify connectivity using Postman -- an API client that allows you to easily create and save simple and complex HTTP/s requests and read their responses. 

Common causes of connectivity issues include:

  • The certificate is not configured correctly in the customer integration engine
  • An incorrect URL is being used
  • The customer IP address is not on the allow list
  • Cipher Suites are not supported by Verato
  • SNI is not supported by the customer integration engine

What you will need

If you contact customer support to help you troubleshoot API connectivity issues, we request the following information to help us troubleshoot the problem and find a solution as quickly as possible: 

  • The client IP address to be added to the allow list by Verato
  • The client email address with whom the credentials (Verato username/account) should be shared.
  • Optional: Does the client need Verato IPs to be added to the allow list on their end?

Once this information is shared with the Verato support agent, we create an environment and share credentials with the client for them to connect with Verato.

In addition, to connect successfully with Verato, you will need following information, which will be sent in encrypted emails by Verato:

  • The API username for their environment 
  • The URL for the environment 
  • The API password for their environment 
  • The API certificate to successfully authenticate via Mutual TLS
  • The password for the API certificate shared 

Configuring and testing connectivity with Postman

Once you have gathered all of the necessary information and credentials outlined in the previous section (above),  do the following to connect via Postman.

  1. Open Postman. From the main menu, select File > New.
  2. Select Request.
  3. Enter the name of the request and a collection where this request needs to be saved. (You can create a new collection or use an existing collection.)
  4. After the request is created, the postman screen will show a new GET method request.
  5. Now since all Verato API calls are POST method requests, please modify the GET request to POST.
  6. Select the GET request drop down, and then select POST. 
    postman_get_dropdown_anno.png
  7. Enter the complete URL (emailed to you by Verato) and resource type in the following format: https://custXXXX-api.verato.com , where XXXX will be a 4-digit number.
    The resource type for Verato API services is of the format: /link-ws/svc/<resourceType>. For this guide, we will be using nativeIdQuery as an example.
  8. Select the Auth tab. In the Type drop menu, select Basic Auth (Verato currently supports only BASIC Authentication mechanism). Enter the username and password emailed to you by Verato.
  9. Select Settings, and then select the settings icon.
    postman_settings.png
  10. Select Certificates, and then select Add Certificate.
  11. Enter the following information, and then select Add
    • Host - Use the hostname shared in the email sent to you by Verato. 
    • CRT File - The .cer format of your certificate
    • KEY File - The .pem format of your certificate
    • PFX File - The .p12 format of your certificate
    • Passphrase - Use your certificate password. 
  12. Select Body. In the drop menu, select Raw
  13. In the Text drop menu, select JSON.
  14. Copy paste an API request you would like to send, and then select Send
    postman_copy_paste_api_request_anno.png
  15. If your connection was correctly configured, next to Status you should see a 200-status code in the response body.
    postman_response_status_code_success_anno.png
Note
If you do not see a 200-status code, verify all of the configuration information (passwords, URLs, etc.) for each step was configured properly. If you are still unable to receive a 200-status code, please submit a ticket to Verato Support.