REST API Component

The REST API component lets your workflow talk to other systems, either to fetch information from them or to send information to them. It works with any system that has a web address you can send requests to (a "REST API").

---

Settings

Connection

Turn on Use connection if the target system needs you to log in, then pick a saved Connection from the Connection dropdown that appears.

Leave Use connection off if the system doesn't need one — for example, a public API with no authentication. No connection is required in that case.

Endpoint URL

The web address to call, e.g. https://api.example.com/orders.

HTTP Method

What you want to do:

Method	Use it to
get	Fetch data
post	Create something new
put	Replace something that exists
patch	Change part of something that exists
delete	Remove something

The documentation for the system you're connecting to tells you which method to use.

Headers

Extra information sent with the request, such as which data format you expect back. Select Add header, then fill in a Key and Value for each one. Use the trash icon to remove a row. Headers are optional.

Request body

Only used when sending data (typically with post, put or patch). Choose one of the two tabs:

• Body path — reference data from an earlier step instead of typing it by hand. Enter a JSONata expression, such as $ to send everything the previous step returned, or a field name like order to send just that part.
• Body — type the data to send directly.

---

Using data from earlier steps

Wrap a value in {{ }} to fill it in from an earlier step when the workflow runs.

In Endpoint URL specifically, always use triple braces {{{ }}} instead of double braces. The templating language was originally built for websites, so double braces HTML-encode the value (for example, turning & into &), which can silently corrupt the URL. Triple braces output the raw value instead.

For example, if the previous step returned an order with an orderId, you could set Endpoint URL to:

https://api.example.com/orders/{{{ body.orderId }}}

This works in Endpoint URL (triple braces), Headers, Body, and Connection (double braces). Connection behaves differently when combined with For each — see For each.

It works the same way in a header's Value. For example, to pass an order's warehouse code as a custom header, add a header with:

Key	Value
x-warehouse-code	{{ body.warehouseCode }}

Write	To get
{{ body.fieldName }}	A field from the previous step's result
{{ header.fieldName }}	A header from the previous step
{{ $context.tenant.tenantId }}	Your company's ID in Vince Platform
{{ $context.user.userId }}	The user who started the workflow
{{ $context.runtime.variables.name }}	A variable from the environment the workflow runs in
{{ $context.runtime.connections.name }}	A connection chosen by the environment. This lets one workflow use different logins in test and production.

Using one of these in Endpoint URL? Use triple braces there instead, e.g. {{{ body.fieldName }}}.

---

What the step returns

The next step receives:

• statusCode: a number in the 200s if it worked, such as 200 or 201. 400 and above means something went wrong. For example, 404 means not found, and 401 means the login failed. Redirects (301, 302 and so on) are followed automatically, so you get the status code of the final response, not the redirect.
• body: the data the system sent back.
• headers: extra information the system sent back.

If the request fails, the workflow keeps running. The step returns the error code, and the system's error message goes in body.

---

Working with files

Downloading a file

To download a file such as a PDF or an image, add a header with the file type. The file is saved to the workflow automatically, and later steps can use it.

Under Headers, add:

Key	Value
accept	application/pdf
content-disposition	attachment; filename="invoice-42.pdf"

The content-disposition value decides what is passed on to the next step:

content-disposition	Next step receives
attachment	Only the saved file. Recommended, especially for large files.
inline	The saved file and the file contents
base64	The saved file and the file contents as text. Use this when you want to upload the file somewhere else later in the workflow.

Add filename="..." to choose the file name, as in the example above.

You can build the file name dynamically with {{ }}, using data from an earlier step. For example, to name the file after the order it belongs to:

Key	Value
content-disposition	attachment; filename="invoice-{{ body.orderId }}.pdf"

Uploading a file

To upload a file you downloaded earlier with base64, set the Body path to the field holding that file (e.g. body), then go to Advanced and tick Send base64 encoded data as binary. This turns the text back into the original file before sending it. You also need to set the file type via a content-type header.

---

Advanced settings

Select Advanced in the editor to see these. Most workflows don't need them.

Version

Component version. Use version 3.

Send base64 encoded data as binary

Tick this when the body holds a file stored as text (base64), for example from a download that used content-disposition: base64. The text is turned back into the original file before it's sent. See Uploading a file.

Skip if expression

A JSONata expression that, if it evaluates to true, skips this step. For example, skip it when the previous step returned no orders:

$count(body.orders) = 0

When the step is skipped it returns statusCode 204 and an empty body.

For each

If the previous step returned a list (for example, 50 orders), set For each to make one request per item instead of one request for the whole list.

Set For each to where the list is in the previous step's result, e.g. body.orders.

Example

Say the previous step returned this:

{
  "orders": [
    { "id": "1001", "customer": "Acme Ltd", "amount": 250 },
    { "id": "1002", "customer": "Nordic AS", "amount": 120 }
  ]
}

And the REST API step is set up like this:

Setting	Value
HTTP Method	post
Endpoint URL	https://api.example.com/orders/{{{ body.id }}}
For each	body.orders
Request body → Body path	$

The step then makes two requests, one per order:

Request	Sent to	Data sent
1	https://api.example.com/orders/1001	{ "id": "1001", "customer": "Acme Ltd", "amount": 250 }
2	https://api.example.com/orders/1002	{ "id": "1002", "customer": "Nordic AS", "amount": 120 }

What body means inside the loop

With For each set, body no longer means the whole result from the previous step. It means the one item being processed right now:

You write	Without For each	With For each: body.orders
{{{ body.id }}} in Endpoint URL	id in the previous step's result	id of the current order (1001, then 1002)
{{ body.customer }}	customer in the previous step's result	customer of the current order
Body path: $	Sends the whole previous result	Sends the current order only
Body path: customer	Sends customer from the previous result	Sends only the current order's customer
{{ header.name }}	A header from the previous step	Same: headers are not affected by For each
{{ }} in Connection	Resolved once, from the previous step's result	Not supported: Connection is resolved once for the whole step, for all requests it makes — it can't reference the current item and doesn't change per item

You can also build the data to send yourself, using fields from the current item. Switch to the Body tab (instead of Body path) and enter:

{
  "orderNumber": "{{ body.id }}",
  "total": "{{ body.amount }}"
}

with Endpoint URL set to https://api.example.com/invoices, HTTP Method to post, and For each to body.orders.

What the step returns

Instead of one result, the step returns a list of results, one per item, in the same order as the original list. Each result has its own statusCode, body and headers, so if one request fails, the others still go through.

[
  { "statusCode": 200, "body": { }, "headers": { } },
  { "statusCode": 404, "body": { "message": "Order not found" }, "headers": { } }
]

If the list is empty or doesn't exist, the step makes a single normal request as if For each wasn't set. To skip the request instead, use Skip if expression.

Parallel executions

Appears once For each is set. Number of concurrent requests to run in parallel (max 20). A higher number is faster, but check first that the other system can handle it.

---

Further reading

• Connections: save logins for the REST API component
• M3 API: if you're connecting to Infor M3, use this component instead