invokeURL task for API calls
Table of Contents
- Overview
- Syntax
- Examples
- Example 1: Fetch a file from the web
- Example 2: Upload file to Zoho WorkDrive
- Example 3: Fetch the list of files from the connected Dropbox account
- Example 4: Upload a list of files to Candidates module of Zoho Recruit
- Example 5: Remove a whitelisted email in Zoho Mail using invoke URL
- Example 6: Create a contact in Zoho Books
- Example 7: Upload file to Dropbox
- Response Format
- Related Links
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>] ];
| 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. |
| <body_value> | TEXT/ FILE/ KEY-VALUE | The optimal way to specify the data sent in an API request body. Note:
Request body formats in invokeUrl:
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:
|
<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:
responseTheFILE 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.
GETThe 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.
POSTThe HTTP request method to upload data.
bodyParamMap 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_dataThe 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:
paramThe 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.
DELETEThe 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_typeThe MAP that specifies the request's content type to be in JSON format.
mail_connectionThe 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.
POSTThe 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:
fileToUploadBinary file object retrieved from web.
hdJSON arguments passed to Dropbox API in headers.
POSTHTTP 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") ;