You should use the Request method to avoid exposing sensitive information, such as API keys or user credentials, when you make HTTP requests to third-party domains as agents will be able to inspect these values in a browser and access them. The other benefit is Cross-Origin Resource Sharing (CORS) support as requests are routed through a proxy.

Notes:
1. All apps that make requests to third-party domains must use the Request method or they will not be published in the Freshworks Marketplace.
2. The timeout for requests is six seconds.
3. There is a rate limit of 50 requests per minute per app per account.
4. In the response of a request call made using the Request method, the Content-Type header attribute specifies the response format. The accepted response formats are:
- application/json
- application/jsonp
- application/vnd.api+json
- application/xml
- text/plain
- text/html
- text/xml
- text/javascript

Usage

The Request method should be defined in the app.js file by using the following syntax.

1
2
3
4
5
6
7
8
9
10
client.request.get("URL", options)
  .then(
    function(data) {
      //handle "data"
      //"data" is a json string with status, headers, and response.
    },
    function(error) {
      //handle failure
    }
  );

The Request method should be defined in the server.js file by using the following syntax.

1
2
3
4
5
6
7
8
9
10
$request.get("URL", options)
  .then(
    function(data) {
      //handle "data"
      //"data" is a json string with status, headers, and response.
    },
    function(error) {
      //handle failure
    }
  );

The following table lists the parameters and their description.

Using iparams

Iparams can be used in requests as part of the following:

• Header
• URL Copied Copy

  1
  https://passport-office.com/user?id=<%= iparam.passport %>

• Body Copied Copy

  1
  2
  3
  4
  5
  6
  7
  8
  9
  10
  11
  12
  client.request.post("https://helloworld.freshservice.com/api/tickets", {
        headers: {
          Authorization: "Basic <%= encode(iparam.username + \":\" + iparam.password) %>"
        },
        body: JSON.stringify({
          status: 2,
          priority: 1,
          description: "Test",
          subject: "<%= iparam.subjectPrefix %> Hello there",
          email: "tom@outerspace.com"
        })
       });

  EXPAND ↓

Sample Requests

For API requests that require authentication, you may need to encode the auth header in base64 format.

1
2
3
4
5
6
7
8
9
10
11
var headers = {"Authorization": "Basic <%= encode(iparam.api_key) %>"};
  var options = { headers: headers };
  var url = "https://sample.freshservice.com/itil/requesters/5.json";
  client.request.get(url, options)
  .then (
  function(data) {
    console.log(data);
  },
  function(error) {
    console.log(error);
  });

If the request is successful, data is returned in the following format. In case a network or 429/5xx HTTP error occurs, the app will retry the request a number of times to obtain the response. Here, attempts is the number of times after which the request has returned a response.

1
2
3
4
5
6
7
8
9
10
{
    status : 200,
    headers:
    {
      "Content-Length": 20,
      "Content-Type": "application/json;charset=utf-8"
    },
    response: "{ "Name": "Rachel"}",
    "attempts": 1
}

If the request fails, an error response is returned in the following format.

1
2
3
4
5
6
7
8
9
{
    status : 401,
    headers: {
      "Content-Type": "application/json;charset=utf-8"
   },
   response: [{"message": "Session expired or invalid",
   "attempts": 1,
   "errorCode": "INVALID_SESSION_ID"}]
}

If the request fails due to an error from the app, the error response is returned in the following format. Here, attempts is the number of times after which the request has returned a response.

1
2
3
4
5
6
7
8
9
10
{
    "status" : 400,
    "headers":
    {
      "Content-Type": "application/json;charset=utf-8"
    },
    "response": "This domain has not been whitelisted.",
    "attempts": 2,
    "errorSource": "APP"
  }

1
2
3
4
5
6
7
8
9
10
var options = {};
  var url = "https://httpbin.org/get?arg1=hello_world";
  client.request.get(url, options)
  .then (
  function(data) {
    console.log(data);
  },
  function(error) {
    console.log(error);
  });

1
2
3
4
5
6
7
8
9
10
11
var headers = {"Authorization": "Basic <%= encode(iparam.api_key) %>"};
  var options = { headers: headers, body: "Hello world"};
  var url = "https://sample.freshservice.com/tickets.json";
  client.request.post(url, options)
  .then (
  function(data) {
    console.log(data);
  },
  function(error) {
    console.log(error);
  });

For information on how to make an OAuth request, see Usage in the OAuth section.

Testing

For information on how to test an app that uses the Request method feature, see Test your App.

IP Ranges

Here is the list of IPs you must whitelist when using Request APIs if IP whitelisting is enabled on the Freshservice support portal or you wish to whitelist requests from your app.

Errors

In case of failure when making requests, a status code is displayed along with a message to help troubleshoot the issue.

An example of a status code and message is as follows.

1
2
3
4
5
6
7
8
9
10
11
{
  "status": 401,
  "headers": {
    "Content-Type": "text/plain"
  },
  "response": [{
    "message": "Session expired or invalid",
    "errorCode": "INVALID_SESSION_ID"
  }]

}

The following table lists all the supported status code.