Call an outside API

This guide is for authors whose automation needs to read from or write to another system over HTTP. It uses the HTTP Request block, which handles REST, JSON, XML and text APIs. For SOAP services use SOAP Request.

1. Add a connection

If the API needs authentication, store it as a connection first, so the secret never appears in the automation.

Open Connections and click New connection.
Under APIs and authentication, pick the kind the API uses, such as an API key, a bearer token or basic authentication. Under OAuth, pick a kind for APIs that use OAuth, including those where you sign in through the provider.
Fill it in and save it.

2. Add the block

In the editor, add HTTP Request after the block that has the data you need, and connect them. In its Setup tab:

Destination URL: the full address. Type @ to insert values from earlier blocks, such as an order number in the path.
Method: GET by default. GET and HEAD send no body.
Connection: the connection from step 1. Lainstack adds its authentication to the request. Never put secrets in the URL, headers or body.
Headers: any extra headers. Values can be typed or mapped.
Body format and the body: JSON by default, or text or XML. A JSON body is built like a Define Value block: add fields with a key, a type and a value, choose List for an array, or type @ to send one earlier value as the whole body. A list can send a Whole list from an earlier block, Fixed entries you add by hand, or For each: pick a list, then map one entry’s fields from that list’s current item, shown as chips such as Packages item › Description. For each takes up to 1,000 items, and one item that cannot be built stops the block before anything is sent. Text and XML bodies are typed, with @ for values. To send JSON that is already built, use Text and add a Content-Type header. Text bodies show in full in the run, so prefer a built body when a field is sensitive.
Schema: for a JSON body, Import JSON Schema fills in the fields from a schema file the API publishes. Keys and types are then fixed, required fields are always there, and + adds optional ones. A body that does not match is not sent, and the block fails. Rules the file has that Lainstack cannot check are listed under the import. A file with a required field it cannot read is refused. Clear keeps your fields and makes them editable again. For an XML body, Upload XSD takes a schema file, a .zip or several .xsd files, and Root element picks the document to send. The fields work the same way, Lainstack writes the XML, and a body that does not match the XSD is not sent, in a draft run as well. An XSD too large for these fields is refused and the message names the field. Without an XSD, Clear empties the fields, because an XML body is then a text template.
Timeout: 5 seconds by default, up to 120 seconds.

Only public http and https addresses work, and redirects are not followed.

3. Read the response

Set Response parsing to match what the API returns: JSON (the default), text or XML.

For JSON, describe the response in Response fields, or import a JSON Schema file to fill them in. The parsed Response body then has typed fields that later blocks can map with @. A response that does not match the schema fails the block, so a changed API is caught at once instead of passing bad data on.

The block also outputs the Status, the raw Response text and the response headers. Values that look like credentials are redacted.

4. Handle errors

By default any status outside 200 to 299 fails the block, and the run fails with it. The request is not retried.

To handle errors yourself, turn off Fail on HTTP error. The block gets an HTTP error exit that receives the full response. Wire it to what should happen instead: a Condition on the status, an approval, or a log entry.

With Fail on HTTP error off, an error response takes its own exit instead of failing the run.

Each request carries an automatic Idempotency-Key header, so APIs that support it can ignore duplicates.

5. Test it

Click Run draft. A GET or HEAD calls the real API. Any other method is held: nothing is sent, and the run shows what the block would have sent. The blocks after it run on its pinned sample, or else its last real output; with neither, the branch stops there. To check a call that writes, publish and run it once against a test account of the API, then use Capture from last run to keep that response as the sample.

Send data to another system

A first push usually sends a few values from earlier blocks to an API that creates a record:

Add HTTP Request where the data is ready, such as after a check or an approval.
Enter the Destination URL, set Method to POST, and pick the Connection.
Leave Body format on JSON. Add a field for each value the API expects, give it a key and a type, and type @ to map its value. If the API publishes a JSON Schema, Import JSON Schema fills in the fields for you.
Set Response parsing and describe the response, so later blocks can use what the API sends back, such as a new record’s reference.
Decide what a refusal should do: fail the run, or turn off Fail on HTTP error and handle it on the HTTP error exit.
Check the body with Run draft. The request is held, and the run shows what the block would have sent.
Publish and run it once against a test account of the API. That is the real test.

An HTTP Request block's settings for sending an entry to a customs broker: a destination URL, the POST method, a bearer token connection and a JSON body with fields mapped from earlier blocks.

If a person may correct the data first, map the body from the Approval block’s Reviewed data, so the corrections are sent. A resumed or replayed run sends the request again, and the Idempotency-Key header only helps if the API supports it.