​invokeURL task for API calls

Table of Contents

Overview

The invokeUrl task is an HTTP client that allows you to access and modify:

  • web resources using HTTP calls.
  • data of one Zoho service from another Zoho service using the URL specified in its API
  • data of a third-party service connected to your Zoho service using the URL specified in its API. Click here to learn how you can connect your Zoho service with a third-party service using connections.

Note:

  • This task will throw "socket timeout error" if the web resource/ API takes more than 40 seconds to respond. 
    This means that the task will be terminated and you need to wait for a few moments before trying again.
  • In Zoho Creator, this task can download file up to 5 MB.  Some older accounts would allow downloads up to 50 MB which will eventually be reduced without affecting the existing scripts. Learn more.
  • In services other than Zoho Creator, you can download Zoho domain files of size up to 15 MB and other domain files of size up to 5 MB. 

Syntax

response =invokeUrl 
[ 
url: <url_value> 
type: [<type_value>] 
headers: [<headers_value>]
body: [<body_value>]
parameters: [<parameters_value>]
files: [<files_value>]
connection: [<connection_name>]
detailed: [<detailed_value>] 
response-format: [<response_format_value>] 
response-decoding: [<encoding_format_value>] 
];
ParameterData typeDescription
<response>KEY-VALUE/ FILE/ TEXT/ LISTThe variable that will contain the response returned.

<url_value>

 

TEXT

The request URL whose resources need to be accessed.

Note: URL domains with user-created SSL certificates cannot be invoked using this task.

<type_value>

(optional)

Constant

The HTTP request method.

Allowed values:

  • GET
  • POST
  • PUT
  • PATCH
  • DELETE
  • OPTIONS

Default value: GET

<headers_value>

(optional)

KEY-VALUEThe attributes or the header values.
<body_value>TEXT/ FILE/ KEY-VALUE

The optimal way to specify the data sent in an API request body.
 

Note: 

  • In order to add query parameters to the request, append the required value to the URL. For example, you can add the query param followed by the question mark(?) as part of the URL in the response,
    url: "http://www.thenonlinearpath.com/wp-content/uploads/2016/05/AddImage?page=2"
  • The content-type specified in the header must match the data format of the body_value. For example,
    headers: {"Content-Type": "application/json"}
    body: {"name":"John Doe", "email":"john.doe@example.com"}
  • The default content-type for each body format is listed below. However, if the header explicitly specifies a content-type value, it will override the default setting.

Request body formats in invokeUrl:

  • Raw: If the input value is of TEXT data, the body is considered to be in Raw format. Default content-type: text/plain. Alternatively, you can use application/json, text/html, application/xml, application/javascript, etc. by overriding content type using header.
  • Form data: If the input value is of Key-value data, by default the content-type will be sent as multipart/form-data. Alternatively, you can use application/x-www-form-urlencoded by overriding content type using header.
  • Binary: If the input value is file data, the body is considered to be in binary format. Default content-type: application/octet-stream. Alternatively, you can use application/pdf, image/png, etc by overriding content type using header.

     

Note: 

You can't specify both a parameter_value and a body _value param in an invokeurl syntax.

<parameters_value>

(optional)

TEXT/FILE/ KEY-VALUE

Specifies the body of the request when the body_value parameter is not used. For GET and DELETE type values, it functions similarly to a query parameter.

Note: When the type is specified as GET, the parameter value will be passed in the URL as a query parameter, rather than in the request body.

Send various types of request body using invokeUrl:

  • Raw:
    TEXT data to this parameter will be sent as raw type.
     
  • x-www-form-urlencoded:
    KEY-VALUE data to this parameter will be sent as x-www-form-urlencoded type.
     

  • Form-data:
    KEY-VALUE data to this parameter will be sent as multipart form-data type, if the value of the content-type parameter is specified as multipart/form-data.
     

    Note: 

    • If the value of the content-type parameter is not specified as multipart/form-data, the KEY-VALUE data is treated as x-www-form-urlencoded type.
    • In Zoho Creator, the multipart/form-data values must be specified in files parameter

  • Binary:
    FILE data is sent as binary type.
     

    Note: 

    • The value of the <content-type> parameter must be specified as application/octet-stream, to recognize that the body is sent as binary type.
    • Binary type is not applicable to Zoho Creator.

<files_value>

(optional)

FILE/ TEXT/ KEY-VALUE/ LIST of FILE/ LIST of TEXT/ LIST of KEY-VALUE

In Zoho Creator, if the body of the request needs to be sent as multipart form-data, the values need to be are supplied to this parameter.

Note: 

  • Only the files received as the response of an invokeUrl task can be attached.
  • This parameter can also be used in services other than Zoho Creator. However, to send multipart form-data from services other than Zoho Creator, we recommend that you supply the values as KEY-VALUE to the body parameter while specifying the content-type parameter as multipart/form-data.
  • The toFile function can be used here. For example, you can take a text value in csv format and use the 'toFile' function to pass it as a csv file. Please note that this function is currently not applicable to Zoho Creator.
  • In Zoho Creator, the input text that will be converted into file cannot be more than 50MB.

Format to send KEY-VALUE data,

  • If the value associated with the key is FILE:​
<variable> = {"paramName": <key>, "content": <File>};
  • If the value associated with the key is TEXT:
<variable> = {"paramName": <key>, "content": <Text>, "stringPart": "true"};

Format to send LIST of FILE data:

<File1>.setParamName(<FileName1>);
<File2>.setParamName(<FileName2>);
list_of_files = List();
List.add(<File1>);
List.add(<File2>);

setParamName built-in function is used to set the specified name for the file object that needs to be sent in multipart form-data using invokeUrl. This function cannot be applied on files fetched using fetch records task or input.<field_name> expression.

Format to send LIST of TEXT data:

list_of_text = List();
List.add(<Text1>);
List.add(<Text2>);

Format to send LIST of KEY-VALUE data,

  • If the values to the keys are FILES:
list_of_key_value = List();
list_of_key_value.add({"paramName": <key1>, "content": <File1>});
list_of_key_value.add({"paramName": <key2>, "content": <File2>});
  • If the values to the keys are of TEXT data type:
list_of_text = List();
list_of_text.add({"paramName": <key1>, "content": <Text1>, "stringPart": "true"});
list_of_text.add({"paramName": <key2>, "content": <Text2>, "stringPart": "true"});

<connection_name>

(optional)

TEXT

The connection name of the required service.

Note: Multiple connections can be created for the same service.

<detailed_value>

(optional)

BOOLEAN

This parameter decides if a detailed response needs to be returned.

Allowed values: 

  • true - returns response code (HTTP status code), header response, and response content as KEY-VALUE.
  • false - returns the response content.

Default value: false

<response_format_value>

(optional)

Constant

This parameter determines how the response from the API is handled.
Allowed values:

  • NONE
  • STRING
  • FILE

If this parameter is supplied with the NONE value, no response will be accepted, and the response will remain empty.
If this parameter is supplied with the STRING value, the response—whether it is in JSON, map, or any other format—will be converted to a string.
If this parameter is supplied with the FILE value, the response will be converted and returned as a file object.

Note: The STRING and FILE options are not applicable in Zoho Creator.

<encoding_format_value>

(optional)

TEXT

The character encoding scheme with which the response returned needs to be decoded.

Allowed values: Click here to find the list of allowed values to this parameter.

Default value: UTF-8

Example 1: Fetch a file from the web

The following script fetches an image from the web using its URL:

 response = invokeUrl
 [
 url: "http://www.thenonlinearpath.com/wp-content/uploads/2016/05/GoodVibesOnly.png"
 type: GET
 ];

where:

response
TheFILE that holds the image that will be fetched from the web.
"http://www.thenonlinearpath.com/wp-content/uploads/2016/05/GoodVibesOnly.png"
The TEXT that represents the URL of the image that needs to be fetched.
GET
The HTTP request method.

Example 2: Upload file to Zoho WorkDrive

The following script uploads a file using the URL specified in the Zoho WorkDrive API:

Note: When using a Map as the request body, the default content type is multipart/form-data. However, you can override this by setting the Content-Type header to application/x-www-form-urlencoded.
// File Upload to Zoho WorkDrive
fileToUpload = invokeurl
[
url :"https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf"
type :GET
];
info fileToUpload;

// Upload the file to WorkDrive
bodyParam = map();
bodyParam.put("parent_id","0567s97d5252736c84d2981f138baeb237312");
bodyParam.put("content",fileToUpload);
uploadResp = invokeurl
[
url :"https://workdrive.zoho.com/api/v1/upload"
type :POST
body :bodyParam
connection :"workdrive_connection"
];
info uploadResp;

where:

"https://workdrive.zoho.com/api/v1/upload"
URL used to upload a file to Zoho WorkDrive via API.
POST
The HTTP request method to upload data.
bodyParam
Map containing the file and folder ID (as parent_id) for upload.
"workdrive_connection"
The connection name authorized with WorkDrive.

Example 3: Fetch the list of files from the connected Dropbox account

The following script fetches all the files from the folder - test_folder of the connected Dropbox account using its API:

// Create a variable to hold the parameters that is required by Dropbox API
raw_data = Map();
raw_data.put("path", "/test_folder");

// Create a variable to hold the headers that is required by Dropbox API
header_data  = Map(); 
header_data.put("Content-Type", "application/json");

// Supply the URL, parameters, and headers to the invoke URL task  
response = invokeUrl  
[  
url: "https://api.dropboxapi.com/2/files/list_folder"  
type: POST  
parameters: raw_data.toString()  
headers: header_data
connection: "dropbox_connection"  
];

where:

"https://api.dropboxapi.com/2/files/list_folder"
The TEXT that represents the URL specified in the Dropbox API to fetch all the files from the specified folder.
raw_data.toString()
The TEXT that holds the path of the folder. The toText is a Deluge built-in function that converts a value into TEXT data type. Click here to learn more about it.
header_data
The KEY-VALUE variable that holds the header values required by Dropbox API.
"dropbox_connection"
The TEXT that represents the name of the connection.
Note: Click here to find the list of ports in which the invoke URL task can be executed.

Example 4: Upload a list of files to the Candidates module of Zoho Recruit

The following script attaches the two files to the specified record of Zoho Recruit's Candidate module:

// Download the required files from web
cv = invokeurl 
[ 
url:"https://www.office.xerox.com/latest/SFTBR-04U.PDF" 
]; 
cover_letter = invokeurl 
[ 
url:"https://filesamples.com/samples/document/txt/sample1.txt" 
];

// Create parameter key-value pairs
param1 = {"stringPart":"true", "paramName":"id", "content":"690423000000432208"}; 
param2 = {"stringPart":"true", "paramName":"type", "content":"Resume"}; 
param3 = {"stringPart":"true", "paramName":"version", "content":"2"};
 
// Add the files and parameter key-value pairs to a list
file_list = List(); 
file_list.add(cv); 
file_list.add(cover_letter); 
file_list.add(param1); 
file_list.add(param2); 
file_list.add(param3); 
 
// Perform API call to upload the files to Candidate module of Zoho Recruit

response = invokeurl 
[ 
url: "https://recruit.zoho.com/recruit/private/json/Candidates/uploadFile" 
type: POST 
files: file_list 
connection: "recruit_oauth_conection" 
]; 
info response;

where:

"https://recruit.zoho.com/recruit/private/json/Candidates/uploadFile"
The TEXT that represents the API URL to upload files to Zoho Recruit.
id 
type 
version 
The TEXT parameter keys required by Recruit API.
"recruit_oauth_connection"
The TEXT that represents the name of the connection.

Example 5: Remove a whitelisted email in Zoho Mail using invoke URL

The following script removes a whitelisted email address from the spam settings of an organization in Zoho Mail:

// Define the parameter with spam category and whitelist email

param = {
 "spamCategory":"whiteListEmail", 
 "whiteListEmail":{"mysupply@mysupplydomain.com"}
};  
        
response = invokeurl
[
url: "https://mail.zoho.com/api/organization/68XXXXX72/antispam/data"
type: DELETE
body: param.toString()
headers: {"content-type":"application/json"}
connection: "mail_connection"
];
info response;

where:

param
The MAP that defines the spam category and the specific email address to be removed from the whitelist.
https://mail.zoho.com/api/organization/68XXXXX72/antispam/data 
type 
version 
The TEXT that represents the API endpoint to manage spam settings for the specified organization.
DELETE
The TEXT request method used to remove the whitelisted email from the specified category.
param.toString()

The TEXT formatted body payload that includes the whitelist removal data.

content_type

The MAP that specifies the request's content type to be in JSON format.

mail_connection
The TEXT that refers to the connection created for authenticating with the Zoho Mail API.

Example 6: Create a contact in Zoho Books

The following script adds a new contact to an organization in Zoho Books using an invoke URL:

Note: When using a string as the body in an invoke URL, the default content type is text/plain. If you're sending JSON data, make sure to override this by setting the Content-Type header to application/json. You can also specify other content types like HTML, XML, or JavaScript using the headers parameter.
contact_info = Map();  
contact_info.put("contact_name", "Shawn");                                                                           
                                                                                                                                
response = invokeurl
[
 url :"https://books.zoho.com/api/v3/contacts?organization_id=53792286"
 type : POST
 body : contact_info.toString()
 headers : {"content-type":"application/json"}
 connection : "books_connection"
];
info response;

where:

"https://books.zoho.com/api/v3/contacts?organization_id=53792286"
The Zoho Books API endpoint to create a contact.
POST
The HTTP request method.
contact_info.toString()
Serialized map holding contact info as string.
"books_connection"
Authorized connection to Zoho Books.

Example 7: Upload file to Dropbox

The following script uploads a PDF file to Dropbox using an invoke URL:
 

Note: When fileToUpload is of type File and used as the request body, the default content type is application/octet-stream. You can override this by setting the Content-Type header using the headers parameter—for example, application/pdf, image/png, or other relevant file types.
fileToUpload = invokeurl
[
  url: "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf"
  type: GET
                                                                ];                
hd = {"path":"/dummy.pdf","mode":"add","autorename":true,"mute":false,"strict_conflict":false};
driveheaders = Map();
                                                                driveheaders.put("Dropbox-Api-Arg",hd);                                          
uploadResp = invokeurl
[
  url: "https://content.dropboxapi.com/2/files/upload"
  type: POST
  body: fileToUpload
  headers:driveheaders
  connection : "dropbox_connection"
];
info uploadResp;

where:

fileToUpload
Binary file object retrieved from web.
hd
JSON arguments passed to Dropbox API in headers.
POST
HTTP method used for upload.
"dropbox_connection"
Connection used to authenticate Dropbox API calls.

Response Format

Success Response

  • The success response when the <detailed_value> param is set to true, will be returned in the following format:

        {
      "responseText": "GoodVibesOnly.png",
      "responseHeader": {
        "date": "Wed, 23 Oct 2019 10:03:31 GMT",
        "server": "Apache",
        "content-length": "159500",
        "expires": "Wed, 23 Oct 2019 16:03:31 GMT",
        "x-endurance-cache-level": "2",
        "x-cache-lookup": "MISS from 172.30.232.40:3128",
        "via": "1.1 172.30.232.40 (squid/4.1)",
        "last-modified": "Wed, 04 May 2016 01:44:18 GMT",
        "content-type": "image/png",
        "connection": "keep-alive",
        "x-cache": "MISS from 172.30.232.40",
        "accept-ranges": "bytes",
        "cache-control": "max-age=21600"
        },
        "responseCode": 200
        }

To fetch the content-type from the response header obtained, execute the following script:

 <variable> = response.get("responseHeader").get("content-type") ;

Related Links