API Call
  • 01 Jun 2023
  • 10 Minutes to read
  • Contributors
  • Dark
  • PDF

API Call

  • Dark
  • PDF

Article Summary

The API Call node is a powerful tool that enables you to make requests to any available API. This node provides a flexible and efficient way to interact with external systems and integrate them into your workflows (see Picture 1).

API Call.png

Picture 1. API Call node task flow

With the API Call node, you can easily connect to a wide range of APIs, such as social media platforms (LinkedIn, Facebook, Twitter, Google, etc.), banking services (Visa, Mastercard payment and info services), web services, and exchange data with them.

Before getting started with writing API requests, it is crucial to thoroughly read the documentation of the specific API you intend to use. This will help you understand the required structure and authentication methods for making successful requests. It will also provide you with crucial information, such as the API endpoints, request methods, parameter formats, etc.

Request IP addresses

All API Requests are made from the following IP addresses:

If you encounter access errors when calling third-party APIs, you might need to white-list these addresses.

Node Settings

API request URL

URL - Request URL/endpoint. Corezoid supports the standard HTTP/HTTPS protocol and can accept any valid endpoint format, including URLs, IP addresses, and more.

Request format:

Default - standard HTTP/HTTPS request format. It adds a convenient Key-Value editor for query parameters and a request method dropdown menu.

Corezoid - similar to the Default format, but removes the ability to select a request method.

Raw - free form request format. Allows you to write custom request bodies. It is useful in cases when an API follows a non-standard request format.

Request method

Allows you to specify the type of request you want to make using a dropdown menu. It's important to note that some APIs may have the same endpoint for different request methods.

POST - send data
GET - retrieve data
PUT - create or update existing data
DELETE - delete data
HEAD - similar to POST, but does not return a response body
PATCH - update only a part of the data

Data format

  • JSON
  • form
  • XML


Content-Type is used to indicate the format of the data being sent in the request body. This field will be pre-filled automatically based on the Data format you've selected, however, you can edit it to fit your specific needs.

Default types based on Data format:

  • JSON - application/json; charset=utf-8
  • form - application/x-www-form-urlencoded; charset=utf-8
  • XML - application/xml; charset=utf-8

Request Parameters

Request's query parameters.


Key - parameter name.
Value - parameter value.

Add "key-value" - add a new parameter field.

Code editor - code editor of the corresponding JSON.


Header parameters - request’s Header parameters. Headers are used to provide additional information about the request, such as authentication parameters, and various metadata. You can specify it in the same Key-Value format as the Request Parameters.

Customize response parameters - allows you to modify the response header and body parameters. It also allows you to specify the response format before the task is released from the node.

This feature can be particularly useful when dealing with APIs that provide an incorrect response format or do not specify a format at all. By customizing the response parameters, you can ensure that the response is parsed correctly.

Another use case for this feature is to minimize the amount of data to be added to a task. Oftentimes, your API request will return a lot of data, but you only need to extract a small number of specific parameters. In this case, you can use the Customize response parameters feature to only extract the necessary data.

Limit the number of simultaneous requests to the API - This feature allows you to control the maximum number of concurrent requests made to the API. By default, it is set to 5, but you can adjust it to comply with the number required by the API.

Add system parameters to the request- This checkbox allows you to add Corezoid's system parameters to your API request. These parameters are necessary when you are making a request to Corezoid's API. The parameters that will be added are conv_signature, conv_time, and conv_id. You can learn more about them here.


Some APIs have strict requirements regarding the parameters that can be included in a request. If this is the case for the API you're using, you may need to uncheck the box to exclude the Corezoid system parameters from your request.

Sign the request with secret key - This option is specifically designed for making requests to Corezoid's API, which requires all requests to be authenticated with a secret key. You must also select the "Add system parameters to the request" option to include the necessary system parameters along with the request.

RFC standard response - When this option is selected, the response will be processed in compliance with the RFC standard.

When this option is selected, a response body is mandatory for response codes 200 and 201. For the 202 response code, the response body is optional.

Include debug info - Enabling this option adds extra information about the API request to a task parameter called conveyor_api_debug. This additional information includes the execution time, request body size, response code, and response body size.

Sample conveyor_api_debug object:

 "__conveyor_api_debug__": {
        "http_exec_time": 328.552,
        "http_req_body_size": 0,
        "http_res_code": 200,
        "http_res_body_size": 1132

Sign the request by certificate - In certain cases, APIs may require you to include a client certificate with your request. If your API mandates the use of a client certificate, you can conveniently add it by selecting this option.

The client certificate should be in PEM format. It should be formatted like this:

....your private key goes here....
....your certificate goes here....

Alert if the number of tasks in the node queue reaches the following number - a condition that will be met when the node has a specified number of tasks in it. If this option is selected, a new edge will be created.

Maximum interval, for which the task stays in the node before being forwarded - the amount of time a task must spend in this node. Can be specified in seconds, minutes, hours, or days.


There are innumerable ways in which companies choose to implement their APIs. They can use different data formats, however, JSON and XML are the most commonly used. Some require headers, some don't. Some require a certificate, others don't. Some make you generate an authentication code and periodically renew your access token, while others simply want you to provide an API key or token.

All of these choices have good reasons behind them, and Corezoid strives to simplify the process of working with all the different API configurations, but it means that every case is a little bit different and will require you to look up the specific requirements of the API you are using. This also means that there is no obvious set of examples that would cover all possible features.

In this section, we provide an illustration of making an API call to one of the more popular libraries. For more intricate examples, we recommend exploring the tutorials section, where you can find guidance on handling more complex scenarios and configurations.

API call to OpenWeatherMap

OpenWeatherMap is a popular API that you can use to check the weather at any location. It is also free!

For the purpose of this example, let's say we want to get the current weather in San Fransico.

A good place to start is to look at the API documentation. When doing so, you want to find the answers to the following questions:

  • What is the endpoint URL?
  • What parameters need to be specified? Where?
  • How does this API handle authorization/ authentication?

In the API's documentation, we find the structure of the API call:

https://api.openweathermap.org/data/2.5/weather?lat={lat}&lon={lon}&appid={API key}

Here, https://api.openweathermap.org/data/2.5/weather is the endpoint, and lat, lon, and appid are the parameters.

We are told that appid is our unique API key, which we get can by creating an account with the service. You can get yours for free here. The API key is what this service uses to authorize requests. Once you make an account, you will need to generate a new API key. Store it somewhere safe!

Now that we have all the required information, we can fill out our API Call node and make our first request (see Picture 2).


Picture 2. Making a request with specified parameters from the API Call node

Note that in the URL field, we only include the endpoint URL, and add the parameters under Request Parameters. This is done for convenience only, as separating the two makes it easier to see and manipulate parameter values. You can still specify the parameters within the URL string if you wish to do so.

Another thing to note is that we changed the Request method to GET since we will be getting information from the resource.

Now, we switch to View mode and create a new task with no parameters, since our process doesn't take any.

The task passes through the API Call node, and we instantly get back a response with the current weather in San Francisco (see Picture 3).

Screenshots 1.png

Picture 3. A response from an API triggered by a task sent through the API Call node

Looks like it's cloudy. Better grab a sweater!

Getting task parameters from State Diagrams

In this node, you can access a single task parameter or a whole task stored in a State Diagram using these constructions.

Error handling & troubleshooting

When an error occurs in the node, a task goes to the auxiliary Condition output node (Picture 4):


Picture 4. API Call node's auxiliary output node

This auxiliary Condition node is used for storing error parameters. With that, the following fields are added to the initial task depending on the error and node type:

Error parameter nameParameter description
__conveyor_node_type_return_type_error__Error type: hardware (system error), software (error in a node logic/settings)
__conveyor_node_type_return_type_tag__Error tag (see the *-marked errors in Error tag column of the table below)
__conveyor_node_type_return_type_description__Error description in human-readable language. Can be static or dynamic
Problem/Error tagCauseSolution
*"api_expire_query" errorYour API query has expired. Either the API has taken too long to respond or the number you set in Limit the number of simultaneous requests to the API has been exceeded.Check with the API provider for possible causes.
*"api_bind_error" errorThe request parameters you defined in the key-value fields could not be added to the URL to form a requestMake sure your parameters are formatted correctly.
*"api_fatal_error" errorThere was an internal process error when making an API request.Contact support for assistance.
*"api_bad_answer" : "timeout" or "failed_connect" errorThe node did not receive a response from API or failed to establish a connection with it after 60 seconds.Check with the API provider for possible causes. Make sure URL you provided is correct. Corezoid will reattempt to make a request every 30 seconds.
*"api_no_valid_json" errorThe request header/body is incorrectly formatted.Correct the request header/body format.
*"api_no_ops" errorThe API response does not contain an ops block or contains an incorrect ops blockPlease refer to the API documentation for detailed information on the correct ops block
*"api_task_size_overflow_limit" errorThe size of the task data exceeds the indicated limit set for your environmentPlease reduce the size of your task by modifying the data or splitting it into several smaller tasks
*"wrong_validate_params" error when using customize response parametersThe variable that the node is trying to access was not sent by the API or has a type that differs from the one that was specified.Make sure the parameters you are attempting to modify exist or change the parameter type.
*"api_bad_answer" : "no_scheme" errorURL field is emptyThe URL field will allow you to specify an empty URL in the case when it is referencing to an empty variable. Make sure to provide a valid URL.
*"api_no_request_proc" errorBad "request_proc" tag setPlease ensure that you specify "request_proc=ok" for your response. If you intend to send an error, use "proc!=ok"
*"api_wrong_convert_param" errorParameter value failed to convert with the specified parameter typePlease check and correct the data type of the parameter mentioned in the error message
*"api_bad_res_data" errorThe data format you are trying to send to the API is incorrectPlease refer to the API documentation for detailed information on the correct format

*the node errors that are listed with the exact error tag (conveyor_node name_return_type_tag).

What's Next