Request API

You should use the Request API to avoid exposing sensitive information, such as your API keys or user credentials, when you make HTTP requests to third-party domains as users 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.

Note:
1. All apps that make requests to third-party domains must use the Request API or they will not be published in Marketplace.
2. Requests made using the Request API should return String, JSON, or XML data type.
3. The timeout for request is six seconds.
4. There is a rate limit of 50 requests per minute per app per account.

Configure

To use the Request API, the list of domains should be specified in the manifest.json file.

  • You must use only HTTPS.
  • Do not use IP addresses.

Example 1
If your app makes an API call to https://example.com/api/1.json, include the following in the manifest.json file.

Copied Copy
1
2
3
"whitelisted-domains": [ "https://www.google.com" ]

Example 2
Sometimes you will have to make calls to a URL whose name is not static. For example, users who sign up for a Freshsales account have a unique Freshsales domain. So, if your app makes calls to the Freshsales domain, part of the domain value will come from Installation Parameters (iparams).

To whitelist such domains, include the following code in the manifest.json file.

Copied Copy
1
2
3
"whitelisted-domains": [ "https://<%= iparam.subdomain %>.freshsales.io" ]

In the above sample code, subdomain is the display name of the iparam.

Example 3
Wildcards are supported to enable you to whitelist all subdomains of a parent. For example, an app wants to make requests to multiple Freshsales accounts like menswear.freshsales.io, kidstoys.freshsales.io, accesories.freshsales.io, and so on.

To whitelist such domains, include the following code in the manifest.json file.

Copied Copy
1
2
3
"whitelisted-domains": [ "https://*.freshsales.io" ]
Usage

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

Copied Copy
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 } );

PARAMETER DESCRIPTION
URL Is mandatory to make the Request API call.
options Is a JSON object and can include the following properties:
  • headers: HTTP Headers
  • body: Entity body, applicable for PATCH, POST, and PUT requests. Should be a string.
data Data received from the Request API if the request is successful.
error Data received from the request if an error is encountered.

Using Iparams

Iparams can be used in the requests as part of the URL, header, or body. The iparams should be enclosed within tags as shown in the following example.

Copied Copy
1
https://sample.freshsales.io/?data=<%= iparam.name %>

In addition, you can hide privileged information (apart from the API key, username, and password) included as part of a request. For example, imagine that you are making a call to a third-party resource which requires your passport number as part of the URL. This can be hidden by using the following syntax.

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

Request API should be defined in the app.js file, you can use the following sample requests for reference:

1. GET request with authentication Copied Copy
1
2
3
4
5
6
7
8
9
10
11
var headers = {"Authorization": "Token token=<%= encode(iparam.api_key) %>"}; var options = { headers: headers }; var url = "https://sample.freshsales.io/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.

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

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

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

2. GET request without authentication Copied Copy
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); });

3. POST request with authentication Copied Copy
1
2
3
4
5
6
7
8
9
10
11
var headers = {"Authorization": "Token token=<%= encode(iparam.api_key) %>"}; var options = { headers: headers, body: "Hello world"}; var url = "https://sample.freshsales.io/api/leads"; client.request.post(url, options) .then ( function(data) { console.log(data); }, function(error) { console.log(error); });

OAuth Request

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

Testing

Open your console, navigate to your project folder, and execute the following command. $ fdk run

During testing, you may see a shield icon in the browser address bar. Clicking the icon displays a warning message as the support portal runs on HTTPS while the server that is used for testing runs on HTTP. Click Load Unsafe Scripts to continue testing.

Errors

In case of request failure, 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.

Copied Copy
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.

STATUS DESCRIPTION
400 Is returned due to invalid input. For example, if you are making a request to a domain that has not been whitelisted, you will receive this status.
401 Is returned if you performed an unauthorized request.
429 Is returned when the number of requests exceeds the threshold.
500 Is returned if the server encountered an unexpected error. If this error persists, contact us at support@freshsales.io.
502 Is returned when there is a network error. If this error persists, contact us at support@freshsales.io.

Log in with your Freshsales account

Enter your helpdesk URL to proceed to login

Proceed

By clicking "Proceed", you agree to our Terms of Use.