Support

Service/API thinklet

The Service/API thinklet supports the following connector credential types:

Basic

Bearer

OAuth 2.0 - Client Credentials

OAuth 2.0 - Authorization Code

No Auth

The Service/API thinklet makes a REST call to an external public API. Use it to retrieve additional information or request actions to be performed.

The Service/API thinklet supports the following call methods:

  • GET

  • POST

  • PATCH

  • PUT

  • DELETE

The supported payload and response for the Service/API Thinklet are in JSON format.

  • Name: Enter a unique name for the Service/API thinklet.

  • ID: The system generates the ID automatically based on the name.

  • Description (optional): Describe the purpose of the thinklet and what it does. This information is useful for other users of the workflow who may not be familiar with it.

  • Credentials: Select the connection credentials for the integration. You must configure them first on the Connector credentials page of the Administration module.

  • Request Method: Select the request connection method.

  • Resource: Enter the endpoint for the connection.

  • Add custom header: Add up to 5 custom headers to pass additional metadata if required. You must add authorization headers in Credentials instead.

  • Payload: Enter the JSON payload to be sent to the external system.

  • Choose parsing language for JSON to effectively collect data from API call responses.

All expressions within a single Service/API thinklet should use the selected parsing language for JSON.

Collecting data from API calls

From the Service/API thinklet configuration, select a supported parsing language for JSON to collect data from API call responses from an external system:

  • JSONata (recommended): This is a powerful query and transformation language for JSON. It allows for complex filtering, calculations, and data restructuring.

  • JSONPath: This is a simpler language for extracting fields from JSON. It is commonly used where the system expects straightforward data access paths.

The Service/API thinklet waits up to 10 seconds for a response from the external system before considering the call a failure.

The response from the external system must not exceed 2 MB, regardless of the Service/API thinklet output configuration.

Output configuration

The system supports up to 5 outputs per thinklet.

The maximum output size is 30 KB or 3840 characters.

After choosing parsing language for JSON for the Service/API thinklet, define the data output settings:

  1. Click the Add output button.

  2. Provide a reference Name to use in conditions and thinklet inputs.

  3. Define the expression for data selection and transformation using the selected JSON syntax.

Find below expression examples—in JSONPath and JSONata—to extract data from the following API sample response:

 {
  "result": { "number": "INC001" },
  "value": [
    { "displayName": "Alice", "id": 1, "number": 50 },
    { "displayName": "Bob", "id": 2, "number": 120 }
  ],
  "@meta": { "key.with.dots": "yes" }
}
JSONPath expression examples for outputs

Use these expression examples to extract specific data from the API responses.

Use Case
Expression - JSONPatch
Results for API sample response from aboved

Root element

$.

(entire JSON)

Access a key

$.result

{ "number": "INC001" }

Access nested element

$.result.number

"INC001"

First array element

$.value[0].displayName

"Alice"

Special characters in key

$['@meta']['key.with.dots']

"yes"

JSONata expression examples for outputs

Use these expression examples to extract specific data from the API responses.

Use Case
Expression - JSONata
Results for API sample response from aboved

Access a top-level key

result

{ "number": "INC001" }

Access a nested element

result.number

"INC001"

First item in array

value[0].displayName

"Alice"

Filter by condition

value[number > 100].displayName

[ "Bob" ]

Map and transform

value.{ "name": displayName, "id": id }

[ { "name": "Alice", "id": 1 }, { "name": "Bob", "id": 2 } ]

Perform computation

value[0].number * 100

5000

Aggregate

sum(value.number)

170

Use an online converter tool to parse JSONPath or JSONata during testing.

Using database and workflow values in payloads

Reference the data of users and devices along with data collected during the execution of the workflow in the Resource and Payload fields.

Refer to the Parameters and dynamic values documentation for more details on how to reference dynamic values.

Last updated

Was this helpful?