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>] content-type: [<content_type_value>] parameters: [<parameters_value>] files: [<files_value>] connection: [<connection_name>] detailed: [<detailed_value>] response-format: [<response_format_value>] response-decoding: [<encoding_format_value>] ];
| Parameter | Data type | Description |
| <response> | KEY-VALUE/ FILE/ TEXT/ LIST | The 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:
Default value: GET |
<headers_value> (optional) | KEY-VALUE | The attributes or the header values. |
<content_type_value> (optional) | TEXT | The type of content that needs to be sent in the body of the HTTP request. Allowed values: Any valid content type. Eg, multipart/form-data, application/x-www-form-urlencoded, application/json, etc. Default value:
Note: This parameter is not applicable to Zoho Creator. |
<parameters_value> (optional) | TEXT/FILE/ KEY-VALUE | The body of the request. 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:
|
<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:
Format to send KEY-VALUE data,
<variable> = {"paramName": <key>, "content": <File>};
<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,
list_of_key_value = List(); list_of_key_value.add({"paramName": <key1>, "content": <File1>}); list_of_key_value.add({"paramName": <key2>, "content": <File2>});
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:
Default value: false |
<response_format_value> (optional) | Constant | If this parameter is supplied with the value - FILE, the response is converted and returned as a FILE object. Allowed values: FILE Note: This parameter is not applicable to 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"http://www.thenonlinearpath.com/wp-content/uploads/2016/05/GoodVibesOnly.png"GETExample 2: Create a contact in Zoho Books using invoke URL
The following script creates a contact with the specified values in Zoho Books using the URL specified in the Zoho Books API:
// Create a map that holds the values of the new contact that needs to be created contact_info = Map(); contact_info.put("contact_name", "Shawn");
// Format the data as specified in the Zoho Books API data = Map(); data.put("JSONString", contact_info);
// Supply the URL and parameters to the invoke URL task response = invokeUrl [ url: "https://books.zoho.com/api/v3/contacts?organization_id=58XXXX07" type: POST parameters: data connection: "books_api_connection" ];
where:
"https://books.zoho.com/api/v3/contacts?organization_id=58XXXX07"POSTdata"books_api_connection"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"raw_data.toString()
header_data"dropbox_connection"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:
// Downlod 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"id type version
"recruit_oauth_connection"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") ;