Choose where you’d like to start

​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>] 
];
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

Default value: GET

<headers_value>

(optional)

KEY-VALUEThe 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:

  • application/x-www-form-urlencoded, if the body is KEY-VALUE.
  • text/plain, if the body is TEXT.
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:

  • 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

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
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: 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"
The TEXT that represents the URL specified in the Zoho Books API to create a contact.
POST
The HTTP request method.
data
The KEY-VALUE variable that holds the values of the contact that needs to be created.
"books_api_connection"
The TEXT that represents the connection name.

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:

// 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"
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.

Generate Script

↻

Note: Your data isn't stored, and all conversions happen only on your browser.



 


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

Get Started Now

Execute