API Request

API Request connects your flow to any service that offers a public web address for reading or sending data: a CRM, an ERP, an online store or an internal tool at your company. You tell it the address, the kind of operation and, if needed, the data to send. The component makes the call and gives you back what the service answers.

Use it when NappAI has no dedicated component for the service you need, or when you want an operation that the dedicated component does not cover.

When to use it

• Check an order’s status in your logistics provider’s system from its number.
• Add a contact to your CRM every time someone fills in a form.
• Fetch up-to-date prices or stock from your ERP before an agent answers a customer.
• Tell an internal tool that a process has finished.
• Call several addresses at once and gather their answers in a single result.

Configuration

Field	What it does
URLs (required)	The address or addresses to call. If you enter several, separate them with commas: the component calls all of them with the same settings.
Method (required)	The kind of operation: GET to read, POST to create or send, PATCH to change part of something and PUT to replace it. Default: GET.
Headers Mode	How you write the headers: JSON, all together in the Headers field, or Create Manually, one by one. Default: JSON.
Headers	The headers of the call, for example the access key the service gives you. Shown when Headers Mode is JSON.
Number of Headers	How many headers you want to add one by one. Shown when Headers Mode is Create Manually; it creates a Header 1 Key / Header 1 Value pair for each one.
Body Mode	How you write the data you send: JSON, Create Manually (JSON), field by field, or x-www-form-urlencoded, the format of a web form. Only shown for the POST, PATCH and PUT methods. Default: JSON.
Body	The data you send to the service. Shown when Body Mode is JSON or x-www-form-urlencoded.
Number of Body Fields	How many fields you want to add one by one. Shown when Body Mode is Create Manually (JSON); it creates Body Field 1 Key / Body Field 1 Value, and so on.
Query Parameters Mode	How you write the filters that go in the address itself: JSON or Create Manually. Default: JSON.
Query Parameters	The filters added to the address, for example a search term or a page number.
Number of Query Parameters	How many filters you want to add one by one. Shown when Query Parameters Mode is Create Manually.

Advanced options

Field	What it does
Curl	If the service’s documentation gives you an example call in curl format, paste it here: the component fills in the address, method, headers, data and filters for you.
Timeout	Seconds to wait for the answer before giving up. Default: 5.

With Body Mode set to x-www-form-urlencoded you can send files: if a field receives a file from another component, it is attached to the call the way a web form would do it.

In the Batch Mode tab you can connect a list to Batch Input so the component makes one call per item and gathers all the answers. See Batch Mode.

Output

The Data output returns one result per address called, with:

• source: the address that was called.
• status_code: the code the service answered with, for example 200 when everything went well or 404 when it did not find what you asked for.
• result: what the service returned.
• headers: the headers that were sent.

If the service does not answer in time, the result has status_code 408 and an error field. If the call cannot be made, it has status_code 500 and the description of the problem in error.

You can connect the output to components that read data, such as JQ Query (Parse JSON) or Get Value By Key, or hand it to an agent. The component can also be used as an agent tool with Tool Mode.

Example

An online store wants its assistant to report on a shipment’s status.

1. Add API Request to the flow.
2. In URLs, enter the shipment lookup address your carrier gives you.
3. Leave Method as GET.
4. In Headers, add the access key the carrier gave you, as its documentation describes.
5. In Query Parameters, add the order’s tracking number.
6. Connect the Data output to the agent that serves customers, so it answers with the real shipment status.

Good practices

• Check status_code before using the answer. A failed call does not stop the flow: it returns the code and the error so you can decide what to do.
• Store access keys as secret variables in an environment instead of typing them into every flow.
• If the service is slow to answer, raise Timeout.
• Start by pasting the curl example from the service’s documentation into Curl: it saves you typing mistakes.

Related components

• URL: to read the content of a web page.
• Webhook Input: for the opposite case, when the other service calls your flow.
• JQ Query (Parse JSON): to keep only the part of the answer you need.